App Component

Introduction

AppComponent is a key element within the AppModule structure of CXTMS. It defines the UI elements, their behavior, and layout for specific features or sections of the application.

When to Use App Components

• When creating new UI features for CXTMS
• When modifying existing UI layouts or behaviors
• When building reusable UI elements across different modules

Structure

AppComponents are defined using YAML syntax within the components section of an AppModule file. Here's a basic structure:

components:
  - name: "ModuleName/ComponentName"
    permissions: "ComponentName/View" # Permission to access the component
    priority: 0 # (Optional) Priority of the component. Components with higher priority will override lower priority components. (Default is 0, higher number is higher priority)
    displayName:
      en-US: "Human-readable Component Name"
    layout: # Layout of the component
      component: "layout" # Layout component type (e.g., form, tabs, layout)
      props:
        # Component properties
      children:
        # Nested components

Key attributes:

• name: Name of the component (unique within the system)
• permissions: Permission to access the component. If not specified, the component will be accessible to all users.
• displayName: Localized display names
• priority: Priority of the component. Components with higher priority will override lower priority components. (Default is 0, higher number is higher priority)
• layout: Layout of the component
• props: Component properties
• children: Array of nested components

Key Components

Component Name

The name field follows the format: ModuleName/ComponentName

For example:

• PurchaseOrder/PurchaseOrderForm
• PurchaseOrder/PurchaseOrderList

Display Name

Provides a localized, human-readable name for the component:

displayName:
  en-US: "Shipment Form"
  fr-FR: "Formulaire d'expédition"

Layout

Defines the structure and behavior of the component:

layout:
  component: "form"
  props:
    cols: 2
  children:
    - component: "field"
      props:
        name: "shipmentNumber"
        label:
          en-US: "Shipment Number"
        type: "text"

Use Cases

Simple Form Component

components:
  - name: "TMS/SimpleShipmentForm"
    displayName:
      en-US: "Simple Shipment Form"
    layout:
      component: "form"
      props:
        cols: 2
      children:
        - component: "field"
          props:
            name: "shipmentNumber"
            label:
              en-US: "Shipment Number"
            type: "text"
        - component: "field"
          props:
            name: "shipmentDate"
            label:
              en-US: "Shipment Date"
            type: "date"

Complex Component with Tabs and Data Grid

components:
  - name: "TMS/ShipmentDashboard"
    displayName:
      en-US: "Shipment Dashboard"
    layout:
      component: "layout"
      children:
        - component: "tabs"
          children:
            - component: "tab"
              props:
                label:
                  en-US: "Active Shipments"
              children:
                - component: "dataGrid"
                  props:
                    entity: "Shipment"
                    filter:
                      status: "active"
            - component: "tab"
              props:
                label:
                  en-US: "Completed Shipments"
              children:
                - component: "dataGrid"
                  props:
                    entity: "Shipment"
                    filter:
                      status: "completed"

Component Extensions using Slots

Component extensions using slots are a way to extend components with additional components from another modules.

# Define the component with the extension "component"
components:
  - name: "TMS/ShipmentDashboard"
    displayName:
      en-US: "Shipment Dashboard"
    layout:
      component: "layout"
      children:
        - component: "tabs"
          children:
            - component: "tab"
              props:
                label:
                  en-US: "Active Shipments"
              children:
                - component: "dataGrid"
            - component: "slot" # Slot component
              props:
                name: "TMS/ShipmentDashboard/Tabs" # Name of the slot

Define the extension component in another AppModule file.

components:
  - name: "TMS/ShipmentDashboard/ExtraTab"
    displayName:
      en-US: "Extra Tab"
    props:
      targetSlot: "TMS/ShipmentDashboard/Tabs"
      order: 1 # (Optional) Order of the component in the target slot.
    layout:
      component: "tab"
      props:
        label:
          en-US: "Extra Tab"
      children:

Define another tab component in the another AppModule file.

components:
  - name: "TMS/ShipmentDashboard/AnotherTab"
    displayName:
      en-US: "Another Tab"
    props:
      targetSlot: "TMS/ShipmentDashboard/Tabs"
      order: 2 # (Optional) Order of the component in the target slot.
    layout:
      component: "tab"
      props:
        label:
          en-US: "Another Tab"

Toggle Button Field

Use type: toggle on a field component when a form needs a compact segmented-control choice instead of a dropdown or radio list. It renders a MUI ToggleButtonGroup and works with React Hook Form validation.

- component: field
  name: priority
  props:
    type: toggle
    label: Priority
    enforceValue: true
    defaultValue: medium
    items:
      - value: low
        label: Low
      - value: medium
        label: Medium
      - value: high
        label: High

Key props:

Prop	Description
items[]	Required options. Each item has value, label, optional icon, and optional disabled.
exclusive	true for single-select (default), false for multi-select array values.
enforceValue	In single-select mode, prevents deselecting the current value.
defaultValue	Selects an initial option after items load.
size	small, medium, or large.
color	MUI toggle color: standard, primary, secondary, error, info, success, or warning.
orientation	horizontal or vertical.

- component: field
  name: transportMode
  props:
    type: toggle
    label: Transport Mode
    items:
      - { value: truck, label: Truck, icon: truck }
      - { value: ship, label: Ship, icon: ship }
      - { value: plane, label: Plane, icon: plane }

Diff viewer layout

The diff component keeps its gutters and change markers at fixed widths and lets long content wrap inside each half of the comparison. This prevents long JSON, YAML, or unbroken values from forcing one side wider than the other.

component: diff
name: configDiff
props:
  oldValue: "{{ previousConfig }}"
  newValue: "{{ currentConfig }}"
  leftTitle: "Previous"
  rightTitle: "Current"