Best practice

When to use solution state (global state)

State manages the state of the app, including the UI's data and the user's interactions, and is best used in scenarios with a one-to-one relationship; for example, a field services person selects one job or task to complete, or a pilot selects one mission to fly.

Design Pattern: Singletons

Setup:

1. Set the ID to be stored in the solution state, using the set-state action. The ID is the least amount of data required to identify each job uniquely. The ID is used throughout the solution to reference the necessary data in each of the solution's jigs.

2. In the datasource queries use the ID to return the required data.

   • In a global datasource query reference the data required. The global datasource is referenced in each jig where the data is required.

   • In the individual jig 's datasource query. The query is configured to only return the exact data required for that jig using the ID as the unique identifier.

set-solution-state (action)

actions:
  - children:
      - type: action.set-state
        options:
          title: Task A
          state: [email protected]
          value: [email protected]

use-solution-state (datasource)

State resources and code samples:

• Solution (Global) State

• Set-state

• Reset-state

• Examples of state

When to use inputs

Inputs are used in complex apps to pass multiple variables between jigs using parameters, and is best used in scenarios where there is a one-to-many relationship, for example, a manager needs to check on the progress of each field service worker.

Design Pattern: Mediator

Setup:

1. Set up parameters in the jig that needs to pass data, then in the jig needing to receive the data set up inputs. Multiple parameters and inputs can be configured on a single jig.

2. In the components of the jig use expressions to reference the data passed in, for example, [email protected].

set-parameters

actions:
  - children:
      - type: action.go-to
        options:
          title: Team Progress
          linkTo: team-progress
          # Define what data the parameters must use
          # The parameters name is used in the receiving jig's input expression
          parameters:
            taskId: [email protected]
            taskStatus: [email protected]
            taskCost: [email protected]
            taskAssignee: [email protected]

use-input

Input resources and code samples:

• Passing data using inputs

• Input examples

When to use outputs

Outputs are used to combine multiple jigs into one jig. Outputs pass variables from each jig into the next jig, and is best used in scenarios where there is a many-to-one relationship, for example, a manager needs to report on the progress of the team. Creating a master detail form is another use case for outputs.

Design Pattern: Observer

Setup:

1. In the jig that will pass the data define the output property with an expression that will pass the variable, such as an ID.

2. In the composite jig, which combines multiple jigs, define the input property on the jig that must receive the variable.

team-progress (output)

title: Team list
type: jig.list
icon: contact
isHorizontal: true
isHorizontalScrollIndicatorHidden: false
isSelectable: true
hasActiveItem: true

datasources:
  team:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_DYNAMIC

      entities:
        - default/tasks
      query: |
        SELECT
         id, 
         '$.taskId',
         '$.Profile', 
         '$.taskAssignee',
         '$.team' 
        FROM [default/tasks] 
        WHERE '$.team' IS NOT NULL
# Set the output to use the Id defined in the set state
# The output- key will be passed in the input property,
# in the composite jig
outputs:
  output-key: [email protected]

data: [email protected]
item:
  type: component.list-item
  options:
    title: [email protected]
    horizontalItemSize: large
    progress: [email protected] = @ctx.solution.state.teamId ? 1 :0
    color:
      - when: [email protected] = @ctx.solution.state.teamId ? true :false
        color: color2
    isContained: true
    leftElement:
      element: image
      text: ""
      uri: [email protected]
    onPress:
      type: action.action-list
      options:
        actions:
          # set the solution state and the value as id of the current selected item
          - type: action.set-state
            options:
              state: [email protected]
              value: [email protected]

team

team-report (input)

Output resources and code samples:

• Passing data using outputs

• Output examples

Performance optimization

Using an id in your datasource enhances performance, particularly when handling large volumes of records.

datasource

datasources:
  team-update:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_DYNAMIC
      entities:
        - default/tasks
      query: |
        SELECT
         id,
         '$.taskId',
         '$.taskAssignee',
         '$.taskCost',
         '$.taskStatus',
         '$.taskProfile' 
        FROM [default/tasks] 
        WHERE id = @statId
      queryParameters:
        statId: [email protected]