Navigation

To connect the pages in your application, you will want to build Navigation between these pages. There are a few different ways to facilitate this navigation.

Multi-page Superblocks apps utilize a single-page app architecture so that page transitions are snappy as you'd expect in modern web applications.

Navigate to page action

The most common way to navigate between pages is to use the Navigate to page action.

You can wire the Navigate to page action up to any event handler in order to trigger a navigation to another page.

Example - Navigating to a CustomerDetail page

A very common interaction in a multi-page app is to have one page for a list of resources (List Page) and another page to view a specific resource (Detail Page).

Let's say I have a list of users on my Customer List page. Notice that the route in in the URL is /customers.

I also have a Customer Detail page with a dynamic route /customers/:customerId. I want to wire up my app such that when a user clicks on a customer row in the table, they are navigated to the Customer Detail page for the selected customer.

To do so, I'll open the table's onRowClicked event handler and configure a Navigate to page action. I'll ensure that I am passing {{Table1.selectedRow.id}} as my customerId route parameter.

Now, when a user clicks on a specific row - for example, Jessica Anderson's row - they will be navigated to /customers/11 which is the Customer Detail page with Jessica's ID passed as the route parameter.

Using links

On the web, links are dedicated HTML elements with specific behavior, such as the ability to Open in New Tab via a right-click menu. This behavior is not possible when using event handlers in Superblocks.

If you prefer to use a link, you can simply write HTML inside of a text component. You can use a relative path for linking within your app - you do not need to write the full URL path.

For example, to link to my users page, I could write the following in my text component:

<a href="/users">Users Page</a>

Dynamic navigation

You can easily dynamically navigate to different pages in your app. To do so, you can either use Navigate to URL or the navigateTo function in a Run JS action.

When navigating to a different page in your app, you only need to specify the relative path to the page (i.e. the fully resolved route).

For example, if my root page is at https://app.superblocks.com/applications/d3c0a8d8-858b-4f4f-a9e1-1b5d3bcbfbd2 and I want to navigate to my Users page which has the route /users, I only need to specify /users as the URL I am navigating to.

To walk through how to implement dynamic navigation, let's imagine that instead of the navigation bar we've seen in the previous screenshots, we want to use a dropdown to navigate between pages.

Navigate to URL action

First, let's examine how we could achieve this with the Navigate to URL action.

In this case, we've configured the Dropdown with the following options data.

[
  {
    "label": "Issue Card",
    "value": "/issue-card"
  },
  {
    "label": "Customers",
    "value": "/customers"
  },
    {
    "label": "Customer Detail",
    "value": "/customers/{{Table1.selectedRow.id}}"
  }
]

Now, when a user clicks the Go button, we want to navigate to the page selected in the dropdown.

In order to do so, we can use the button's onClick event handler and set up a Navigate to URL action. Instead of providing a static URL, we simply specify that {{Dropdown1.selectedOptionValue}} as the URL. This approach works well since our options object already contains the relative paths for each of our pages.

Now, when a user selects the Issue Card option from the dropdown and clicks the Go! button, the Navigate to URL action will fire with the URL set to /issue-card, navigating the user to the page with this route.

Navigation in Run JS

Alternatively, we can utilize the navigateTo function in the Run JS action to dynamically navigate to different pages in our app.

This approach is useful if we want to write more complex logic - for example, a series of conditionals with some logic to construct URLs differently.

For this example, let's imagine that our Dropdown options data instead was structured as:

["Issue Card", "Customers", "Customer Detail"]

In this case, we're going to need to write a bit more logic to determine where the user should be navigated. While we could do this within a binding in the Navigate to page action, it will be more ergonomic to write it inside RunJS.

let selectedPage = Dropdown1.selectedOptionValue;

switch (selectedPage) {
  case "Issue Card":
    navigateTo(`/issue-card`);
    break;
  case "Customers":
    navigateTo(`/customers`);
    break;
  case "Customer Detail":
    navigateTo(`/customers/${Table1.selectedRow.id}`);
    break;
  default:
    showAlert("Page not found", "warning", 4, "top");
}

Navigation and events

Each time you navigate within your Superblocks app, the pageLoad event will be triggered on the page being navigated to. As a result, any APIs you have that run onPageLoad will run after navigation.

This behavior applies even when you navigate within the same page. For example, if you update route or query parameters using the Navigate to page action, the pageLoad event will be triggered, re-running any APIs which run onPageLoad.

Building a standard navigation bar

Most web apps have a standard navigation used to switch between pages. For example, think of the sidebar navigation in Shopify or the top navigation bar in Github.

In Superblocks, you can easily build your pixel-perfect Navigation using a combination of Layouts and Multi-Page.

Sidebar navigation

Let's walk through how we could build out the Shopify navigation in the screenshot above.

First, I want to lay out my sections and columns so I have one full-height column for my navigation. To do so, I will:

1. Add a column to the main section
2. Resize the column to the appropriate width which is 2/12 columns.
3. Set the section's height to Fill viewport - this will ensure the nav is always full height regardless of screen height
4. Set the Background color of this column to rgba(250, 250, 250)

Next, I'll set the column's Layout to Vertical stack, since I want all my links laid out vertically.

I'll drag in two containers - one for the top set of navigation items and the other for the footer - and set the columns' Vertical alignment to Space between. Now I have two containers where I'll place my navigation items.

I'll rename the first container to MainNavItems for ease of use. Then, I will:

• Set its Layout to Vertical stack so I can lay out my Nav items in this stack.
• Set its Background color to transparent

Now, I'll create my Home navigation item. I'll drag in a Button and apply the following configuration:

• Label = "Home"
• Icon = "home"
• Text color = rgba(55, 55, 55)
• Background color = `{{ ['/'].includes(Global.URL.currentRoute) ? `rgba(250, 250, 250)` : `rgba(0, 0, 0, 0)` }}`

The Background color changes conditionally based on whether the currentRoute matches the link for this button, since I want to show a selected state when the user is on a specific page.

I'll also reduce the height of the button slightly since the buttons in the Shopify navigation are shorter.

I'll then copy this button and paste it many times to create the rest of my Navigation items. I'll need to remember to adjust the Background of each button to match on the correct route.

This is looking pretty good. But now I want to add a section for my Sales channels. There are a few different approaches I can take to get my desired layout.

For example, I could create another container and move the main section into it, then add additional containers for the other sections so that I have:

• MainNavItems (container)
  • TopItems (container)
  • SalesChannel (container)
  • Apps (container)
• Footer (container)

In this case, however, I'm just going to add in another container to use as a spacer between my two sections.

Then, I'll add another button in for the Sales channels and configure this one to always have a transparent background, and set the Text color to rgba(78, 78, 78).

Below that, I can add the remaining navigation items, as well as the Apps section.

We're close now! But the items look a bit too far apart. To condense the items, we can reduce the Spacing in MainNavContainer to Small (6px)

Looking good! To finalize these navigation items, we will want to set up their respective onClick handlers to Navigate to the relevant page.

Finally, I'll want to set up my footer, which in this case only includes a Settings item.

First I'll set up the Footer container by:

• Setting the Layout to Vertical stack
• Setting the Background color to transparent

Then, I can copy an existing nav item into the Footer container I created early and configure it with the relevant label, icon, and onClick handler.

My navigation is pretty much complete! To make my app look a bit more like Shopify, I might also add a section above for my header.

Duplicating navigation to other pages

Once you've built your navigation, you can easily copy it over to other pages. Simply select the Section, Column, or Container, copy it clipboard, and paste it over to the new page.