Component Actions in CargoXplorer

Introduction

Component Actions define the behavior of components in CargoXplorer. They handle events, fetch data, and perform various operations within the application.

When to Use Actions

Use actions when you need to:

• Respond to user interactions (e.g., button clicks)
• Update data in the application
• Navigate between screens
• Display notifications or dialogs
• Perform data validation
• Execute workflows or complex operations

Available Actions

CargoXplorer provides the following actions:

1. setVariables - Sets variables in the UI context
2. setActionsVariables - Sets variables specifically for use within actions
3. setParams - Sets parameters for the current Screen or Dialog (Query String)
4. setStore - Updates values in the application's store
5. setFields - Sets values for form fields
6. query - Executes a GraphQL query
7. mutation - Executes a GraphQL mutation
8. workflow - Executes a predefined workflow
9. navigate - Navigates to a different route
10. navigateBackOrClose - Navigates back or closes the current dialog
11. notification - Displays a notification message
12. dialog - Opens a dialog component
13. confirm - Shows a confirmation dialog
14. setValue - Sets the value of a specific form field
15. if - Conditionally executes actions
16. validateForm - Validates the current form
17. validateStore - Validates store variables
18. fileUpload - Uploads a file to temporary storage
19. fileDownload - Initiates a file download
20. refresh - Refreshes the current screen or component
21. setLocalStorage - Sets a value in local storage
22. forEach - Iterates over an array and executes actions
23. consoleLog - Logs a message to the console
24. submitForm - Submits a form
25. setAIContext - Sets the AI context for the current screen
26. createNewAIChat - Creates a new AI chat
27. openBarcodeScanner - Opens a barcode scanning UI and handles scan events

Let's explore each action in detail:

1. setVariables

Sets variables in the UI context.

Attributes:

• [variable_name]: The name and value of each variable to set

- setVariables:
    myForm.firstName: "John"
    myForm.lastName: "Doe"

2. setActionsVariables

Sets variables specifically for use within actions.

Attributes:

• [variable_name]: The name and value of each variable to set

- setActionsVariables:
    firstName: "John"
    lastName: "Doe"

3. setParams

Sets parameters for the current Screen or Dialog.

Attributes:

• [param_name]: The name and value of each parameter to set

- setParams:
    search: "John"
    filter: "active"

4. setStore

Updates values in the application's store.

Attributes:

• [store_path]: The path and new value to set in the store

- setStore:
    myForm.firstName: "John"
    myForm.lastName: "Doe"

5. setFields

Sets values for form fields.

Attributes:

• [field_name]: The name and new value for each form field

- setFields:
    myForm.firstName: "John"
    myForm.lastName: "Doe"

6. query

Executes a GraphQL query.

Attributes:

• command: The GraphQL query string
• variables: An object containing query variables
• onSuccess: Actions to perform if the query is successful
• onError: Actions to perform if the query fails

- query:
    command: "query { users { id name email }}"
    variables: {}
    onSuccess:
      - setStore:
          users: "{{ result.users }}"
    onError:
      - notification:
          message: "Error fetching users"

7. mutation

Executes a GraphQL mutation.

Attributes:

• command: The GraphQL mutation string
• variables: An object containing mutation variables
• onSuccess: Actions to perform if the mutation is successful
• onError: Actions to perform if the mutation fails

- mutation:
    command: "mutation CreateUser($name: String!) { createUser(name: $name) { id name } }"
    variables:
      name: "John Doe"
    onSuccess:
      - notification:
          message: "User created successfully"
    onError:
      - notification:
          message: "Error creating user"

8. workflow

Executes a predefined workflow.

Attributes:

• workflowId: The unique identifier of the workflow to execute
• inputs: An object containing input values for the workflow
• onSuccess: Actions to perform if the workflow completes successfully
• onError: Actions to perform if the workflow fails

- workflow:
    workflowId: "f07103ce-d0b4-40fe-8a59-33eb851c8691"
    inputs:
      name: "John"
      email: "[email protected]"
    onSuccess:
      - notification:
          message: "Workflow completed"
    onError:
      - notification:
          message: "Workflow failed"

9. navigate

Navigates to a different route in the application.

Attributes:

• to: The route path to navigate to

- navigate:
    to: "/dashboard"

10. navigateBackOrClose

Navigates back to the previous route or closes the current dialog.

Attributes:

• result: The result to pass back when closing a dialog (optional)

- navigateBackOrClose:
    result: false

11. notification

Displays a notification message.

Attributes:

• message: The notification message (can be localized)
• variant: The style variant of the notification (e.g., success, error, warning)

- notification:
    message:
      en-US: "This is a notification"
    variant: success

12. dialog

Opens a dialog component.

Attributes:

• name: A unique identifier for the dialog
• props: Properties to pass to the dialog component
• onClose: Actions to perform when the dialog is closed
• component: The definition of the dialog component

- dialog:
    name: createDialog
    props:
      title:
        en-US: "Create New Item"
    onClose:
      - setStore:
          myForm.firstName: "{{ result.firstName }}"
    component:
      # Dialog component definition here

13. confirm

Shows a confirmation dialog (available for form fields only).

Attributes:

• title: The title of the confirmation dialog
• message: The message to display in the dialog
• onConfirm: Actions to perform if the user confirms
• onCancel: Actions to perform if the user cancels

- confirm:
    title: "Delete User"
    message: "Are you sure you want to delete this user?"
    onConfirm:
      - mutation:
          command: "mutation DeleteUser($id: ID!) { deleteUser(id: $id) }"
          variables:
            id: "{{ userId }}"
    onCancel:
      - notification:
          message: "Deletion cancelled"

14. setValue

Sets the value of a specific form field (available for form fields only).

Attributes:

• field: The name of the field to set
• value: The new value for the field

- setValue:
    field: "myForm.firstName"
    value: "John"

15. if

Conditionally executes actions based on a specified condition.

Attributes:

• condition: The condition to evaluate
• then: Actions to perform if the condition is true
• else: Actions to perform if the condition is false

- if: "{{ eval myForm.firstName === 'John' }}"
  then:
    - notification:
        message: "Hello John!"
  else:
    - notification:
        message: "Hello {{ myForm.firstName }}"

16. validateForm

Validates the current form fields against a specified schema or the default form schema.

Attributes:

• validationSchema: An object defining the validation rules for form fields. If not provided, the form will be validated against the default form schema.

- validateForm:
    validationSchema: # optional
      firstName:
        required:
          message: "First Name is required"
        min:
          length: 2
          message: "First Name should be at least 2 characters"

17. validateStore

Validates store variables against a specified schema.

Attributes:

• validationSchema: An object defining the validation rules for store variables

- validateStore:
    validationSchema:
      "myForm.email":
        required:
          message: "Email is required"
        email:
          message: "Invalid email format"

18. fileUpload

Uploads a file to temporary storage.

Attributes:

• accept: File types to accept (e.g., ".jpg,.png")
• maxSize: Maximum file size in MB
• multiple: Whether to allow multiple file uploads
• onSuccess: Actions to perform if the upload is successful
• onError: Actions to perform if the upload fails

- fileUpload:
    accept: ".jpg,.png"
    maxSize: 5
    multiple: false
    onSuccess:
      - notification:
          message: "File uploaded: {{ result.fileName }}"
    onError:
      - notification:
          message: "Upload failed"

19. fileDownload

Initiates a file download from a specified URL.

Attributes:

• url: The URL of the file to download

- fileDownload:
    url: "https://example.com/files/document.pdf"

20. refresh

Refreshes the current screen or a specific component.

Attributes:

• componentName: The name of the component to refresh (optional)

- refresh: "dataGrid"

21. setLocalStorage

Sets a value in the browser's local storage.

Attributes:

• key: The key to use in local storage
• value: The value to store

- setLocalStorage:
    key: "userPreferences"
    value: "{{ userPreferences }}"

22. forEach

Iterates over an array and executes specified actions for each item.

Attributes:

• items: The array to iterate over
• item: The name to use for the current item in the iteration
• actions: The actions to perform for each item

- forEach:
    items: "{{ myForm.items }}"
    item: "currentItem"
    actions:
      - notification:
          message: "Processing {{ currentItem.name }}"

23. consoleLog

Logs a message to the console.

Attributes:

• message: The message to log
• level: The log level (optional, defaults to "info". Other levels: "error", "warn", "debug", "log")

- consoleLog:
    level: "info" # optional
    message: "Hello World"
- consoleLog: "Hello World" # simplified version

24. submitForm

Submits a form.

Attributes:

• formName: The name of the form to submit

- submitForm:
    formName: "myForm"

Best Practices

1. Use meaningful names for your actions to improve readability.
2. Group related actions together for better organization.
3. Use conditional actions (if) to handle different scenarios.
4. Utilize setActionsVariables for temporary data that's only needed within the action sequence.
5. Always handle both success and error cases in asynchronous actions (query, mutation, workflow).
6. Use validateForm before submitting data to ensure data integrity.
7. Leverage the forEach action for batch operations on arrays.

setAIContext

Sets the AI context for the current screen.

Attributes:

• entities: The entities to set in the AI context
• quickQuestions: The common questions to set in the AI context

- setAIContext:
    entities:
      - entityType: "{{ entityType }}"
        entityName: "{{ entityName }}"
        entityId: "{{ entityId }}"
        displayText: "{{ entityName }}"
    quickQuestions:
      - "What is the name of the item?"
      - "What is the description of the item?"
      - "What is the price of the item?"

createNewAIChat

Creates a new AI chat. This action is used to create a new AI chat for the current screen. If the AI chat is closed, the action will open an AI window.

Attributes:

• title: The title of the AI chat
• topic: The topic of the AI chat
• entities: The entities to set in the AI chat
• quickQuestions: The quick questions to set in the AI chat
• question: The question to set in the AI chat
• autoExecute: Whether to automatically execute the AI chat (optional, defaults to false)

- createNewAIChat:
    title: "My AI Chat"
    topic: "{{ entityName }}"
    entities:
      - entityType: "{{ entityType }}"
        entityName: "{{ entityName }}"
        entityId: "{{ entityId }}"
        displayText: "{{ entityName }}"
    quickQuestions:
      - "What is the name of the item?"
    question: "What is the name of the item?"
    autoExecute: true # optional, defaults to false

27. openBarcodeScanner

Opens a dedicated barcode scanning UI. Supports single-scan (default) and multi-scan flows. In multi-scan mode, the UI remains open until the user completes scanning or a maxBarcodes limit is reached.

Attributes:

• title: Optional title text for the scanner UI
• minBarcodeLength: Minimum length for recognized barcodes (defaults to 1 if omitted)
• allowMultiple: Whether to allow scanning multiple barcodes before closing (optional, defaults to false)
• maxBarcodes: Maximum number of barcodes to collect in multi-scan mode (optional). When set and allowMultiple is true, the dialog auto-closes after this many scans
• onScan: Actions to execute after each successful scan; receives result.data and, when available, result.format
• onComplete: Actions to execute when the scanner UI finishes multi-scan and closes (user taps Done or maxBarcodes reached). Receives result.barcodes (array of strings)
• onClose: Actions to execute when the scanner UI is closed without completing (for example, user cancels). May include result.barcodes collected so far if any

Notes:

• Single-scan (default): the dialog closes immediately after the first scan; onScan runs once and onComplete is not used.
• Multi-scan (allowMultiple: true):
  • Without maxBarcodes, users close the dialog via the UI when finished; onComplete receives all collected barcodes as result.barcodes.
  • With maxBarcodes, the dialog auto-closes when the limit is reached; onComplete receives the final list as result.barcodes.
• result.format may vary by platform; guard its usage.

Single-scan example:

- openBarcodeScanner:
    title: "Scan Item"
    minBarcodeLength: 8
    onScan:
      - setStore:
          scannedBarcode: "{{ result.data }}"
      - notification:
          message: "Scanned: {{ result.data }}"
    onClose:
      - notification:
          message: "Scanner closed"

Multi-scan until user completes:

- openBarcodeScanner:
    title: "Scan multiple items"
    allowMultiple: true
    minBarcodeLength: 8
    onScan:
      - notification:
          message: "Captured: {{ result.data }}"
    onComplete:
      - setStore:
          scannedBarcodes: "{{ result.barcodes }}"
      - notification:
          message: "Collected {{ result.barcodes.length }} barcodes"

Multi-scan with maximum count (auto-close):

- openBarcodeScanner:
    title: "Scan up to 5 items"
    allowMultiple: true
    maxBarcodes: 5
    minBarcodeLength: 8
    onScan:
      - notification:
          message: "Added: {{ result.data }}"
    onComplete:
      - setStore:
          scannedBarcodes: "{{ result.barcodes }}"
      - notification:
          message: "Scanning completed ({{ result.barcodes.length }} items)"

Conditional handling by format (single or multi-scan):

- openBarcodeScanner:
    title: "Scan or log"
    minBarcodeLength: 10
    allowMultiple: true
    maxBarcodes: 3 # optional
    onScan:
      - if:
          condition: "{{ eval result.format === 'QR_CODE' }}"
          then:
            - navigate:
                to: "/qr-details"
          else:
            - mutation:
                command: "logBarcodeScan"
                variables:
                  barcodeData: "{{ result.data }}"
                  format: "{{ result.format }}"
            - notification:
                message: "Barcode logged"
    onComplete:
      - notification:
          message: "Finished scanning"

Integrating with a button:

component: button
props:
  text: "Scan barcodes"
  onClick:
    - openBarcodeScanner:
        title: "Scan Items"
        allowMultiple: true
        maxBarcodes: 10
        minBarcodeLength: 8
        onScan:
          - consoleLog:
              message: "Scanned: {{ result.data }}"
        onComplete:
          - setStore:
              scannedBarcodes: "{{ result.barcodes }}"
          - refresh: "dataGrid"