Data Source Component

Introduction

The Data Source Component in CargoXplorer TMS is a crucial element that manages data fetching and storage. It acts as a wrapper for data sources, providing a standardized way to retrieve data from servers and maintain it in the application state.

YAML Structure

component: datasource
name: dataSourceName
props:
  name: dataSourceName
  queries:
    - name: queryName
      query:
        command: graphQLQuery
        path: resultPath
        variables: {}

Attribute Description

• component: (string) Must be set to "datasource" to use this component type.
• name: (string) A unique identifier for the data source component within its parent context.
• props: (object) Contains the configuration properties for the data source.
  • name: (string) The name of the data source, used for referencing in other components.
  • queries: (array) A list of query configurations used to populate the data source.
    • name: (string) Unique identifier for the query, used to store the result in the state.
    • query: (object) The query configuration.
      • command: (string) The GraphQL query to be executed.
      • path: (string) The path to the relevant data in the query result.
      • variables: (object) Variables to be used in the GraphQL query.

Examples

Basic GraphQL Query

component: datasource
name: employeeDataSource
props:
  name: employeeData
  queries:
    - name: getEmployees
      query:
        command: >-
          query($organizationId: Int!) {
            employees(organizationId: $organizationId) {
              id
              name
              email
            }
          }
        path: employees
        variables:
          organizationId: "{{ number organizationId }}"

Workflow Query

component: datasource
name: countryDataSource
props:
  name: countryData
  queries:
    - name: getCountries
      query:
        workflow:
          workflowId: "0e5ff225-366c-4a3b-80ce-3e2426fdd1fc"
          inputs:
            search: "U"

Complex Example with Multiple Queries

component: datasource
name: complexDataSource
props:
  name: complexData
  queries:
    - name: getUsers
      query:
        command: >-
          query($organizationId: Int!) {
            users(organizationId: $organizationId) {
              id
              name
            }
          }
        path: users
        variables:
          organizationId: "{{ number organizationId }}"
    - name: getDepartments
      query:
        command: >-
          query($organizationId: Int!) {
            departments(organizationId: $organizationId) {
              id
              name
            }
          }
        path: departments
        variables:
          organizationId: "{{ number organizationId }}"

Usage with Other Components

The Data Source Component is often used in conjunction with other components, such as the Collection Component, to render fetched data:

components:
  - component: datasource
    name: employeeDataSource
    props:
      name: employeeData
      queries:
        - name: getEmployees
          query:
            command: >-
              query($organizationId: Int!) {
                employees(organizationId: $organizationId) {
                  id
                  name
                  email
                }
              }
            path: employees
            variables:
              organizationId: "{{ number organizationId }}"
  - component: collection
    name: employeeList
    props:
      items: "{{ employeeData.getEmployees }}"
      itemName: employee
    children:
      - component: text
        props:
          type: p
          value: "{{ employee.name }} ({{ employee.email }})"

Best Practices

1. Use meaningful names for data sources and queries to improve code readability.
2. Leverage variables in GraphQL queries to make them dynamic and reusable.
3. Keep queries focused and specific to reduce unnecessary data fetching.
4. Use the path attribute to pinpoint exact data locations in complex query responses.
5. Consider using workflows for complex data fetching operations that require multiple steps or transformations.
6. Always handle potential errors and loading states when working with data sources.