Converting a single-page app to a multi-page app

If you first built your app as a single-page app and now wish to convert it to multi-page, there are a few useful features you'll want to know about!

Copying and pasting components across pages

While breaking out your application, you will probably want to move some existing components from your original page to a new page.

You can use copy (⌘C) / paste (⌘V) to move existing components to new pages. Here are a few useful tips on how to copy and paste effectively in Superblocks

• Copy an entire Section or Column - select the section/column on the canvas
• Multi-select components - holding down the shift key (⇧) and clicking on each component or dragging over a set of component

Duplicating APIs across pages

When splitting your application out into pages, you may realize you need access to the same API on multiple pages. To make this simple, you can duplicate APIs to other pages.

1. Open the navigation left panel
2. Click the three dots context menu for the API you wish to duplicate
3. Hover over Duplicate to and select the page

For example, imagine that my app displayed a list of users in a table, and clicking on a specific table row opened that user's details in a Slideout. Now I want to move that Slideout into a separate UserDetail page.

Previously, if I had some API getUsers which fetched my list of users, I might have referenced the getUsers.response in the Slideout to display some basic information about the selected user.

However, now that I am breaking this Slideout into its own page, I'll need to make sure to fetch the user information on both the list page and the detail page. On the detail page, rather than fetch the entire users list, I might only query the specific user, but it's still easier for me to duplicate the original getUsers API as a starting point to fetch the user information.

To do so, I can easily duplicate the getUsers API from the UserList page to my UserDetail page. I can then edit it as I wish.

info

Be careful of broken references when splitting out a single page into multiple pages. When you duplicate an API, all of the frontend event handlers are preserved - make sure any references to frontend resources make sense on the new page.

Duplicate pages

You can also duplicate an entire page. Duplicating a page will create a new page with the exact same components, APIs, frontend variables, events, and other resources as the original page. Duplicating a page enables you to build your new page by removing unnecessary aspects of the page, rather than adding elements to a blank page.

To duplicate a page, click the three dots next to the page name and select Duplicate.

Changes to file structure with Git

With Multi-Page Apps, Superblocks has updated the file structure for applications in Git. This means if you are currently using Git-based Source Control with your applications, the file structure will be slightly different moving forward.

Specifically, while the old file structure only had a single apis folder and page.yaml file, the new file structure has a pages/ directory containing each individual page in your application.

Single-page app file structure

Multi-page app file structure

The first time you make a commit to your repository after the Multi-Page feature has been enabled for your account, the file structure will automatically be updated. If you are developing on a feature branch, merging this feature branch into your main branch should update the file structure of your main branch, so you will not need to take any manual action!

Handling outstanding branches created before Multi-Page

Any branches that were created before Multi-Page was enabled in your account will have the outdated file structure.

If you attempt to merge a branch with the old file structure into Superblocks after the feature has been enabled (for example, via the Superblocks Github Action), you will see an error message telling you to migrate your file structure.

✖ Pushing application apps/[your_app_name]... [FAILED: Application files at apps/[your_app_name] are in single page format, but the multi-page feature is enabled for your account. 

To resolve this issue, you can make a commit to this branch from Superblocks to convert the file structure to multi-page format. Alternatively, you can run 
`superblocks migrate` to convert your file structure and commit the changes before pushing.

To update the file structure on your branch, you can simply:

1. Open the branch in the Superblocks UI
2. Make a change on the branch (this can be some invisible change like creating a Frontend variable, which can then be deleted in a subsequent commit)
3. Commit the change
4. Superblocks will add one more commit automatically to restructure your files to the multi-page file structure. The commit message title is Superblocks system upgrade
5. Review these changes, approve, and merge

Alternatively, if you don’t want to make a change on your branch, you can simply:

1. Pull the branch locally
2. Run the superblocks migrate CLI command (make sure you’ve installed the latest version of the Superblocks CLI by running npm install -g @superblocksteam/cli@latest)
3. Commit your changes
4. Merge your branch