path_stack 0.0.1+1

A Stateful Stack that uses string paths as keys.

path_stack

A stack that uses string based paths as it's keys. Supports nesting of child Widgets, and custom animations when switching paths.

Because this is based on IndexedStack, state can (optionally) be maintained for all child entries. This means that Scrollers, Textfields and Animations are all retained as you are changing paths.

🔨 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