sailor 0.4.0 copy "sailor: ^0.4.0" to clipboard
sailor: ^0.4.0 copied to clipboard

outdated

Easily manage page navigation in Flutter apps. Add page transition animations, log navigation events.

sailor #

anchor_image

License: MIT pub_package

A Flutter package for easy navigation management.

Warning: Package is still under development, there might be breaking changes in future.

Roadmap #

  • Core Navigation Features.
  • Proper logging when navigating.
  • Basic Transitions and configuration.
  • More inbuilt transitions.
  • Pretty printing navigation stack.

Index #

Setup and Usage #

  1. Create an instance of Sailor and add routes.
// Routes class is created by you.
class Routes {
  static final sailor = Sailor();

  static void createRoutes() {
    sailor.addRoute(SailorRoute(
        name: "/secondPage",
        builder: (context, args, params) {
          return SecondPage();
        },
      ));
  }
}
  1. Register the routes in onGenerateRoute using the generate function of Sailor and also Sailor's navigatorKey.
class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Sailor Example',
      home: Home(),
      navigatorKey: Routes.sailor.navigatorKey,
      onGenerateRoute: Routes.sailor.generator(),
    );
  }
}
  1. Make sure to create routes before starting the application.
void main() async {
  Routes.createRoutes();
  runApp(App());
}
  1. Use the instance of Sailor to navigate.
Routes.sailor.navigate("/secondPage");
  • TIP: Sailor is a callable class, so you can omit navigate and directly call the method.
Routes.sailor("/secondPage");

Passing parameters #

Sailor allows you to pass parameters to the page that you are navigating to.

  • Before passing the parameter itself, you need to declare it while declaring your route. Let's declare a parameter named id that has a default value of 1234.
sailor.addRoutes([
  SailorRoute(
    name: "/secondPage",
    builder: (context, args, params) => SecondPage(),
    params: [
      SailorParam(
        name: 'id',
        defaultValue: 1234,
      ),
    ],
  ),
);
  • Pass the actual parameter when navigating to the new route.
Routes.sailor.navigate<bool>("/secondPage", params: {
  'id': 4321,
});
  • Parameters can be retrieved from two places, first, the route builder and second, the opened page itself.

Route Builder:

sailor.addRoutes([
  SailorRoute(
    name: "/secondPage",
    builder: (context, args, params) {
      // Getting a param
      final id = params.param<int>('id');
      return SecondPage();
    },
    params: [
      SailorParam(
        name: 'id',
        defaultValue: 1234,
      ),
    ],
  ),
);

Opened page:

class SecondPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final id = Sailor.param<int>(context, 'id');

    ...

  }
}

Passing Arguments #

Sailor allows you to pass arguments to the page that you are navigating to.

  • Create a class that extends from BaseArguments.
class SecondPageArgs extends BaseArguments {
  final String text;

  SecondPageArgs(this.text);
}
  • When calling the navigate method pass these arguments.
final response = Routes.sailor.navigate(
  "/secondPage",
  args: SecondPageArgs('Hey there'),
);
  • When in the SecondPage, use Sailor.arguments to get the passed arguments.
class SecondPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final args = Sailor.args<SecondPageArgs>(context);

    return Scaffold(
      appBar: AppBar(
        title: Text('Compass Example'),
      ),
      body: Center(
        child: Text(args.text),
      ),
    );
  }
}

Transitions #

Sailor has inbuilt support for page transitions. A transition is specified using SailorTransition.

Transition can be specified at 3 levels (ordered in priority from highest to lowest):

  • When Navigating (using Sailor.navigate).
  • While adding routes (SailorRoute).
  • Global transitions (SailorOptions).

When navigating #

Specify which transitions to use when calling the navigate method.

Routes.sailor.navigate(
  "/secondPage",
  transitions: [SailorTransition.fade_in],
);

More than one transition can be provided when navigating a single route. These transitions are composed on top of each other, so in some cases changing the order will change the animation.

Routes.sailor.navigate(
  "/secondPage",
  transitions: [
    SailorTransition.fade_in,
    SailorTransition.slide_from_right,
  ],
  transitionDuration: Duration(milliseconds: 500),
  transitionCurve: Curves.bounceOut,
);

Duration and Curve can be provided using transitionDuration and transitionCurve respectively.

Routes.sailor.navigate(
  "/secondPage",
  transitions: [
    SailorTransition.fade_in,
    SailorTransition.slide_from_right,
  ],
  transitionDuration: Duration(milliseconds: 500),
  transitionCurve: Curves.bounceOut,
);

In the above example the page will slide in from right with a fade in animation. You can specify as many transitions as you want.

When adding routes #

You can specify the default transition for a route, so you don't have to specify it again and again when navigating.

sailor.addRoute(SailorRoute(
  name: "/secondPage",
  defaultTransitions: [
    SailorTransition.slide_from_bottom,
    SailorTransition.zoom_in,
  ],
  defaultTransitionCurve: Curves.decelerate,
  defaultTransitionDuration: Duration(milliseconds: 500),
  builder: (context, args) => SecondPage(),
));

Priority: Transitions provided in Sailor.navigate while navigating to this route, will override these transitions.

Global transitions #

You can specify default transition to be used for all routes in Sailor.

SailorOptions(
  defaultTransitions: [
    SailorTransition.slide_from_bottom,
    SailorTransition.zoom_in,
  ],
  defaultTransitionCurve: Curves.decelerate,
  defaultTransitionDuration: Duration(milliseconds: 500),
)

Priority: Transitions provided while adding a route or when navigating using navigate, will override these transitions.

Pushing Multiple Routes #

Sailor allows you to push multiple pages at the same time and get collected response from all.

final responses = await Routes.sailor.navigateMultiple(context, [
  RouteArgsPair("/secondPage", SecondPageArgs("Multi Page!")),
  RouteArgsPair("/thirdPage", ThirdPageArgs(10)),
]);

print("Second Page Response ${responses[0]}");
print("Third Page Response ${responses[1]}");

Log Navigation #

Use SailorLoggingObserver to log the push/pop navigation inside the application. Add the SailorLoggingObserver to the navigatorObservers list inside your MaterialApp.

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Compass Example',
      home: Home(),
      onGenerateRoute: Routes.sailor.generator(),
      navigatorObservers: [
        SailorLoggingObserver(),
      ],
    );
  }
}

Once added, start navigating in your app and check the logs. You will see something like this.

flutter: [Sailor] Route Pushed: (Pushed Route='/', Previous Route='null', New Route Args=null, Previous Route Args=null)
flutter: [Sailor] Route Pushed: (Pushed Route='/secondPage', Previous Route='/', New Route Args=Instance of 'SecondPageArgs', Previous Route Args=null)
flutter: [Sailor] Route Popped: (New Route='/', Popped Route='/secondPage', New Route Args=null, Previous Route Args=Instance of 'SecondPageArgs')

Support #

If you face any issue or want a new feature to be added to the package, please create an issue. I will be more than happy to resolve your queries.

129
likes
0
pub points
77%
popularity

Publisher

unverified uploader

Easily manage page navigation in Flutter apps. Add page transition animations, log navigation events.

Homepage

License

unknown (LICENSE)

Dependencies

flutter

More

Packages that depend on sailor