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

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