Captain ⛵️

pub test style

GitHub commit activity GitHub open issues GitHub closed issues Licence

an imperative way to navigate declaratively AKA making it dead simple for you to design complex navigations 🦾😎

🌲 Placing it in the widget tree

place the Captain()widget at the same postition inside your widget tree where your Router or Navigator widget would reside. Best practice is placing the main Router beneath the Material/Cupertino/WidgetsApp like:

MaterialApp(
    home: Captain(
        CaptainConfig([
            PageToShowBeneath(),
            MyBeautifulHomePage(),
        ],),
        // only pages is required
    ),
),

CaptainConfig

EXAMPLE

CaptainConfig(
    // REQUIRED
    [MyStartingPage()],
    // OPTIONAL
    popPage: (routeThatIsGettingPopped, itsResult, pageStack) => pageStack..removeLast(),
    shouldPop: (pageStack) => pageStack.isNotEmpty,
    actions: {
        'removeEverythingAndAddThePages': (pageStack) {
            pageStack.removeAll();
            return pageStack..addAll([
                Page1(),
                Page2(),
            ]);
        }
    }
    initialRouteInformation: RouteInformation(localtion: 'initial'),
    parseRouteInformation: (newRouteInformation, pageStack) {
        if (newRouteInformation.location=='/home' && pageStack.length < 2) {
            return HomePage();
        }
    },
    restoreRouteInformation: (page) {
        if (page is Home) {
            return RouteInformation(location: '/welcomeToHome');
        }
    }
)
Parameter Description Docs
pages the stack of pages the app is built with at first pages
popPage function that is called when a page should be popped - this should usually remove the top-most page of the stack but can behave in any custom way popPage
shouldPop decide on shouldPop
actions map of preconfigured functions that are callable via Navigator.of(context).action('key') actions
initialRouteInformation initial RouteInformation object the app starts with initialRouteInformation
parseRouteInformation function that maps a new incoming RouteInformation to a Page that is added on the stack parseRouteInformation
restoreRouteInformation chooses/restores new RouteInformation object taking the parsed page ☝️ as a parameter restoreRouteInformation

🧭 Navigate with Captain

Captain supports imperative navigation style by complying to the Navigator.of(context) format

USE EITHER:

  • .action(Object actionKey)for invoking predefined actions that have been registered to the Captain Widget
  • .actionFunc(List<Page> Function(List<Page>)) which takes a List

EXAMPLE

// invoke an action defined in actions parameter in CaptainConfig
Navigator.of(context).action("myActionKey");

// directly nvoke a change in the pageStack and return the new pageStack
Navigator.of(context).actionFunc((pageStack) => 
    pageStack..add(pageToAdd));

Libraries

captain