The
<path-router>
element allows developers to show and hide sections of html contained in "routes" which can either be defined using
<route-page>
or
route-dialog
child elements.
Routing is done by matching the the
<path-router>
element's
path
attribute to one of its child route's
path
attributes.
Matching path values can be as simple as exact string matches. Many types of routing can be done without any type of dynamic content or subrouting.
The
<path-router>
element does, however, account for dynamic content and subrouting by allowing complex matching that uses common string patterns for variables, and partial-path matching so that subrouting can be done with the unmatched path content.
If the
<path-router>
element's
path
attribute finds a child route that matches, that route will be displayed.
If no route can be found that matches the
<path-router>
element's
path
attribute, no route will be displayed.
Features
Transitions
Blocking
The
<path-router>
element dispatches events and allows for asynchronous blocking during route opening and closing procedures.
CSS Integration
CSS transitions and animations, including opacity fades and animation effects like bouncing or rotating, are awaited by the
<path-router>
element, allowing for event handling before and after animations without needing to set up timers or callbacks.
Dialog Routes
To account for the common design pattern of dialog routes, while still maintaining best practices for route history manamgent, the
<path-router>
element uses the hash character (#) to match with any
route-dialog
child elements.
Links and Buttons
As an additional convenience, this library also provides the addRouteLinkClickHandlers() function, which adds handling for any anchor (<a>) element or <button> element to route to a custom path.
Basic Example
The
<path-router>
element has no value set for the
path
attribute. This prevents the path-router from starting with a route open.
To open a route, select an option from the menu below:
Route ARoute BRoute C
Default Route
As long as the
<path-router>
element's
path
attribute is set, the
<path-router>
will auto-navigate.
If the
path
attribute is set to nothing, set to an empty string, or set to a path that does not match any routes, a default route (configurable, but usually the first child route) will be opened.
The following example has the
<path-router>'s
path
attribute set to an empty string. Note that the first route is opened.
Route FirstRoute SecondRoute Third
Starting Route
Set the
<path-router>
element's
path
attribute to automatically navigate to the matching path when the page is opened.
The following example is set to open the "Route C" when the page is opened.
Route ARoute BRoute C
Custom Default Route
Setting a
<route-page>'s
default
attribute to any value will set that route to be the route opened in the case that a default route would be opened (no path set, path set to an unmatching value, etc...).
If multiple
<route-page>
elements have a
default
attribute, the last
<route-page>
listed with the attribute will be used.
The following example has the
<path-router>'s
path
attribute set to an empty string. Note that the second route is opened.
Route FirstRoute SecondRoute Third
Subrouting
The <path-router> element can match nested <route-page> elements, in addition to direct <route-page> children. Each nested level will be matched based on its sibling pages, using the same rules as top-level route matching.
In practice, this means that a path of parent/child could match the top level route with a path attribute of "top" as well as a <route-page> element inside of that "top" element with a path attribute of "child".
Subrouting can be implemented with automatic handling by nesting one <route-page> element inside of another. <route-page> elements that are inside <route-dialog> elements will also be subrouted automatically.
<route-page> elements that are inside of a separate <path-router> element will not be handled as subroutes, with the expectation that the closest <path-router> will manage its own <route-page>s.
In this example, the "About" page has multiple subroutes, as a method of maintaining the visibility of its header content.
HomeAbout
This AppCompanyMissionFAQ
Contact
Route Properties
Route properties are defined with a
:
prefix. For example,
:id
defines a route property named "id".
Route properties allow multiple different paths to open the same route. When a
<route-page>
element has a route property defined in it's
path
attribute, that route can be accessed by any path that can match the value after substituting variables for the supplied values.
HomeUserUser
User Contacts
User Contact
Properties Log
Dialog Routes
Dialog routes are managed as a secondary routing layer. This allows dialogs to be managed by common single-path routing methods, often used in web apps, without unwanted side effects like closing the current route.
Dialog routes can be used like any other route, including awaiting transitions, and handling events.
HomeAbout
Transitions
The
<route-page>
and
route-dialog
elements dispatch custom events when navigation is occurring. There are four total events, but the events may be assigned in two ways: "normally" or "blocking". These are handled by two separate sets of event handlers, so you can specify the preference in implementation.
Using the standard
addEventListener
function will add an event that does NOT block the page from transitioning. The handler will run simultaneously with the css transitions.
If you need to prevent a route from opening until after your handler has finished its work, you can use the custom
addBlockingEventListener, in the same way, using the same event name.
Since the handlers will be awaited, you can use asynchronous code within the handler. This allows dynamic content to be set during the transitions.
before
events will fire before any css transitions or animations are applied and
after
events will fire after all css transitions and animations have finished.
Events
beforeopen
afteropen
beforeclose
afterclose
Before Page Open
Before Page Close
Event Log
Browser History Management
This browser mockup demonstrates how the
<path-router>
element's navigation events can be handled. This demo page does not actually manipulate your browser's history.
Instead, this demo collects the full, current path from the
<path-router>
element's
path
attribute, and then uses the element's
compareLocations
function to determine whether or not the path has changed, and if the change was a simple navigation, or a "replacement" navigation (for dialog-to-dialog transitions).
When navigating through the routes in the browser mockup demo, you can use the "Forward" and "Back" buttons to simulate browser history navigation.