PPA PPA: Task Interface

Inputs & Outputs

Actions in the user interface module generate inputs & outputs in the task interface.

When new inputs & outputs are generated, they flow into the task interface from bottom to top.

The one exception to this rule is the progress bar, explained here.

Elements & IDs

All visual input & output elements in the PPA task interface have a unique ID.

By default PPA will auto-generate IDs for all elements, but you can also provide your own.

Most of the user interface actions accept the optional element_id parameter.

The following rules explain how elements & IDs work:

  • Only 1 element with a given ID will be visible at any time
  • You can't display multiple elements with the same ID at the same time
  • Generating a new element with an existing ID will replace the existing element
  • When an element is replaced, the new element appears at the bottom

Using Element IDs

You should supply an element_id if you need to:

  • Create a progress bar & update its value
  • Prompt for input that may require multiple attempts
  • Replace an input or output element in the task interface with another

Progress Bars

The progress bar works differently to other elements.

It is recommended to always supply an element_id to a progress bar.

Fixed Position

A progress bar with a given ID will not move once it is generated.

Rather than being replaced in the interface, it will be updated.

Updating Values

When using a progress bar you'll probably need to update its value along the way.

You can do this by:

  • Assigning each progress bar a unique element_id
  • Supplying the element_id to the action when you need to update its value
Updating Progress Bars
1
2
3
4
5
6
7
8
9
- ppa.ui.output_progress:
    text: Adding user...
    percent: null
    element_id: add_user_progress

- ppa.ui.output_progress:
    text: Added user successfully
    percent: 100
    element_id: add_user_progress

Multiple Inputs Example

The step in this example will:

  • Ask the Task Operator to supply & confirm a new password
  • Output an error if the passwords don't match
  • Repeat all actions if the passwords don't match

Auto-Generated IDs

Currently there are no element_id parameters supplied to the actions.

Each input & output will have its ID auto-generated.

Example 1 - Without Element ID
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
  - name: Supply & Confirm New Password
    until: new_password == confirm_password
    actions:

      - ppa.ui.input_password:
          text: New Password
        save: new_password

      - ppa.ui.input_password:
          text: Confirm New Password
        save: confirm_password

      - ppa.ui.output_error:
          text: Passwords did not match. Please try again.
        when: new_password != confirm_password

The screenshot below shows what happens in PPA if the step repeats.

New input & output elements are generated each time the step runs.

PPA Screenshot

no-element-ids

Custom IDs

The task interface can become cluttered if the step repeats multiple times.

Supplying a unique element_id to each action will re-use the input & output elements.

Example 2 - With Element ID
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
  - name: Supply & Confirm New Password
    until: new_password == confirm_password
    actions:

      - ppa.ui.input_password:
          text: New Password
          element_id: new_password
        save: new_password

      - ppa.ui.input_password:
          text: Confirm New Password
          element_id: confirm_password
        save: confirm_password

      - ppa.ui.output_error:
          text: Passwords did not match. Please try again.
          element_id: new_password_error
        when: new_password != confirm_password

Again, the screenshot below shows what happens in PPA if the step repeats.

Each time the step runs, the existing input & output elements are re-used:

  • The first New Password input has been removed
  • A new one is presented at the bottom

No matter how many times the step repeats, there will only ever be 3 elements visible in PPA.

PPA Screenshot

element-ids