Scenario codes regarding multiple usage approaches

[slovnicki]

I'm wondering how can we best depict and showcase various usage approaches for a package which has many. Of course, it would not be wise to randomly use different usage in each scenario as this may confuse research participants.

For example, beamer has many ways in which it can be used, depending on developer needs. I will point out 2 major differences;

• difference in locationBuilder
• difference in navigating

Difference in locationBuilder

Each BeamerRouterDelegate must receive a locationBuilder, but it can be provided in different ways;

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routeInformationParser: BeamerRouteInformationParser(),
      routerDelegate: BeamerRouterDelegate(
        locationBuilder: // one of below
      ),
    );
  }
}

Simple

Using the SimpleLocationBuilder does not require to define custom BeamLocations and below setup is sufficient for a functioning application.

SimpleLocationBuilder(
  routes: {
    '/': (context) => HomeScreen(),
    '/books': (context) => BooksScreen(),
    '/books/:bookId': (context) => BookDetailsScreen()
  },
),

Almost Fully Custom

Defining custom BeamLocations, but letting beamer decide which to choose.

BeamerLocationBuilder(
  beamLocations: [
    HomeLocation(),
    BooksLocation(),
  ],
),

Fully Custom

Defining custom BeamLocations and deciding which to choose by examining the "root state"

(state) {
  if (state.uri.pathSegments.contains('books')) {
    return BooksLocation(state);
  }
  return HomeLocation(state);
},

Difference in Navigating

Navigating through pages can be done in a declarative or imperative manner, where imperative API will call declarative update under the hood.

Declarative

Updating current location state

Beamer.of(context).currentLocation.update(
  (state) => // create a new state
);

Updating delegate's state (locationBuilder gets executed)

Beamer.of(context).update(
  state: // create a new state
);

Imperative

Most commonly used

Beamer.of(context).beamToNamed('/some/path');

Many more...

Why Such Diversity?

The reason for this diversity is that users have different needs and expectations of an API. Obviously, there's no way to manually control a page stack in SimpleLocationBuilder as one would do in custom BeamLocation's pagesBuilder, but many users simply don't have a need to do it and are satisfied with default page stacking.

nav2-usability/scenario_code

I submitted most of the scenarios using the SimpleLocationBuilder and beamToNamed as it was sufficient for requirements. On one hand, I'm happy with that because it's a very simple way to get users going, but on the other hand I'm sad that participant's won't see "what Pages API is really about" if they don't see pagesBuilder. I did use "full beamer" in one scenario - skipping stacks. Although still not necessary, but skipping stacks is in my opinion the core example for Pages API so I went that way.

My Question

My question to everyone is:

Should/Can we put more than 1 scenario code for a package?
(if there's a situation where many usages are possible)

I don't want this to be extra work for anyone and these additional examples don't need to be studied thoroughly, but just be there if someone asks "Can I do this or that?". It may seem impossible looking just at a single usage, but very possible in others.

[InMatrix]

@slovnicki Thanks for raising this question. The short answer is "Yes," it's beneficial to see variants of scenario implementation as long as the reason for each variation is provided. From a usability standpoint, the issue of having multiple ways of implementing the same scenario is about how easy the API user can make those choices and how reversible those choices are. The goal of this project does put an emphasis on high-level APIs that give the majority of Flutter users what they need for navigation and routing at a potential expense of flexibility and power, which was the design goal of Navigator 2.0 and Router.

Showing the variants of scenario implementations can help us assess a few aspects of API usability we're going to look at in the heuristic evaluation:

• Abstract level: is the abstract level of the API appropriate for the scenario and across the scenarios?
• Premature commitment: is it easy for the user to choose which way to go? If the user needs to switch to a different approach later, how much work is required to reverse their earlier choice?
• Viscosity: similar to the above, once the user adopts a simpler approach, how hard would it be for them to refactor the code in response to a change in requirements?