Captain ⛵️

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 and returns a List which will be the new Page stack for the App

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));