Class OutletRouter

Allows navigating to a web page or microfrontend in a <sci-router-outlet> element.

In SCION Microfrontend Platform, routing means instructing a <sci-router-outlet> to display the content of a URL. Routing works across microfrontend and micro application boundaries, allowing the URL of an outlet to be set from anywhere in the application. The web content displayed in an outlet can be any HTML document that has not set the HTTP header X-Frame-Options. Routing is also referred to as navigating.

The router supports multiple outlets in the same application to co-exist. By giving an outlet a name, you can reference it as the routing target. If not naming an outlet, its name defaults to primary. If multiple outlets have the same name, they all show the same content. If routing in the context of a router outlet, that is inside a microfrontend, and not specifying a routing target, the content of the current outlet is replaced.

An outlet does not necessarily have to exist at the time of routing. When adding the outlet to the DOM, the outlet displays the last URL routed for it. When repeating routing for an outlet, its content is replaced.

A router outlet is defined as follows. If no navigation has been performed for the outlet yet, then its content is empty.

<sci-router-outlet name="aside"></sci-router-outlet>
Copy

Navigation via URL

The URL of the page to be loaded into the router outlet is passed to the router, as follows:

Beans.get(OutletRouter).navigate('https://micro-frontends.org', {outlet: 'aside'});
Copy

Relative URL Navigation

The router allows to use both absolute and relative paths. A relative path begins with a navigational symbol /, ./, or ../. By default, relative navigation is relative to the current window location of the navigating application, unless specifying a base path for the navigation.

// Navigation relative to the root path segment
Beans.get(OutletRouter).navigate('/products/:id', {outlet: PRIMARY_OUTLET});

// Navigation relative to the parent path segment
Beans.get(OutletRouter).navigate('../products/:id', {outlet: PRIMARY_OUTLET});
Copy

Named URL Parameters

The URL being passed to the router can contain named parameters which the router replaces with values of the provided params object. A named parameter begins with a colon (:) and is allowed in path segments, query parameters, matrix parameters and the fragment part, e.g., product/:id or product;id=:id or products?id=:id.

Navigating via Intent

As an alternative to navigating directly to a URL, the router supports navigation to a microfrontend capability via an intent. We refer to this as intent-based routing.

We recommend using intent-based routing over url-based routing, especially for cross-application navigations, since the navigation flows are explicit, i.e., declared in the manifest, and to keep the microfrontend URLs an implementation detail of the micro applications that provide the microfrontends.

Note that if the microfrontend is provided by another micro app, the navigating app must manifest an intention. Also, the navigating app can only navigate to public microfrontend capabilities.

The following code snippet illustrates how to display the product microfrontend in the "aside" outlet. Note that you only need to pass the qualifier of the microfrontend capability and not its type. The capability type, which is always microfrontend, is implicitly set by the router.

Beans.get(OutletRouter).navigate({entity: 'product'}, {
  outlet: 'aside',
  params: {id: 123},
});
Copy

Applications can provide microfrontend capabilities through their manifest. A microfrontend can be either application private or exposed to other micro applications. The platform requires all microfrontend capabilities to be of type microfrontend. A particular microfrontend can be identified using its qualifier.

{
  "type": "microfrontend",
  "qualifier": {
    "entity": "product"
  },
  "description": "Displays a product.",
  "params": [
    {"name": "id", "required": true}
  ],
  "private": false,
  "properties": {
    "path": "product/:id",
  }
}
Copy

Note that the providing micro application does not need to install an intent handler for its microfrontend capabilities. The platform intercepts microfrontend intents and performs the navigation.

Persistent Navigation

Persistent navigation refers to the mechanism for restoring the navigational state after an application reload.

The router does not provide an implementation for persistent navigation out-of-the-box, mostly because many persistence strategies are imaginable. For example, the navigational state could be added to the top-level URL, stored in local storage, or persisted in the backend. However, you can easily implement persistent navigation yourself. The router publishes navigations to the topic sci-router-outlets/:outlet/url; thus, they can be captured and persisted. When starting the application, you can then replay persisted navigations using the router.

Unloading Outlet Content

To unload an outlet’s content, use null as the URL when routing, as follows:

Beans.get(OutletRouter).navigate(null, {outlet: 'aside'});
Copy

Browsing History and Session History

Routing does not add an entry to the browsing history, and, by default, not push a navigational state to the browser’s session history stack.

You can instruct the router to add a navigational state to the browser’s session history stack, allowing the user to use the back button of the browser to navigate back in an outlet.

Beans.get(OutletRouter).navigate('https://micro-frontends.org', {
  outlet: 'aside',
  pushStateToSessionHistoryStack: true,
});
Copy