How to use the RouterNavigator component
The RouterNavigator
class supports navigation between views by integrating with the HTML History API. On other targets, Feathers UI emulates the behavior of the HTML History API to provide a consistent experience across all platforms.
RouterNavigator
is designed for use in web browsers, but it is supported on all platform targets. If your app is not intended for deployment to the web, you might consider usingStackNavigator
instead, which offers more powerful features that are not supported by the HTML History API.
The Basics
Start by creating a RouterNavigator
, and add it to the display list.
var navigator = new RouterNavigator();
this.addChild(navigator);
A view can be a Feathers UI component or any OpenFL display object. The following example creates a simple view with a label.
class HelloView extends LayoutGroup {
public function new() {
super();
var message = new Label();
message.text = "Hello World";
this.addChild(message);
}
}
To add a new view that the navigator can show, create a Route
and pass it to the navigator's addRoute()
method.
var route = Route.withClass("/", HelloView);
navigator.addRoute(route);
The first argument passed to Route.withClass()
is the pathname to use for the view. A pathname must start with a forward slash /
character. /settings
, /
, and /users/list
are all examples of valid pathnames.
The pathname is one of several parts of a URL, as demonstrated in the following table.
protocol hostname port pathname search hash https: www.google.com 443 /search ?q=feathers+ui #nav /search is the pathname for https://www.google.com:443/search?q=feathers+ui#nav.
The second argument is the HelloView
class from earlier. The navigator will automatically create an instance of this class when the view needs to be shown.
The
Route
class defines three static functions for creating items.
withClass()
accepts any subclass ofDisplayObject
. Each time that the view is shown, a new instance of the class will be instantiated.withFunction()
accepts a function that returns a display object. Each time that the view is shown, this function will be called. Using a function can be useful for adding children to a view or setting its properties before showing it in the navigator.withDisplayObject()
accepts an already-instantiated display object. When the view is shown, the same instance will always be reused. This one can allocate a lot of memory if overused, so be careful!
Navigation
In a RouterNavigator
component, navigating to a new view adds a new entry to the web browser's history. When the user navigates back or forward, the page's URL will be updated, and the RouterNavigator
will update the currently displayed view to match.
Navigation may be triggered progammatically by calling functions like push()
and goBack()
on the navigator.
navigator.push("/users/list");
However, the real power of RouterNavigator
comes from using events to trigger navigation.
Navigate with events
The navigator can listen for events dispatched by the active view to automatically trigger navigation to other views. Custom events may be registered with a Route
, and a variety of different actions are available, including the ability to push new locations or to go back in history.
Consider the following two views, ViewA
and ViewB
.
class ViewA extends LayoutGroup {
public static final PATHNAME = "/";
public function new() {
super();
this.layout = new VerticalLayout();
var label = new Label();
label.text = "A";
this.addChild(label);
var button = new Button();
button.text = "Push B";
button.addEventListener(TriggerEvent.TRIGGER, button_triggerHandler);
this.addChild(button);
}
private function button_triggerHandler(event:TriggerEvent):Void {
this.dispatchEvent(new Event(Event.CHANGE));
}
}
ViewA
displays a label with the text "A" and a button with the text "Push B". When the button is triggered, ViewA
dispatches Event.CHANGE
. The pathname of ViewA
is /
.
class ViewB extends LayoutGroup {
public static final PATHNAME = "/b";
public function new() {
super();
this.layout = new VerticalLayout();
var label = new Label();
label.text = "B";
this.addChild(label);
var button = new Button();
button.text = "Go back to A";
button.addEventListener(TriggerEvent.TRIGGER, button_triggerHandler);
this.addChild(button);
}
private function button_triggerHandler(event:TriggerEvent):Void {
this.dispatchEvent(new Event(Event.COMPLETE));
}
}
ViewB
displays a label with the text "B" and a button with the text "Go back to A". When the button is triggered, ViewB
dispatches Event.COMPLETE
. The pathname of ViewB
is /b
.
In the next example, the two views are added to the navigator using their pathnames.
var routeA = Route.withClass(ViewA.PATHNAME, ViewA, [
Event.CHANGE => Push(ViewB.PATHNAME)
]);
navigator.addRoute(routeA);
var routeB = Route.withClass(ViewB.PATHNAME, ViewB, [
Event.COMPLETE => Push(ViewA.PATHNAME)
]);
navigator.addRoute(routeB);
When creating a Route
, a mapping of events to actions may be optionally provided. The available actions are defined on the RouterAction
enum.
In the example above, when ViewA
dispatches Event.CHANGE
, the navigator will create a new history entry for the pathname of ViewB
. The Push()
action accepts the pathname of the view to push. In this case, it's ViewB.PATHNAME
.
Similarly, when ViewB
dispatches Event.COMPLETE
, the navigator will create a new history entry for ViewA.PATHNAME
.
Why does B navigating back to A use
Push()
too? Shouldn't it useGoBack()
instead?Consider how you would create a simple HTML website. You want a.html to link to b.html, so you'd add
<a href="b.html">Push B</a>
. Similarly, if b.html should link to a.html, you'd add<a href="a.html">Go back to A</a>
.Links in HTML don't go backwards. They always add a new history entry. For a Feathers UI app to feel native to the web, its navigation should feel similar to using links in HTML.
Additionally, consider that your routes are accessible as public URLs, which allows another website to link directly to any of your internal routes. If your view has a back button, and it should always go to a specific route in your app, that will only work if you use
Push()
becauseGoBack()
could return anywhere, depending on how the user originally arrived at the route.Regardless,
RouterNavigator
is capable of using aGoBack()
action, if desired:Route.withClass(ViewB.PATHNAME, ViewB, [ Event.COMPLETE => GoBack() ]);
Just be careful how you use it.
Pass data between views
🚧 Data passing will be supported, but it has not been completely implemented yet.