path_stack #

Based on IndexedStack, path_stack uses string-based paths as it's keys, rather than an index.

Supports nesting of child Widgets, custom animations when switching paths and path params.

🔨 Installation #

dependencies:
  path_stack: ^0.0.1

⚙ Import #

import 'package:path_stack/path_stack.dart';

🕹️ Usage #

You can create basic tab-scaffold using simple string as the path, like this:

class _SimpleTabExampleState extends State<SimpleTabExample> {
  PageType _tabType = PageType.Home;
  late String currentPath = "$_tabType";

  @override
  Widget build(BuildContext context) {
    return PathStack(
      path: "$currentPath",
      transitionBuilder: (_, child, anim) => FadeTransition(opacity: anim, child: child), // Optional
      scaffoldBuilder: (_, stack) => TabScaffold(_tabType, child: stack, onTabPressed: _handleTabPressed),
      entries: [
        PathStackEntry(path: "${PageType.Home}", builder: (_, args) => HomePage()),
        PathStackEntry(path: "${PageType.Settings}", builder: (_, args) => SettingsPage()),
        PathStackEntry(path: "${PageType.Explore}", builder: (_, args) => ExplorePage(), maintainState: false),
      ],
    );
  }

  void _handleTabPressed(PageType value) => setState(() => _tabType = value);
}

• PathStack.transitionBuilder - Allows you to provide a custom animation when path is changed
• PathStack.scaffoldBuilder - Allows you to wrap a custom Widget around all entries, typically a tab-menu or an app bar
• PathStack.entries - A list of available paths for this stack, can contain other PathStacks to nest routes and menus
• PathStackEntry.builder - Returns a widget for the defined path, provides args that can be injected into the view
• PathStackEntry.maintainState - Set this to false if you do not want a path to remember it's State.

Defining paths #

path_stack supports both path based args (/details/83) or queryString args (/details?id=83). Under the hood we use path_to_reg_exp so you can look there for details on path parsing.

Path Parsing Rules:

• Paths with no trailing slash must an exact match: /details
  • matches only /details does not match /details/12
• Paths with a trailing slash, will accept a suffix, ie /details/
  • matches both /details/ and /details/12
• To accept a named parameter you can use /details/:id, which will match details/12
  • This can be accessed later in the PathStack.builder using args["id"]

Query string params are also included, and can be accessed from the same args map:

• To accept a named parameter you can use /details?id=12
  • This can be accessed later in the PathStack.builder using args["id"]

Nested Stacks #

path_stack supports easy nesting of stacks using the PathStack.parentPath property combined with the PathStackEntry.builder.

For example, to create a tree like this, using 2 nested stacks:

• /home
• /settings/alerts
• /settings/profile
• /settings/billing

return PathStack(
    path: currentPath,
    entries: [
      PathStackEntry(path: "/home", builder: (_, __) => HomePage("")),
      PathStackEntry(
        path: "/settings/",
        builder: (_, __) {
          return PathStack(
            path: currentPath,
            // Wrap all settings routes in a shared scaffold
            scaffoldBuilder: (_, c) => _SettingsScaffold(body: child),
            // By setting parent path, our sub route 'alerts' will actually match '/settings/alerts`
            parentPath: "/settings/",
            entries: [
              PathStackEntry(path: "alerts", builder: (_, __) => AlertSettings("")),
              PathStackEntry(path: "profile", builder: (_, __) => ProfileSettings("")),
              PathStackEntry(path: "billing", builder: (_, __) => BillingSettings("")),
            ],
          );
        },
      ),
    ],
  );

🐞 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