PPA PPA: User Interface

Summary

This module contains actions for interacting with PPA Task Operators.

PPA Task Interface

See Task Interface for more information on inputs & outputs in PPA.

Actions

ppa.ui.

input_accept

Present a labelled button with text, & wait until it is clicked.

Minimum Plugin Version: 1.0.0

Input
  • text: the button label
  • element_id: the ID of the element in the task interface (see here for more)
Output

Nothing is returned from this action.

Example
1
2
- ppa.ui.input_accept:
    text: Start

ppa.ui.

input_choice

Present a dropdown & wait for a choice.

Minimum Plugin Version: 1.0.0

Input
  • text: the title of the dropdown list

  • options: one or more values to populate the dropdown list (see the examples for more information)

  • element_id: an optional ID for the interface element (see here for more)

Output

The string value chosen by the task operator.

Example 1: Simple

Prompting for a team & saving the choice as a new variable called team.

1
2
3
4
5
6
7
- ppa.ui.input_choice:
    text: Select a Team
    options:
      - Sales
      - Marketing
      - Engineering
  save: team
Example 2: Custom Ordering

Prompting for a quantity & saving the choice as a new variable called quantity

  • To avoid list values being automatically sorted, this example uses a dictionary as input
  • Each key is a dropdown item, & its value is its order in the list
1
2
3
4
5
6
7
8
9
  - ppa.ui.input_choice:
      text: Select a Quantity
      options:
        One: 1
        Two: 2
        Three: 3
        Four: 4
        Five: 5
    save: quantity

ppa.ui.

input_confirm

Present two labelled buttons to offer a choice, & wait until one is clicked.

Minimum Plugin Version: 1.0.0

Input
  • text: the text to display above the 2 buttons

  • confirm: the label of the button that returns true (defaults to Confirm)

  • cancel: the label of the button that returns false (defaults to Cancel)

  • element_id: an optional ID for the task interface element (see here for more)

Output

A boolean (true or false).

Example
1
2
3
4
5
- ppa.ui.input_confirm:
    text: Would you like to continue?
    confirm: Yes
    cancel: No
  save: confirm

ppa.ui.

input_file

Ask the Task Operator to upload a file to the PPA task container.

The file contents can be used & inspected by the task.

Minimum Plugin Version: 1.2.0

Input
  • text: text to display with the upload component
  • accept: optional file extension or MIME type to accept
  • element_id: the ID of the element in the task interface (see here for more)
Output

A single UploadedFile dictionary.

Example
1
2
3
4
- ppa.ui.input_file:
    text: Please upload a users CSV file
    accept: .csv
  save: users_csv

ppa.ui.

input_password

Present a password field.

The password will be obfuscated in the interface & not stored in PPA.

Minimum Plugin Version: 1.0.0

Input
  • text: the title of the input field

  • meter: set to true to show a password strength meter (defaults to false)

  • element_id: an optional ID for the interface element (see here for more)

Output

The password supplied by the task operator.

Example
1
2
3
4
- ppa.ui.input_password:
    text: Enter a Password
    meter: true
  save: new_password

ppa.ui.

input_password_confirm

Present 'New Password' & 'Confirm Password' input fields.

This action will loop until both supplied passwords match.

The passwords are obfuscated in the interface & not stored in PPA.

Minimum Plugin Version: 1.0.0

Input

This action takes no inputs.

Output

The password supplied by the task operator.

Example
1
2
- ppa.ui.input_password_confirm:
  save: new_password

ppa.ui.

input_table

Present a table & wait for a selection.

Minimum Plugin Version: 3.0.0

Input
  • text: the table title

  • header: a list of column names

  • rows: the table contents as a list of lists, where each inner list is a row of values

  • minimum: The minimum number of acceptable selections

  • maximum: The maximum number of acceptable selections

  • element_id: an optional ID for the interface element (see here for more)

Output

A list of the selected table row indices (zero-indexed).

Example

Presenting a table of cities & countries & saving the selection as selected_rows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- ppa.ui.input_table:
    title: Select Cities
    header:
      - City
      - Country
    rows:
      - - Paris
        - France
      - - London
        - England
      - - Cardiff
        - Wales
  save: selected_rows

If the first & second rows were chosen selected_rows would be:

1
2
  - 0
  - 1

ppa.ui.

input_text

Present a text input field.

Minimum Plugin Version: 1.0.0

Input
  • text: the title of the input field

  • default: a default value for the input field (defaults to empty)

  • pattern: a regular expression to validate the supplied value

  • required: set to true to require a value before submission (defaults to false)

  • element_id: an optional ID for the interface element (see here for more)

Output

The string submitted by the task operator.

Example

Prompting for a username & saving it as a new variable called username.

  • The value is required, & must match the format firstname.surname

  • A folded string (the > character) escapes any special pattern characters

1
2
3
4
5
6
- ppa.ui.input_text:
    text: Username
    required: true
    pattern: >
      [A-Za-z]+\.[A-Za-z]+
  save: username

ppa.ui.

output_error

Present some error text in red.

Minimum Plugin Version: 1.0.0

Input
  • text: the text to display

  • element_id: an optional ID for the interface element (see here for more)

Output

Nothing is outputted by this action.

Example
1
2
- ppa.ui.output_error:
    text: Something went wrong

ppa.ui.

output_file

Allow the Task Operator to download a file from the PPA task.

Minimum Plugin Version: 1.2.0

Input
  • text: text to display with the upload component
  • data: file contents
  • filename: name of the file
  • type: optional MIME type (defaults to application/octet-stream)
  • element_id: the ID of the element in the task interface (see here for more)
Output

Nothing is outputted by this action.

Example
1
2
3
4
5
- ppa.ui.output_file:
    text: Please download the CSV report
    filename: report.csv
  load:
    data: csv_report

ppa.ui.

output_info

Present some basic text.

Minimum Plugin Version: 1.0.0

Input
  • text: the text to display

  • element_id: an optional ID for the interface element (see here for more)

Output

Nothing is outputted by this action.

Example
1
2
- ppa.ui.output_info:
    text: Welcome to PPA

ppa.ui.

output_markdown

Present a markdown document to display.

Minimum Plugin Version: 1.0.0

Input
  • doc: the markdown document to display

  • element_id: an optional ID for the interface element (see here for more)

Output

Nothing is outputted by this action.

Example
1
2
3
4
5
- ppa.ui.output_markdown:
    doc: >
      # Markdown Header

      Document text

ppa.ui.

output_progress

Present a progress bar with an indeterminate or % value.

The value null is deemed indeterminate & will display an animation.

Minimum Plugin Version: 1.0.0

Input
  • text: the title of the progress bar

  • percent: an integer progress value or null

  • element_id: an optional ID for the interface element (see here for more)

Progress Bar Element IDs

It is essential to supply an element_id to any progress bar whose value will be set more than once.

Output

Nothing is outputted by this action.

Example
  • Showing an indeterminate progress bar

  • waiting for a button click

  • Updating the progress bar to 100%

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- ppa.ui.output_progress:
    text: Waiting to continue...
    percent: null
    element_id: action_progress
- ppa.ui.input_accept:
    text: Continue
- ppa.ui.output_progress:
    text: Continuing
    percent: 100
    element_id: action_progress

ppa.ui.

output_table

Present a table the task operator.

Minimum Plugin Version: 1.0.0

Input
  • text: the table title

  • header: a list of column names

  • rows: the table contents as a list of lists, where each inner list is a row of values

  • element_id: an optional ID for the interface element (see here for more)

Output

Nothing is outputted by this action.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- ppa.ui.output_table:
    text: Cities
    header:
      - Name
      - Country
    rows:
      - - Paris
        - France
      - - London
        - England
      - - Brussels
        - Belgium