Routing

Routes define the navigation structure and access control for different screens within CXTMS. They are a crucial part of the AppModule configuration, determining how users interact with various components of the system.

Introduction

Routing in CXTMS establishes the hierarchical structure of the application, linking URLs to specific components and managing access permissions. This system ensures efficient navigation and proper security measures throughout the application.

When to Use Routes

• When defining the overall structure of your CXTMS application
• To create new screens or sections within the system
• When setting up access control for different parts of the application
• To establish relationships between different components and views

Routes Example

Transportation Management

routes:
  - name: "Shipments/List"
    path: "shipments"
    component: "Shipments/ListComponent"
    props:
      title:
        en-US: "Shipments"
    children: # Nested routes
      - name: "Shipments/Details"
        path: ":id" # Route path with a dynamic parameter
        component: "Shipments/DetailsComponent"

Key Attributes:

• name: Unique identifier for the route
• path: URL path for accessing the route
• component: Component to render for this route
• props: Properties to pass to the component
• children: Nested routes under this route
• permission: Required permission to access this route
• permissions / requiredPermissions: Array forms used by route consumers that need multiple required permissions

Route Fields

Field	Description	Usage
name	Unique identifier for the route	Used for internal references and navigation
path	URL path for accessing the route	Defines the URL structure for the application
component	Component to render for this route	Specifies which UI component should be displayed
props	Properties to pass to the component	Allows for customization of the component based on the route
children	Nested routes under this route	Creates a hierarchical structure for complex views
permission	Required permission to access this route	Controls access to specific parts of the application

How to Create Routes

1. Open your AppModule configuration file
2. Locate the routes section
3. Add a new route entry with the required fields:

routes:
  - name: "ExampleRoute"
    path: "example"
    component: "Example/ExampleComponent"
    props:
      title:
        en-US: "Example Route"
    permission: "ExampleModule/Read"

4. For nested routes, add them under the children property of a parent route
5. Save your configuration file

Route Matching for Linked Notifications and Dialogs

CXTMS route matching supports entity-style paths such as Order/12345 or Terminal/42. When a notification includes entityType and entityId, the UI resolves the target route by matching the generated path (entityType/entityId) against configured app routes. If a matching route exists and the current user has all route permissions, the target component opens in a dialog with route parameters converted to numbers when possible.

Route access checks understand these shapes:

• permission: "Terminal/Read"
• permissions: ["Terminal/Read", "Port/Read"]
• requiredPermissions: ["Terminal/Read"]

Use dynamic route parameters for entity detail screens so notifications can deep-link cleanly:

routes:
  - name: "Terminals/Detail"
    path: "Terminal/:terminalId"
    component: "Terminals/TerminalDetail"
    props:
      title: "Terminal {{ terminalId }}"
    requiredPermissions:
      - "Terminal/Read"

Best Practices

1. Use descriptive and consistent naming conventions for route names
2. Keep URL paths (the path property) short and meaningful
3. Organize routes hierarchically to reflect the structure of your application
4. Always set appropriate permissions to ensure proper access control
5. Use props to pass necessary data to components, enhancing reusability