Routing

Routing is based on several simple principles:

• A request is handled by a file that corresponds to the path specified in the URL of the HTTP request.
• One file can handle multiple different requests; to select the route "inside" the handler file, the part of the path from the URL after the ~ (tilde) symbol is used.
• The file extensions .ts and .tsx can be omitted in the URL (i.e., instead of https://test.chatium.com/example.tsx, you can make a request to https://test.chatium.com/example).
• If the path in the request URL matches a directory, the system will try to find an index file in that directory (index.html, index.ts(x), or index) and will choose it as the handler if found.

When parsing the URL, it is divided into 3 parts:

<https://accname.chatium.com>/folder1/about~part1

✦ Domain - determines the account and can be a subdomain of chatium.com or any arbitrary domain.

✦ Path - considering nesting and directories. It may or may not contain the .tsx file extension.

✦ part - an optional part indicating the method within the file. It can be added to the URL via a tilde. Variables such as product id can be encoded in it.

If there is a .ts or .tsx file in the account whose path, excluding the extension, matches the Path, then a search for the appropriate method (by default, the template / is searched) will be performed to handle this request, and its code will be executed. The result of this code will be returned to the user.

/**
 * File /company/about.tsx in the test account
 * The screen will open at the address
 * https://test.chatium.com/company/about
 */
app.screen('/', function() {
  return <screen title="About Us"/>
})

Files with the extensions .ts and .tsx register address templates in their code using methods:

• app.screen - handles GET requests, returns a Screen
• app.get - handles GET requests, returns anything
• app.apiCall - handles POST requests - returns an Action
• app.post - handles POST requests - returns anything
• app.html - handles and displays an HTML page - returns routes

Each of these methods has two arguments:

• pattern - the path template, a string that will be compared with the part in the address. If part is not present in the address, it will use the value slash /.
• callback - the request handler function.

How Path Template Works

All examples are given for an account named test, meaning the account address is test.chatium.com.

If part is not used in the address, i.e., there is nothing after the tilde in the URL, the root template will be used.

/**
 * File /catalog.tsx in the test account
 * The screen will open at the address
 * https://test.chatium.com/catalog
 */
app.screen('/', function() {
  return <screen title="Catalog"/>
})

You can set a static template - then a direct match with part will be sought.

/**
 * Example: file catalog.tsx in the test account
 * The screen will open at the address
 * https://test.chatium.com/catalog~list
 */
app.screen('/list', function() {
  return <screen title="Product List"/>
})

Dynamic parameters can be used in the path template.

/**
 * Example: file catalog.tsx in the test account
 * The screen will open at addresses
 *
 * https://test.chatium.com/catalog~item/:id
 *
 * for example
 *
 * https://test.chatium.com/catalog~item/15
 * https://test.chatium.com/catalog~item/00001
 */
app.screen('/item/:id', function(ctx, req) {
  return (
    <screen title="Product">
      <text>{req.params.id}</text>
    </screen>
  )
})

Callback Method

The purpose of the callback method is to return a result to the user's request. It has 2 arguments: ctx and req.

• ctx - the context in which the current request is executed. It contains information about the user, account, environment, router, device, and screen size from which the user made the request.

• req - request parameters, such as queryString or params.

This method should return what corresponds to the request. In the case of the app.screen request, this is a screen; in the case of app.get, it can be any object, such as JSON.