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
    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
• layout: Layout of the component
• props: Component properties
• children: 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"

Best Practices

1. Use meaningful and consistent naming conventions for components.
2. Leverage reusable components to maintain consistency and reduce duplication.
3. Implement proper access control through permissions at the component level.
4. Utilize localization features for multi-language support in labels and text.
5. Structure complex UIs using nested components and layouts for better organization.
6. Consider performance implications when designing components with large data sets or complex behaviors.