Now Experience Framework: App Shell and Routing

There are some basic concepts developers have to understand before building web applications with the Now Experience Framework. Two of them are the most important and play a fundamental role for all of the apps: App Shell and Routing.

App Shell

App Shell defines an environment where your UX pages will be rendered. It provides general look & feel for your application (header, footer, navigation menu and a content area):

App Shells

Now Experience app is an SPA (Single-page application) which means the only content area will be reloaded while you’re navigating between pages, header/footer, and a navigation menu loaded once and never reloaded again (unless you force to reload).

Currently, we don’t have an official specification on how to build custom App Shells, but we know for sure — it is possible because an App Shell is just a UX page with multiple UX components. There are two important things to notice:

1. App Shell configuration represented as a JSON object in a Composition field.
2. There must be two specific references to the out-of-the-box “Canvas Layout” and “Canvas Main”components:

You can put as many components as you want into App Shell and define any layout, but those two references must be very specific.

“Canvas Main” component renders UX pages that you build in UI Builder. And the way how it knows what page to render and how to switch pages is called Routing.

Routing

Routing is a process of selecting/loading a particular path (UX page) in your application:

Out-of-the-box App Shell that provides a tab component (on the left) with routing

Usually, that’s controlled by a navigation component. When you click a navigation button/link the page URL changes, however, the browser does not reload the entire App Shell, it updates just the content area.

That navigation component in most of the cases is a part of App Shell:

So how exactly navigation component knows about pages and corresponding routes?

This is where UX Properties come to play. Navigation component reads UX properties defined on the corresponding Experience record and switches routes based on that:

App Shell and Routing together

To show you how it works all together I prepared an update set which includes a custom App Shell with a customizable top navigation component — feel free to install, play, and explore it.

Update set includes a few items:

• Header/top-navigation component — is a custom component that reads a specific UX property and provides navigation between pages/routes.
• Custom App Shell — is a simple app shell based on out-of-the-box Portal App Shell where the default navigation component is replaced with a custom one.

Import/install the update set and follow the next steps to wire everything together.

1. Create a new Experience app

Make sure you are in a custom scope, you may need to create a new scoped application or use any of the existing ones.

Create a new Experience app/portal. This should be easy enough — make sure you pick “App Shell (xLabs)” as an App Shell.

2. Create UX property

On the newly created Experience app create a new UX property xlabs-navigation . Copy JSON content from here and paste it into “Value” field of UX property.

This is how it should look like:

JSON content we put into UX property is a configuration for our custom header. This is an example configuration so it already has some routes pre-defined -home, one, and two.

3. Create UX pages in UI Builder

Create 3 pages (content does not matter) with the names/paths home, one, two :

That’s it, you should be able to load a home page with a nice top navigation bar and be able to switch between pages:

4. Configuration options

The component supports multiple configuration options — logo, colors, appearance etc. Check out the documentation.

You can create completely custom navigation headers with no coding at all — just supply proper configuration params and routes:

Summary

App Shells and Routing are the first fundamental concepts every developer should understand and be able to work with. As of today (February 2021) we’re still missing some official documentation, but overall technology is there and we definitely can use it in our custom ServiceNow applications.

…and React?

Here is the fun part — this custom navigation component has been built with React!

It is tricky but doable. And that will be the topic of the next post.