Navigation

To connect the pages in your application, you will need to establish Navigation between them. There are several methods to facilitate this navigation.

Multi-page Superblocks apps employ a single-page app architecture to ensure quick and smooth page transitions, typical of modern web applications.

Navigate to page action

The most common method for navigating between pages is by using the Navigate to page action.

The Navigate to Page action can be connected to any event handler to initiate navigation to another page.

Example - Navigating to a CustomerDetail page

In a multi-page app, a common interaction involves having one page for listing resources (List Page) and another for viewing specific details (Detail Page). For instance, consider a Customer List page displaying users, with the URL route /customers.

Additionally, there's a Customer Detail page with a dynamic route /customers/:customerId. To enable navigation from the list to the details page, clicking on a customer row in the table should lead to the Customer Detail page for the selected customer.

To acheive this, access the table's onRowClicked event handler and configure a Navigate to page action. From there, pass {{TableName.selectedRow.id}} as the customerId route parameter.

Now, clicking on a specific row navigates to /customers/:customerId, where :customerId represents the ID of the selected item passed as the route parameter to the Customer Detail page.

Using links

On the web, links are dedicated HTML elements with specific behavior, such as the ability to open in a 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 navigate dynamically to different pages in an application using either the Navigate to URL action or the navigateTo function in a Run JS action.

When navigating to a different page in your app, it is only necessary to specify the relative path to the page (i.e. the fully resolved route). For example, if the root page is at https://app.superblocks.com/applications/d3c0a8d8-858b-4f4f-a9e1-1b5d3bcbfbd2, you only need to specify /users as the URL in order to navigate to the Users page.

To demonstrate dynamic navigation, imagine using a dropdown to navigate between pages instead of the navigation bar shown in previous screenshots.

Navigate to URL action

One way dynamic navigation can be achieved is with the Navigate to URL action.

In this case, the Dropdown is configured 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, the app should navigate to the page selected in the dropdown.

To achieve this, use the button's onClick event handler and set up a Navigate to URL action. Instead of providing a static URL, simply specify {{Dropdown1.selectedOptionValue}} as the URL. This approach works well since the 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 trigger with the URL set to /issue-card, navigating the user to corresponding page.

Navigation in Run JS

Alternatively, the navigateTo function can be used in the Run JS action to dynamically navigate to different pages in the app. This approach is useful for implementing more complex logic, such as a series of conditionals to construct URLs differently.

For this example, consider that the Dropdown options data is structured as:

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

In this case, additional logic is needed to determine the destination for the navigation. While this could be handled within a binding in the Navigate to page action, running it within the RunJS action offers a more ergonomic approach.

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

Whenever you navigate within a Superblocks app, the pageLoad event will be triggered on the destination page. Consequently, any APIs set to run onPageLoad will execute after navigation.

This behavior persists even when within the same page. For example, updating the route or query parameters using the Navigate to page action will trigger the pageLoad event, causing any associated APIs to re-run.

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, lay out the sections and columns so there is one full-height column for the Navigation. In order to do this:

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 navigation 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.