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

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