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

- 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

  - 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

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

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

  - 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

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.