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_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 |
|
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_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_email
Present a text input field used to supply an email address.
The address format will be validated, & the task operator will be re-prompted if validation fails.
Minimum Plugin Version: 3.2.0
Input
-
text: the title of the input field
-
element_id: an optional ID for the interface element (see here for more)
Output
The email address submitted by the task operator.
Example
1 2 3 |
|
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.
The file will be made available to be downloaded by the task operator.
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_multiline_text
Present a multiline text input field.
Minimum Plugin Version: 3.4.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 tofalse
) -
element_id: an optional ID for the interface element (see here for more)
-
lines: Denotes how many lines the input element should have (defaults to 15)
Output
The string submitted by the Task Operator. Any line breaks will be denoted by a `
`.
Example
Prompting for a multiline comment & saving it as a new variable called comment.
1 2 3 4 |
|
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 tofalse
) -
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_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_sensitive_file
Ask the Task Operator to upload a file to the PPA task container.
The file contents can be used & inspected by the task.
The file will not be made available to be downloaded by the task operator.
Minimum PPA Appliance Version: 2.6.3
Minimum Plugin Version: 3.4.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_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 |
|
If the first & second rows were chosen selected_rows
would be:
1 2 |
|
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 tofalse
) -
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.
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_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_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_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_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_tabbed_table
Display a table with multiple tabs.
Minimum Plugin Version: 3.5.0
Input
-
text: the table title
-
header: a list of column names
-
tabs: a dictionary containing tab names & their rows as a list of lists
-
element_id: an optional ID for the interface element (see here for more)
Output
Nothing is outputted by this action.
Example
Presenting a table with 2 tabs, where each tab contains a table with 3 columns & 1 row.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
ppa.ui.
output_table
Display a table.
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 |
|