Building apps with multiple pages
In Superblocks, you can build complex apps with multiple pages. Splitting your app into pages helps developers and end-users manage complexity, just like you would with a standard web application.
Each page in your app will have a unique user-defined URL route, so your users can easily navigate around the application and share links to specific pages.
Building multi-page apps enables you to segment out the complexity of your application into logical pages, while still developing and version-controlling the app as a unit.
Multi-page apps are useful when you want to:
- Have a single development team build rich functionality that requires multiple screens
- Develop a complex Admin tool with clearly defined boundaries between separate functional capabilities, such as an app used to manage orders, respond to support tickets, and manage supply chain operations
- Build a list page and detail page for a set of resources - for example, a landing page with a list of users and a detail page for each individual user with more information
- Share state and/or APIs across multiple different pages, such as an app that has many different flows for updating a Jira ticket
- Distribute links to specific functionality within an app to your users
Creating and managing pages
Each Superblocks app has one or more pages. The root page of your app is automatically configured by default and exists at the root route (app.superblocks.com/applications/{your-app-id}/). You can also customize this route.
To add a new page to your Superblocks app, you can simply open the page dropdown in the top navigation bar and click + Add new.
| Property | Description |
|---|---|
| Name | The name of the page which will be visible in the UI |
| Parent page | The parent page, if the page should be nested under another page in your app (i.e. if it should be a subpage or exist at the root domain) |
| Route type | Whether you will know the exact route ahead of time (static) or it will be dynamically generated using path parameters (see dynamic routes section below) |
| Path params | For dynamic routes. Any path params that will be part of the URL route, which will always be available in the Global.URL object |
| Query params | Any query params that the page should expect to receive, which will always be available in the Global.URL object |
| URL route | The full URL route for your page. We’ll attempt to derive this based on the name and parent page but you can edit this |
Once you’ve finished adding the page, you’ll have a brand new page at the route you’ve configured. Now you’re ready to start building out your new page!
You can open the pages section from the left navigation to view the hierarchy of pages in your app. You can also select the page and edit any details from the properties panel.
Dynamic routes with path parameters
A very common pattern in web applications is to build pages that depend on specific data being passed as part of the URL route.
For example, viewing a detail page for a specific user or transaction will often mean including the ID of that resource in the URL, the route would often be /transactions/{transaction-id}.
This pattern aligns with RESTful conventions, as the ID or other details for identifying a resource are passed as part of the URL.
To support this pattern, you can set a page’s Route type to dynamic. Doing so will allow you to provide a list of path parameters that will be included in the page’s route.
Since these parameters are defined up-front, you can develop your page with confidence knowing that the parameters will always be available in the Global.URL.pathname object.
You’ll learn more about allowing your users to navigate between pages and setting these parameters below.
Navigating between pages
To facilitate navigation between pages, you can use the native Navigate to page action, or the corresponding JavaScript function.
The form will automatically populate the required path parameters and any predefined query parameters, and you can also add your own.
The Navigate to page action makes it simple to navigate users around your app based on events - for example, to navigate to the user detail page when a row is clicked in a users table.
Navigation component
The navigation component allows you to easily create a beautiful navigation UX between pages in your application.
The component comes styled out of the box with:
- A header for your app logo and name
- A list of links to display in the nav, pre-populated with all pages at the root level of your app
- Optional sections to logically group navigation links
- Selected state for the page the user is currently on
- An optional vertical or horizontal layout
The native navigation component is extensible - you can add any custom links and corresponding event handlers, conditionally hide links, and customize the style and layout.
Of course, you can also build custom app navigation from scratch by combining native components for infinite extensibility!
Sharing state, APIs, and components across pages
State, APIs, and components are scoped by default to each page, meaning that these resources will not be accessible across pages.
You can promote these resources to the app-level to allow them to be shared across pages. This may be desirable in a few scenarios:
- Sharing state across pages in a single app is common for data that should be accessible in different contexts, just like you would with Redux in React
- Reusing APIs is common when you have shared logic that should be used by multiple pages - for example, you may want to update a Jira ticket from both a list and detail page using the same business logic
- Reusing components is common when the instance of the component has shared configuration on multiple pages, such as a navigation
Using RBAC to control access to specific pages
You can restrict access to specific pages using page visibility. Each page has a visibility property - you can use code mode to simply write your logic in JavaScript to determine which users should be able to access the page.
For example, if you only wished to have users in a group “Customer Support” access a tickets page, you could simply add the following JS to the ticketing page’s visibility setting:
{{Global.user.groups.some(group => group.name === "Customer Support")}}
We also recommend hiding any links to these pages using similar logic so users do not mistakenly land on pages they do not have access to.
Best practices - multi-page app or multiple apps?
Splitting your app into multiple pages and using multiple separate apps are both viable options for managing complexity in Superblocks.
Generally, we recommend the following:
- If a single development team is responsible for the feature set, and this codebase should be version-controlled as a unit, it likely makes more sense as a single multi-page app
- If development responsibilities are sprawled across multiple teams and the functionality should be version-controlled separately, this is a good indication you may be better off developing multiple separate apps
Both options are well-supported in Superblocks. Thus, the distinction between these two options ultimately comes down to your team’s preference!
info
We plan to continue to improve the experience of building across multiple separate Superblocks apps. It will soon be possible to reuse components and APIs as well as share state across applications.
Workarounds and alternatives
Multi-page apps are currently in limited beta. If you would like to build a multi-page experience in your Superblocks app today, you can easily use the Tabs component to create multiple separate canvases which are conditionally shown in your app, simulating a multi-page app experience.
Additionally, if you would like to build a custom navigation component to navigate between the tabs in your app, you can follow this detailed guide!