Skip to main content

Routing

Helium utilizes a file based routing system which means you define all routes for your Helium app in the /pages directory. We’ll walk through a couple of use cases. Examples of all these different use cases can found in this github repository.

The Helium Frameworks job is to replacing pages in TI with your own code and functionality. We utalize a simple file based routing system to achieve this. This is done using the /pages directory which you will find in your base helium app. Below are a couple of use cases, including:

  • Replacing an Existing Page
  • Creating a New Page
  • Replacing Multiple Pages at Once
  • Creating a Catch All Route

Replacing an Existing Page​

Taking control of a page in Helium is as simple as defining a new file-path in the pages directory. Simply create a new folder underneath the pages directory with the name of the route you want to replace, then create a file in that new directory named index.page.tsx. Here are some examples:

  • If you wanted to replace the dashboard page, you would do that under /pages/learn/dashboard.page.tsx
  • The catalog would be replaced with the following path: /pages/catalog/index.page.tsx
  • And lastly, the homepage would be replaced using the index path: pages/index/index.page.tsx

Creating a New Page​

Alongside replacing an existing helium page, you can create new pages for your instance using Helium. To achieve this, simply create a new folder named the new route in the pages folder and create an index.page.tsx. You can also create other files under this folder with naming convention [otherName].page.tsx. Here's some examples:

  • If you wanted to create a new route /test, you would do /pages/test/index.page.tsx
  • Creating a new page under alongside an existing route would look like: /pages/catalog/test-catalog.page.tsx. This page would be displayed when the user visited {your-instance-url}/catalog/test-catalog

Replacing Multiple Pages at Once​

For some use cases, the only thing that changes on a page is the data and context. A great example of this is the course details page. This page is displayed before a user enrolls/enters a course. The layout of the page itself acts more like a template.

A single file can be created for multiple/all courses. This file will control the layout of the course details page, which can then load in content dynamically.

  1. In the pages/courses directory, create a file named @courseSlug.page.tsx
  2. Add 'routeParams' to the end of passToClient in render/_default.page.server.tsx like so
export const passToClient = [
  ...,
  'isProduction',
  'queryParams',
  'authToken',
  'routeParams'
];
  1. You can then refrence the courseSlug param like so:
import React from 'react';
import { usePageContext } from '../../renderer/usePageContext';

function Page() {
  const { routeParams } = usePageContext();
  return (
    <>
      <h1>Welcome to {routeParams.courseSlug}</h1>
    </>
  );
}

export { Page };
  1. The contents of this file will now control all course detail pages of the Helium app, that do not already have a specific course detail page created.

More information on how route strings work can be found here.

Creating a Catch All Route​

Catch all routes are great for letting a user know they are probably somewhere they don’t want to be. A catch all route string can be used to replace the classic 404 error page, by providing the user with a little bit more information.

  1. To create a catch all route, create a new file in pages/courses named *.page/tsx
  2. The contents of this page will now be shown when the user visits courses/course-slug/a-page-that-doesn’t-exist.