Routing

The routing system is how you set up the navigation structure within your application. Within it, you can define routes, associate Layouts with routes, and set up different ways to navigate users between routes.

Managing Routes

You can access the Routes list by clicking on your “Account” icon in the Top Bar, selecting Project Settings, and then selecting Routes in the menu. A shortcut to the Routes editor is also present in the Layout panel within the Layouts Editor.

Routes consist of a path, a title, and a Layout assignment.

Static and Dynamic Paths

The path defines how the route will be referenced within your application. For PWAs, the path will be displayed in the navigation bar after the domain name. Native apps also use path-based routing, though the route will not be visible to the end-user.

Examples of valid paths are /, /shop, and /help/contact. For dynamic paths, you can use a colon (:) to define a parameter in your URL. For example, /product/:productId will match both /product/123 and /product/heather-t-shirt. You can then use the DataZone component to extract the value passed as the productId.  A path can have more than one dynamic variable as long as they’re separated by forward slashes (/).

Title

The title for a route simply provides a way to reference the route within Shipcode. This will not be visible to your end users. To set a user-facing title for a Layout, such as the one displayed in a browser tab, reference the Layout panel on the Right Sidebar.

Layout Assignment

The assignment dropdown specifies which Layout will be presented when the app navigates to a particular route. Each route can only have one associated Layout, but Layouts can be used by multiple routes.

You can also associate a Layout to a route from the Canvas. Simply select the appropriate Layout on the Canvas, click on the Layout panel in the Right Sidebar, and select the appropriate route from the list.

Home Route

Within a PWA, the / route specifies which Layout will be presented when a user navigates to the primary page of the application, such as www.example.com.

Fallback Route

The Fallback Route gives you the ability to specify a Layout to be presented when the user navigates to a URL that doesn’t match any of your defined routes. This is essentially the equivalent of a “404” page, though it will work for both PWAs and native applications. The Fallback Route is automatically added to your routes list and cannot be deleted. To add a fallback Layout, simply edit the Fallback Route and select the appropriate Layout from the dropdown.

Navigating to Routes

Link Component

The easiest way to implement a link to a route is the aptly-named Link component. When in Layouts Mode, drag the Link component onto your Layout. You can then place any other component you wish within the Link component.

To set up the link’s path, select the Link component on the Canvas and then click the Settings icon in the Right Sidebar. The Link To property is where you can provide the path that will be triggered when the link is clicked or tapped. For static links, you can simply enter the path, such as /product/123. You can also use FQL within the input field to construct a dynamic link, such as utilizing a productId variable.

The settings panel for a Link has an Open Link in New Tab toggle; when enabled, the link will open in a new browser tab for browser-based PWAs. This setting has no effect for native applications.

Anchor Links

Anchor Links are a feature that allow users to navigate to a specific section within a long page, either from the same page or a different one. This is a common practice for directing users to relevant content without requiring them to scroll.

To use an Anchor Link, you first need to assign a unique identifier to the target section, and then reference that identifier in your Link component.

How to Add an Anchor Link

1. Assign a Native ID: Locate the section you want to link to in the Structure Panel. For best practice, select the outermost container of that section (e.g. View). In the Settings panel, assign a unique native ID to that container. This ID will serve as your anchor point.

How to Connect a Link

The process for connecting a link depends on whether you are linking from the same page or a different page/global element.

1. Select the Link Component: In the Structure Panel, select the Link component you want to use.
2. Add the Identifier in Settings: In the Settings panel, locate the Link To property.
3. • Same-page link: If the link is on the same page as the anchor, simply input a hashtag followed by the native ID (e.g., #company). Do not include the route. Including the route for a same-page link will cause the page to revert to the top.
   • Cross-page or global link: If the link is from a different page or a global element (like a main navigation bar), you must include the route, followed by a hashtag and the native ID (e.g., /#company). The route tells the application which page to go to, and the hashtag tells it where on that page to scroll.

This new content should be added to the existing "Link Component" section of the "Routing Tutorial". It's important to remember that using the correct implementation is critical for proper functionality.

Flows

You can also utilize the Flows Editor to trigger navigation actions within your app. The Navigate node allows you to specify a path; when the Flow is invoked, the application will navigate to the appropriate route. The Back Node, when invoked, will navigate the user to the previously viewed route in their browser or application.