voyager 0.4.1

banner

pub package

To boldly resolve where no Dart has resolved before.

Router, requirements & dependency injection library for Flutter.

Features #

If your app is a list of screens with respective paths then this library is for you.

  • YAML/JSON based Navigation Spec
    • support for query parameters
    • support for global parameters
    • path subsections
    • parameters interpolation in subsections
    • logicless
    • deliverable over the air (think Firebase remote config)
    • code generator for paths (COMING SOON)
  • Highly customizable plugin architecture.
  • VoyagerWidget to embed your path at any point
  • Provider to inject any data coming with the path

Getting started #

To use this plugin, add voyager as a dependency in your pubspec.yaml file.

You should ensure that you add the router as a dependency in your flutter project.

dependencies:
 voyager: "^0.3.0"

You can also reference the git repo directly if you want:

dependencies:
 voyager:
   git: git://github.com/vishna/voyager.git

Then in the code, make sure you import voyager package:

import 'package:voyager/voyager.dart';

It’s best to start with describing what paths your app will have and what subsections will they be made of.

---
'/home' :
  type: 'home'
  screen: HomeWidget
  title: "This is Home"
'/other/:title' :
  type: 'other'
  screen: OtherWidget
  title: "This is %{title}"

You can either put this in assets as a yaml file or use triple quotes ''' and keep it in your code as a string. The String approach while a bit uglier allows for faster reloads while updating assets requires project rebuild.

Creating Router Instance #

Your router requires paths and plugins as constructor parameters. Getting paths is quite straightforwad and basically means parsing that YAML file we just defined.

final paths = loadPathsFromString('''
---
'/home' :
  type: 'home'
  screen: HomeWidget
  title: "This is Home"
'/other/:title' :
  type: 'other'
  screen: OtherWidget
  title: "This is %{title}"
''');

or if the file is in the assets folder, you can:

final paths = loadPathsFromAssets("assets/navigation.yml");

NOTE: JSON support is available as of version 0.2.3, please check voyager_test.dart for reference.

The other important ingredient of voyager router are plugins. You need to tell router what kind of plugins you plan to use and those depend on what you have written in the navigation file. In our example we use 3 type, screen and title. This library comes with predefined plugins for type & screen and we'll create our own plugin for title.

final plugins = [
  [
    TypePlugin(),
    ScreenPlugin({ // provide widget builders for expressions used in YAML
      "HomeWidget": (context) => HomeWidget(),
      "OtherWidget": (context) => OtherWidget(),
    }),
    TitlePlugin()
  ]
];

Now you're all set for getting your router instance:

Future<RouterNG> router = loadRouter(paths, plugins)

Custom Plugins #

You can define as many plugins as you want. Here's how you could handle the title nodes from the example navigation yaml.

class TitlePlugin extends RouterPlugin {
  TitlePlugin() : super("title"); // YAML node to intercept

  @override
  void outputFor(RouterContext context, dynamic config, Voyager voyager) {
    // config can be anything that is passed from YAML
    voyager["title"] = config.toString(); // output of this plugin
  }
}

NOTE: Above plugin is redundant, Voyager will repackage the primitive types from configuration and you don't need to do anything 😎 Use plugins to resolve primitive types to custom types , e.g. take a look at IconPlugin from the example app.

Router's Default Output: Voyager #

Voyager instance is the composite output of all the relevant plugins that are nested under the path being resolved. Observe:

Voyager voyager = router.find("/home")
print(voyager["title"]); // originates from the title plugin, prints: "This is home"
print(voyager["type"]); // originates from the type plugin, prints: "home"
assert(voyager["screenBuilder"] is WidgetBuilder); // originates from the screen plugin

NOTE: Any attempt to modify voyager keys will fail unless done from plugin's outputFor method. If you want to add some values to Voyager later on, use Voyager.storage public map.

Embed any screen path with VoyagerWidget #

If your path uses screen plugin you can try using VoyagerWidget and embed any path you want like this:

VoyagerWidget(path: "/home", router: router);

NOTE: You can even omit passing router instance if this VoyagerWidget is nested within other VoyagerWidget.

Inject your information via Provider #

If you use VoyagerWidget to create screens for your paths, you can obtain Voyager anywhere from BuildContext using Provider:

final voyager = Provider.of<Voyager>(context);

Now going back to our mystery OtherWidget class from the example navigation spec, that widget could be implemented something like this:

class OtherWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final voyager = Provider.of<Voyager>(context); // injecting voyager from build context
    final title = voyager["title"]; // assuming title plugin worked and title is here 🙈

    return Scaffold(
      appBar: AppBar(
        title: Text(title), // et voilà
      ),
      body: Center(
        child: Text("Other Page"),
      )
    );
  }
}

Integrating with MaterialApp #

Defining inital path & handling navigation

final initalPath = "/my/fancy/super/path"

MaterialApp(
  home: VoyagerWidget(path: initalPath, router: router),
  onGenerateRoute: router.generator()
)

NOTE: You can use MaterialApp.initalRoute but please read this first if you find MaterialApp.initalRoute is not working for you. TL;DR: It's working as intended ¯\_(ツ)_/¯

Having BuildContext and Material.onGenerateRoute set up, you can simply:

Navigator.of(context).pushNamed("/path/to/go");

If you need to push new screen from elsewhere you probably should set navigatorKey to your MaterialApp

Custom Transitions #

The article "Create Custom Router Transition in Flutter using PageRouteBuilder" by Agung Surya explains in detail how to create custom reusable transtions.

Essentially you need to extend a PageRouteBuilder class and pass it a widget you want to be transitioning to. In our case that widget is a VoyagerWidget.

In the aforementioned artile, the author created SlideRightRoute transition. We can combine that transition with any path from our navigation spec by using code below:

Navigator.push(
  context,
  SlideRightRoute(widget: VoyagerWidget.fromPath(context, "/path/to/go")),
);

Adding global values #

If you want to expose some global parameters to specs interpolation, you can do so by doing the following:

router.registerGlobalParam("isTablet", false);

NOTE: Because we interpolate String here, only primitve types are allowed.

If you want to make some global entities available via router instance, you can do so by doing the following:

router.registerGlobalEntity("database", someDatabase);

Sample App #

voyager_edited

Check out full example here

Code generation #

Voyager supports generating dart code based on the configuration yaml file. Simply run the following command and wait for the script to set it up for you.

flutter packages pub run voyager:codegen

This should create a voyager-codegen.yaml file in a root of your project, like so:

- name: Voyager # base name for generated classes, e.g. VoyagerPaths, VoyagerTests etc.
  source: assets/navigation.yaml
  target: lib/gen/voyager_gen.dart

Whenever you edit the voyager-codegen.yaml or source file the code generation logic will pick it up (as long as pub run is running) and generate new dart souces to the target location.

NOTE 1: For code generator implementation details please check the source code at vishna/voyager-codegen.

NOTE 2: Should you want run code generation only once (and not watch files continously) you can supply additional --run-once flag to pub run command:

flutter packages pub run voyager:codegen

This can be useful if running in a CI/CD context.

NOTE 3: You might want to add .jarCache/ to your .gitignore to avoid checking in binary jars to your repo.

NOTE 4: If you're a Windows user make sure you have wget installed.

Strong Typed Paths #

Typing navigation paths by hand is error prone, for this very reason it is recommended to use code generator for the paths, so rather than typing:

Navigator.of(context).pushNamed("/other/thingy");

you can rely on your IDE's autocompletion and do this:

Navigator.of(context).pushNamed(VoyagerPaths.pathOther("thingy"));

More Resources #

Acknowledgments #

  • fluro As their repo says: "The brightest, hippest, coolest router for Flutter." Probably the most know flutter router out there.
  • angel-route "A powerful, isomorphic routing library for Dart." Voyager internally was depending on this library till version 0.2.3. It was a server oriented library and too big dependency for this project - voyager is now using abstract_router.dart which is < 300 LOC.
  • eyeem/router Protoplast of the voyager library, written in Java, for Android.
  • NASA Voyager 2 Interstellar Poster Beautiful artwork I found on NASA page also a base content for the banner - changed colors to flutter ones, cropped the poster, added flutter antenna.

0.4.1 #

  • package health

0.4.0 #

  • code generation for paths, simply run flutter packages pub run voyager:codegen at the top of your flutter project and behold!

0.3.0 #

0.2.3 #

  • json support

0.2.2 #

  • formatting

0.2.1 #

  • fixes around how VoyagerWidget reacts to hot reload
  • improve sample app
  • add a sample app gif to README

0.2.0 #

API DEPRECATION

  • VoyagerProvider is being phased out. Internally Voyager will depend on provider more popular within the community.

Migration:

  • change VoyagerProvider.of(context) to Provider.of<Voyager>(context)
  • change VoyagerProvider.routerOf(context) to Provider.of<RouterNG>(context)

0.1.1 #

  • Package health fixes

0.1.0 #

  • Initial release

example/lib/main.dart

import 'package:example/gen/voyager_gen.dart';
import 'package:flutter/material.dart';
import 'package:voyager/voyager.dart';
import 'package:provider/provider.dart';

String requirements() {
  return '''
---
'/home' :
  type: 'home'
  screen: PageWidget
  title: "This is Home"
  body: "Hello World"
  fabPath: /fab
'/other/:title' :
  type: 'other'
  screen: PageWidget
  body: "Welcome to the other side"
  title: "This is %{title}"
'/fab' :
  type: fab
  screen: FabWidget
  target: /other/thing
  icon: e88f # check icons.dart for reference
''';
}

Future<List<RouterPath>> paths() {
  return loadPathsFromString(requirements());
}

/// plugins that are mentioned in requirements
final plugins = [
  TypePlugin(),
  ScreenPlugin({
    // provide widget builders for expressions used in YAML
    "PageWidget": (context) => PageWidget(),
    "FabWidget": makeMeFab
  }),
  IconPlugin()
];

class IconPlugin extends RouterPlugin {
  IconPlugin() : super("icon");

  @override
  void outputFor(RouterContext context, config, Voyager output) {
    output["icon"] = Icon(IconData(int.parse(config.toString(), radix: 16),
        fontFamily: 'MaterialIcons'));
  }
}

void main() {
  // wrapped with a builder, otherwise hot reload doesn't quite click
  runApp(Builder(builder: (builder) => appOrSplash()));
}

Widget appOrSplash() {
  return FutureBuilder(
      future: loadRouter(paths(), plugins),
      builder: (BuildContext context, AsyncSnapshot snapshot) {
        if (snapshot.hasData && snapshot.data != null) {
          final router = snapshot.data;
          return Provider<RouterNG>.value(
              value: router,
              child: MaterialApp(
                title: 'Voyager Demo',
                home:
                    VoyagerWidget(path: VoyagerPaths.pathHome, router: router),
                theme: themeData(),
                onGenerateRoute: router.generator(),
              ));
        } else {
          return SplashScreen();
        }
      });
}

Widget makeMeFab(BuildContext context) {
  final voyager = Provider.of<Voyager>(context);
  return FloatingActionButton(
    onPressed: () {
      Navigator.of(context).pushNamed(voyager["target"]);
    },
    tooltip: 'Navigate',
    child: voyager["icon"],
  );
}

ThemeData themeData() {
  return ThemeData(
      brightness: Brightness.dark,
      primaryColor: Color(0xff5bb974),
      canvasColor: Colors.black,
      accentColor: Color(0xfffcc934));
}

class PageWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final voyager = Provider.of<Voyager>(context);
    final title = voyager["title"];

    return Scaffold(
        appBar: AppBar(
          title: Text(title),
        ),
        body: Center(
          child: Text(voyager["body"], style: TextStyle(fontSize: 24)),
        ),
        floatingActionButton: voyager["fabPath"] != null
            ? VoyagerWidget(
                path: voyager["fabPath"],
              )
            : null);
  }
}

class SplashScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Center(
        child: Text("Loading",
            style: TextStyle(fontSize: 24), textDirection: TextDirection.ltr));
  }
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  voyager: ^0.4.1

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:voyager/voyager.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
27
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
64
Learn more about scoring.

We analyzed this package on Jul 21, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.4.0
  • pana: 0.12.19
  • Flutter: 1.7.8+hotfix.3

Platforms

Detected platforms: Flutter

References Flutter, and has no conflicting libraries.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.1.0 <3.0.0
flutter 0.0.0
provider ^3.0.0+1 3.0.0+1
sprintf ^4.0.2 4.0.2
yaml ^2.1.16 2.1.16
Transitive dependencies
charcode 1.1.2
collection 1.14.11
meta 1.1.6 1.1.7
path 1.6.2
sky_engine 0.0.99
source_span 1.5.5
string_scanner 1.0.4
term_glyph 1.1.0
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test

Admin