Skip to main content

Slot Component in CargoXplorer TMS

Introduction​

The Slot Component is a powerful extension mechanism in CargoXplorer TMS that allows for dynamic injection of components from other modules. It provides a way to create extensible layouts where additional components can be added without modifying the original component definition, enabling modular and flexible application architecture.

YAML Structure​

component: slot
props:
  name: "ModuleName/ComponentName/SlotName"
  order: 1

Attribute Description​

  • component: (string) Must be set to "slot" to use this component type.
  • props: (object) Contains the configuration properties for the slot component.
    • name: (string) Required. Unique identifier for the slot that other components can target for extension.
    • order: (number) Optional. Defines the rendering order of the slot within its parent container. Default is 0.

Examples​

Basic Slot Definition​

component: slot
props:
  name: "TMS/ShipmentForm/AdditionalFields"
  order: 1

Slot Within Toolbar Items Array​

component: dataGrid
props:
  toolbar:
    - component: dropdown
      name: orderActions
      props:
        label:
          en-US: Actions
        icon: activity
        items:
          - label:
              en-US: Import
          - label:
              en-US: Export
    - component: slot                              # Extension point in toolbar
      props:
        name: "TMS/OrderGrid/CustomToolbarActions"
        order: 2

Slot Within Navbar Items Array​

component: navbar
props:
  items:
    - component: navbarItem
      props:
        label:
          en-US: Dashboard
        href: "/dashboard"
    - component: slot                              # Extension point in navbar
      props:
        name: "TMS/MainNavbar/CustomMenuItems"
        order: 3
    - component: navbarItem
      props:
        label:
          en-US: Settings
        href: "/settings"

Extension Component Definition​

To inject components into a slot, define components with targetSlot property:

Basic Extension Component​

components:
  - name: "CustomModule/ShipmentFormExtension"
    displayName:
      en-US: "Custom Shipment Fields"
    props:
      targetSlot: "TMS/ShipmentForm/AdditionalFields"
      order: 1
    layout:
      component: "form"
      children:
        - component: "field"
          props:
            name: "customField1"
            label:
              en-US: "Custom Field 1"
            type: "text"

Multiple Extensions for Same Slot (Tabs)​

In this example, we have two extensions for the same slot. The first extension is a tab component with a label of "Sales Overview". The second extension is a tab component with a label of "Performance Metrics".

components:
  - name: "TMS/ShipmentDashboard/Tabs"
    displayName:
      en-US: "Shipment Dashboard Tabs"
    layout:
      component: "tabs"
      children:
        - component: "tab"
          props:
            label: "General"
        - component: "slot"
          props:
            name: "TMS/ShipmentDashboard/Tabs"
# First extension
components:
  - name: "Module1/DashboardWidget1"
    displayName:
      en-US: "Sales Widget"
    props:
      targetSlot: "TMS/ShipmentDashboard/Tabs"
      order: 1
    layout:
      component: "tab"
      props:
        label: "Sales Overview"

  # Second extension
  - name: "Module2/DashboardWidget2"
    displayName:
      en-US: "Performance Widget"
    props:
      targetSlot: "TMS/ShipmentDashboard/Tabs"
      order: 2
    layout:
      component: "tab"
      props:
        label: "Performance Metrics"

Extending Dropdown Items with Slots​

Slots can be used within dropdown items arrays to allow multiple modules to contribute additional dropdown options:

# Base component with dropdown containing a slot
toolbar:
  - component: dropdown
    name: orderActions
    props:
      label:
        en-US: Actions
      icon: activity
      items:
        - label:
            en-US: Import
          value: import
          onClick:
            - action: importOrders
        - label:
            en-US: Export  
          value: export
          onClick:
            - action: exportOrders
        # Slot for additional dropdown items
        - component: slot
          props:
            name: "TMS/OrderActions/AdditionalItems"
            order: 1

Multiple Modules Extending the Same Dropdown​

Different modules can contribute items to the same dropdown slot:

# Module A - Email Extension
components:
  - name: "EmailModule/OrderNotifications"
    displayName:
      en-US: "Email Notifications for Orders"
    props:
      targetSlot: "TMS/OrderActions/AdditionalItems"
      order: 10
    layout:
      items:
        - label:
            en-US: Send Email Notification
          value: emailNotification
          icon: mail
          onClick:
            - dialog:
                name: emailNotificationDialog
                props:
                  orderId: "{{ orderId }}"
        - label:
            en-US: Email Invoice
          value: emailInvoice
          icon: file-text
          onClick:
            - workflow:
                workflowId: "send-invoice-email"
                inputs:
                  orderId: "{{ orderId }}"
# Module B - Reporting Extension
components:
  - name: "ReportingModule/OrderReports"
    displayName:
      en-US: "Order Reporting Actions"
    props:
      targetSlot: "TMS/OrderActions/AdditionalItems"
      order: 20
    layout:
      items:
        - label:
            en-US: Generate Detailed Report
          value: detailedReport
          icon: bar-chart
          onClick:
            - navigate: "/reports/order/{{ orderId }}"
        - label: 
            en-US: Analytics Dashboard
          value: analytics
          icon: trending-up
          onClick:
            - navigate: "/analytics/orders?filter={{ orderId }}"

Dynamic Dropdown Item Extensions​

Extensions can use variables and conditions to dynamically add items:

# Module C - Conditional Extension
components:
  - name: "AdminModule/AdminActions"
    displayName:
      en-US: "Admin Order Actions"
    props:
      targetSlot: "TMS/OrderActions/AdditionalItems"
      order: 30
      # Only show for admin users
      condition: "{{ user.role == 'admin' }}"
    layout:
      items:
        - label:
            en-US: Delete Order
          value: deleteOrder
          icon: trash
          style: danger
          onClick:
            - confirm:
                title:
                  en-US: Confirm Deletion
                message:
                  en-US: Are you sure you want to delete this order?
                onConfirm:
                  - mutation:
                      command: "deleteOrder"
                      variables:
                        orderId: "{{ orderId }}"
        - label:
            en-US: "{{ adminActionLabel }}"
          value: customAdmin
          icon: settings
          condition: "{{ hasCustomAdminAction }}"
          onClick:
            - action: "{{ customAdminAction }}"

Nested Dropdown Extensions​

Complex dropdown structures with sub-menus can also use slots:

# Base dropdown with nested structure
toolbar:
  - component: dropdown
    name: advancedActions
    props:
      label:
        en-US: Advanced
      icon: more-horizontal
      items:
        - label:
            en-US: Documents
          items:
            - label:
                en-US: Generate BOL
            - label:
                en-US: Print Labels
            # Slot for additional document actions
            - component: slot
              props:
                name: "TMS/AdvancedActions/DocumentItems"
                order: 1
        - label:
            en-US: Communications
          items:
            - label:
                en-US: Send SMS
            # Slot for additional communication actions  
            - component: slot
              props:
                name: "TMS/AdvancedActions/CommunicationItems"
                order: 1

Extension Best Practices for Dropdowns​

When extending dropdown items through slots:

  1. Use Meaningful Order Values: Use increments of 10 (10, 20, 30) to allow for future insertions
  2. Group Related Items: Consider using separators or sub-groupings for logical organization
  3. Conditional Extensions: Use conditions to show/hide items based on user roles or data state
  4. Consistent Icons: Follow the existing icon patterns in the dropdown
  5. Action Patterns: Maintain consistency with onClick action patterns (dialogs, workflows, navigation)

Common Mistakes to Avoid​

❌ Incorrect Slot Configuration​

# DON'T DO THIS - Slots don't have visual properties
component: slot
props:
  label:                    # ❌ Slots don't have labels
    en-US: Actions
  icon: activity           # ❌ Slots don't have icons
  items:                   # ❌ Slots don't contain items directly
    - label:
        en-US: Something

✅ Correct Slot Configuration​

# DO THIS - Slots are extension points only
component: slot
props:
  name: "TMS/Component/SlotName"  # ✅ Only name and optional order
  order: 1                        # ✅ Optional ordering

Extensions Provide the Visual Elements​

# Extension component that targets the slot
components:
  - name: "CustomModule/ToolbarExtension"
    props:
      targetSlot: "TMS/Component/SlotName"
      order: 1
    layout:
      component: dropdown           # ✅ Extension provides the visual component
      props:
        label:
          en-US: Custom Actions
        icon: settings
        items:
          - label:
              en-US: Custom Action 1
          - label:
              en-US: Custom Action 2

Best Practices​

  1. Use Descriptive Slot Names: Follow the pattern ModuleName/ComponentName/SlotName for clear identification.

    • Examples: TMS/OrderGrid/ToolbarActions, TMS/ShipmentForm/AdditionalFields

  2. Define Clear Extension Points: Only create slots where extensions make logical sense.

    • Toolbars, form sections, navigation menus, dashboard widgets

  3. Use Order Properties: Implement consistent ordering for predictable extension placement.

    • Lower numbers render first, use increments of 10 for flexibility

  4. Document Slot Contracts: Clearly document what types of components are expected in each slot.

    • Specify allowed component types, required props, and layout constraints

  5. Limit Slot Depth: Avoid deeply nested slot structures that can become difficult to manage.

    • Maximum 2-3 levels of nested slots

  6. Consider Performance: Too many slots can impact rendering performance; use judiciously.

    • Limit to 5-10 slots per major component

  7. Slots Are Extension Points Only: Remember that slots themselves don't render visual content.

    • Don't add labels, icons, or items directly to slot components
    • Extensions targeting the slot provide the actual visual elements