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.

- 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

  - 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

- 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

- 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

- 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.

- 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

- 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

- 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

- 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%

- 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

- ppa.ui.output_table:
    text: Cities
    header:
      - Name
      - Country
    rows:
      - - Paris
        - France
      - - London
        - England
      - - Brussels
        - Belgium