Skip to main content

App Component

Introduction​

AppComponent is a key element within the AppModule structure of CargoXplorer. 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 CargoXplorer
  • 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"