routed_widget_switcher 2.0.0

routed_widget_switcher: ^2.0.0 copied to clipboard

Features #

Declaratively switch child widgets based on the current Router location.

class SideBar extends StatelessWidget {
    Widget build(_){
     return RoutedSwitcher(
        builders: (info) => [
            Routed('/', () => MainMenu()), // use a closure
            Routed('/dashboard', DashboardMenu.new), // or a tear-off :)
        ]);
    }
}

Intended as a complimentary package for any Router (aka Nav2) implementation. Including popular routing solutions like GoRouter, RouteMaster or VRouter.

This is useful in 2 primary use cases:

• when you have scaffolding around your Navigator, like a SideBar or a TitleBar and you would like it to react to location changes
• when multiple paths resolve to the same Page and you want to move subsequent routing further down the tree

Note: This package does not provide any control of the routers location, it simply reads the current location and responds accordingly.

🔨 Installation #

dependencies:
  routed_widget_switcher: ^2.0.0

🕹️ Usage #

Place the widget anywhere below the root Router widget and define the paths you would like to match. By default paths are considered to be case-insensitive, and treated as prefixes, but this can be disabled:

return RoutedSwitcher(
  caseSensitive: true,
  builders: [
    // use '.exact' to match only '/'
    Routed('/', MainMenu.new).exact,
     // allow anything prefixed with `/dashboard`
    Routed('/dashboard', DashboardMenu.new),
  ],
);

Uknown routes

Use the unknownRouteBuilder to handle unexpected routes. If the delegate is not provided, a DefaultUnknownRoute widget will be used.

Path matching #

Paths can be defined as simple strings like /user/new or user/:userId, or use regular expression syntax like r'/user/:id(\d+)'. See pathToRegExp library for more details on advanced use cases: https://pub.flutter-io.cn/packages/path_to_regexp.

In addition to the matching performed by pathToRegExp, a wildcard * character can be used to match any location.

Most specific match #

RoutedSwitcher will attempt to use the most specific match. For example,the location of /users/new matches all three of these builders:

Routed('/users/:userId', builder: (_) => const TeamDetails()),
Routed('/users/new', builder: (_) => const NewTeamForm()),
Routed('*', builder: (_) => const PathNotFound()),

Since /users/new is the more exact match, it will be the one to render, it does not matter which order you declare them in. /users/:userId would go next, with the wildcard * finally matching last.

Reading route info #

You can use RoutedInfo.of(context) to fetch the closest RoutedInfo, which exposes:

• url
• matchingRoute
• pathParams
• queryParams

Transitions #

Internally Flutters AnimatedSwitcher widget is used for transitions, so that full API is exposed for different transition effects.

return RoutedSwitcher(
  transitionBuilder: ...
  duration: ...,
  builders: ...,
)

Relative links and incd exaheritence #

Nested switchers are supported to any depth, and relative paths can be defined by omitting the '/' character.

return RoutedSwitcher(
  builders: (_) => [
    Routed(
      '/messages',
      () => RoutedSwitcher(
        builders: (_) => [
          Routed('', Inbox.new), // -> /messages/
          Routed('inbox', Inbox.new), // -> /messages/inbox
          Routed('outbox', Outbox.new), // -> /messages/outbox
        ],
      ),
    ),
  ],
);

🐞 Bugs/Requests #

If you encounter any problems please open an issue. If you feel the library is missing a feature, please raise a ticket on Github and we'll look into it. Pull request are welcome.

📃 License #

MIT License