Composition

Routing

Routing is the process of resolving the URL of a request and resolving it to be able to render the appropriate content for that URL.

info

Many modern front end frameworks (like Next.js, Nuxt 3, Remix) take a file-system based routing approach.

To ensure that you can render pages correctly you need to define routes in your application that match or capture URL patterns that are created in Canvas.

One key aspect of routing is to ensure that valid URLs are created, used and maintained. Once a URL is published it acts as a contract with any visitor that content can be retrieved using it. Website owners also don't have any control how and where the URL is used once it's on the web.

Therefore it's important to make decisions about what system or URL management approach acts as the source of truth for URLs to ensure that they're consistent and valid.

There are two main approaches for managing URLs in Uniform:

  1. using project map: best used when Uniform should act as the primary source of truth for URLs
  2. using composition slugs (Legacy): best used when other systems or tools act as the source of truth for URLs

A project map has a tree of nodes that define the URL structure of your web pages.

By using Project maps you can manage, visualize and resolve URLs for pages that are managed in Uniform (using composition nodes) or in other systems (using placeholder nodes or dynamic pages).

Choose the Project map approach for managing URLs when:

  • Uniform Canvas is responsible for defining and resolving most of your URLs
  • your application has nested URLs or views
  • your application has more than a few pages or views
  • you want to empower you business users to define URL structures

Project map nodes vs composition slugs

When attaching a composition to a project map node the slug field of the composition should not be used to define the URL path of that composition.

For the majority of cases the slug field is then no longer needed. But sometimes the slug field can be used as a human-readable identifier to make it easier to fetch the composition in code: For example, when the composition only represents part of a page (such as site header) and isn't attached to a project map node.

Learn more about how to use the project map.

These tools can be used for implementing routing with Project maps:

Legacy approach

With the introduction of Project Maps the routing approach using composition slugs is no longer the recommended way of managing URLs in Uniform.

While it's still supported and useful in certain scenarios, Uniform recommends using Project Maps for routing, linking and URL management.

The slug-based solution relies on the "slug" field in a composition that stores either a full URL or a unique pathname. If the slug field contains a full, unique URL, all pages are generated by using Canvas API.

In some cases the slug of a composition only contains the final path segment of the URL and the full URL is assembled and resolved based on some conventions. Such as a composition of type Product Feature Page would only have my-awesome-shirt as the slug but the full URL would be /products/features/my-awsome-shirt.

Choose the slug-based approach for managing URLs when:

  • another system is responsible for defining and resolving URLs (for example, another CMS or a front end framework)
  • your application has no need for nested URLs or views
  • your application is basic and only has a few pages or views
  • you need to fetch compositions that aren't attached to a project map node

The Uniform @uniformdev/canvas-next package provide some helper methods to help cut down on boilerplate code to implement routing in Next.js.

  1. Open a terminal in the root of the repository.
  2. Enter the following command:

Flag to use draft content from Canvas. It can be overridden with { preview: process.env.development || process.env.STAGE_ENV === '1' } to build pages with compositions still in draft if it's local env or dedicated private env for internal testing.

Use to override API client and its properties (for example, to override the HTTPS agent).

Override almost any parameter in an API call inside the helper. The request options available will depend on the type of helper you are using.

An optional mapping function that you can use to modify the path passed to the API. it's not available in the withUniformGetStaticPaths helper.

Available in withUniformGetStaticProps helper, it specifies name of the parameter that contains pathname or slug, depending on whether you are using the "project map" or "slug" approach respectively. It needs to match Dynamic route segments. For a structure like the ./pages/[[...myParam1]].jsx page you would use { param: 'myParam1' }. Structures like withUniformGetServerSideProps instead rely on the full path received. Use prefix or modifyPath to control that behavior.

Fetch and retrieve all or only specified nodes and return an array.

By default, it's /, so all nodes from the project map are used. You can override this if you want to cover only a section of your website. Here is an example structure:

If you are building page in Next.js for an "About Us" section, you can specify { rootPath: '/about-us' }.

Alter a list of nodes after fetching and before mapping them into the paths parameter array. For example, this blacklists some URL patterns, because they're covered by dedicated Next.js pages:

A string that you want pre-pended to paths returned by your project map. Useful when calling from a nested folder which isn't part of your project map structure.

Returns getServerSideProps and getStaticProps compatible callbacks respectively.

Alter Props object and composition data or inject additional data props.

A string that you want to strip from the resolved context.resolvedUrl. Useful when calling from a nested folder which isn't part of your project map structure

tip

Learn more about enhancing.

Alter a list of nodes after fetching and before they're mapped into the paths parameters array. For example, this blacklists some URL patterns because they're covered by dedicated Next.js pages:

Alter Props object and composition data.

A string that you want to strip from the resolved context.resolvedUrl. Useful when calling from a nested folder which isn't part of your slug structure.

Last modified
Next
Rendering