Skip to main content

Comments Component in CargoXplorer TMS

Introduction​

The Comments Component enables users to add, view, and manage threaded discussions on any entity in CargoXplorer TMS. It provides a unified communication system for tracking notes, discussions, and updates related to orders, shipments, contacts, and other business entities.

Key Concepts:

  • Each comment belongs to a specific thread (e.g., "Billing", "Operations", "CustomerService")
  • A single comments component instance displays comments from only one thread
  • When no thread is specified, comments use the "default" thread for that entity
  • Threads help categorize discussions and control access through permissions

YAML Structure​

component: comments
props:
  parentId: "{{ entity.id }}"
  parentType: "Order"
  thread: "Operations" # Optional: Specifies which thread to display/create comments in
  title:
    en-US: "Operations Comments"
  options:
    allowAttachments: true
    allowReplies: true
    sortOrder: "desc"
    showTimestamps: true
    showAuthor: true
    autoRefresh: false
    refreshInterval: 30
  pagination:
    pageSize: 10
  permissions:
    create: "Comments/Create"
    view: "Comments/View"
    edit: "Comments/Edit"
    delete: "Comments/Delete"

Attribute Description​

Core Attributes​

  • component: (string) Required - Must be set to "comments" to use this component type.
  • props: (object) Required - Contains the configuration properties for the comments component.

Props Attributes​

Required Properties​

  • parentId: (string) Required - The ID of the parent entity to which comments are attached. Typically uses a variable reference like {{ entity.id }}.
  • parentType: (string) Required - The type of the parent entity. Must match the entity name in the system (e.g., "Order", "Job", "Contact", "Shipment").

Optional Properties​

  • thread: (string) - Specifies which thread this component displays and creates comments in.

    • If not specified, uses the "default" thread for the parent entity
    • Must match a thread name that exists in the system for this entity type
    • Each comments component instance can only work with one thread

  • title: (object) - Localized title for the comments section.

    • Supports multiple languages (e.g., en-US, es-ES, fr-FR)
    • Default: "Comments" in the user's language

  • options: (object) - Configuration options for comment behavior and display.

    • allowAttachments: (boolean) - Whether users can attach files to comments
      • Default: true
    • allowReplies: (boolean) - Whether users can reply to existing comments (nested threading)
      • Default: true
    • sortOrder: (string) - The order in which comments are displayed
      • Options: "asc" (oldest first), "desc" (newest first)
      • Default: "desc"
    • showTimestamps: (boolean) - Whether to display comment timestamps
      • Default: true
    • showAuthor: (boolean) - Whether to display comment authors
      • Default: true
    • autoRefresh: (boolean) - Whether to automatically refresh comments periodically
      • Default: false
    • refreshInterval: (number) - Interval in seconds for auto-refresh (if enabled)
      • Default: 30
      • Minimum: 10

  • pagination: (object) - Pagination configuration.

    • pageSize: (number) - Number of comments to display per page
      • Default: 10
      • Range: 5-50

  • permissions: (object) - Permission control for comment operations in this component.

    • create: (string) - Permission required to create comments
    • view: (string) - Permission required to view comments
    • edit: (string) - Permission required to edit comments
    • delete: (string) - Permission required to delete comments
    • Note: These permissions can be overridden by thread-specific permissions if configured

Thread Configuration​

Threads are configured at the system level for each entity type. The comments component references these pre-configured threads by name. Common thread examples include:

  • General/Default: For general discussions (automatically used when no thread is specified)
  • Billing: For accounting and payment discussions
  • Operations: For operational and logistics notes
  • CustomerService: For customer-facing communications
  • Internal: For internal team discussions

Each thread can have its own:

  • Display name and description
  • Permission requirements
  • Visibility rules
  • Notification settings

Examples​

Basic Comments (Default Thread)​

component: comments
props:
  parentId: "{{ order.id }}"
  parentType: "Order"

This creates a comments component using the default thread for Orders. All general comments will appear here.

Specific Thread Comments​

component: comments
props:
  parentId: "{{ order.id }}"
  parentType: "Order"
  thread: "Billing"
  title:
    en-US: "Billing Discussion"
    es-ES: "Discusión de Facturación"
  permissions:
    create: "Billing/Comments/Create"
    view: "Billing/Comments/View"

This component only shows and creates comments in the "Billing" thread.

Multiple Thread Components on Same Page​

To display multiple threads for the same entity, use multiple comment components:

component: container
children:
  - component: row
    children:
      - component: col
        props:
          span: 12
        children:
          - component: comments
            props:
              parentId: "{{ order.id }}"
              parentType: "Order"
              thread: "CustomerService"
              title:
                en-US: "Customer Communications"
      - component: col
        props:
          span: 12
        children:
          - component: comments
            props:
              parentId: "{{ order.id }}"
              parentType: "Order"
              thread: "Operations"
              title:
                en-US: "Operations Notes"

Comments with Custom Configuration​

component: comments
props:
  parentId: "{{ shipment.id }}"
  parentType: "Shipment"
  thread: "Tracking"
  title:
    en-US: "Shipment Updates"
  options:
    allowAttachments: false # No attachments for tracking updates
    allowReplies: false # Linear updates only
    sortOrder: "asc" # Show oldest first for chronological tracking
    autoRefresh: true # Auto-refresh for real-time updates
    refreshInterval: 15
  pagination:
    pageSize: 25

Comments in a Tab Layout​

component: tabs
children:
  - component: tab
    props:
      label:
        en-US: "General"
    children:
      - component: comments
        props:
          parentId: "{{ entity.id }}"
          parentType: "Order"
          # No thread specified - uses default
  - component: tab
    props:
      label:
        en-US: "Billing"
    children:
      - component: comments
        props:
          parentId: "{{ entity.id }}"
          parentType: "Order"
          thread: "Billing"
  - component: tab
    props:
      label:
        en-US: "Operations"
    children:
      - component: comments
        props:
          parentId: "{{ entity.id }}"
          parentType: "Order"
          thread: "Operations"

Comments with Restricted Permissions​

component: comments
props:
  parentId: "{{ contact.id }}"
  parentType: "Contact"
  thread: "CreditNotes"
  title:
    en-US: "Credit Assessment"
  permissions:
    create: "Credit/Comments/Create"
    view: "Credit/Comments/View"
    edit: "Credit/Comments/Edit/Own" # Can only edit own comments
    delete: "Credit/Comments/Delete/Admin" # Only admins can delete

Read-Only Comments​

component: comments
props:
  parentId: "{{ job.id }}"
  parentType: "Job"
  thread: "SystemLogs"
  title:
    en-US: "System Activity"
  options:
    allowAttachments: false
    allowReplies: false
  permissions:
    view: "System/Logs/View"
    # No create, edit, or delete permissions - read only

Best Practices​

1. Thread Strategy​

  • Use Default Thread: For general discussions that don't fit specific categories
  • Create Specific Threads: For departmental or functional categorization
  • One Component Per Thread: Each comments component instance handles only one thread
  • Multiple Components: Use multiple components to show different threads simultaneously

2. Thread Naming Conventions​

  • Use clear, descriptive thread names (e.g., "Billing", not "Thread1")
  • Maintain consistency across entity types where applicable
  • Consider prefixing with department or function (e.g., "Finance_Billing", "Ops_Tracking")

3. Permission Strategy​

  • Set thread-level permissions at the system configuration level
  • Use component-level permissions to further restrict access if needed
  • Consider read-only threads for audit trails or system logs
  • Implement "Own" permissions for users to edit/delete only their comments

4. Performance Considerations​

  • Limit pageSize for threads with high volume
  • Use autoRefresh sparingly - only for real-time collaboration needs
  • Consider disabling allowAttachments for high-traffic threads
  • Separate operational threads from customer-facing threads

5. User Experience​

  • Provide clear thread titles that indicate purpose
  • Use consistent thread organization across similar entities
  • Enable allowReplies for discussion threads, disable for linear logs
  • Sort chronologically (asc) for tracking, newest first (desc) for discussions

6. Integration Patterns​

  • Place related thread components near relevant data sections
  • Use tabs to organize multiple threads for the same entity
  • Consider collapsible sections for optional thread views
  • Maintain visual hierarchy with appropriate spacing and borders

7. Data Governance​

  • Establish thread retention policies
  • Consider separate threads for internal vs. external communications
  • Use thread permissions to comply with data privacy requirements
  • Implement audit trails for sensitive discussion threads