Skip to content

Pop up UI Accessory Views

Jump to bottom
Simone Martorelli edited this page Nov 19, 2024 · 18 revisions

Pop-up UI can contain the following accessory views

Whitebox White box example

To display a whitebox style pop-up pass -accessory_view_type whitebox parameter.

Whitebox has a mandatory -accessory_view_payload parameter as quoted text which will be displayed inside the whitebox.

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type whitebox -accessory_view_payload "Test accessory view" -main_button_label "OK"

Whitebox also supports a Markdown styled text as a payload, it will render all supported Markdown flavors.

White box markdown example

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type whitebox -accessory_view_payload "## This is markdown\n **It's cool**\n _It supports all major flavors_" -main_button_label "OK"

Timer Timer example

To display a timer style pop-up pass -accessory_view_type timer parameter.

Timer has a mandatory -accessory_view_payload parameter as quoted text which determines the label for the timer accessory view and a mandatory -timeout parameter as integer value to define the number of seconds until timeout is called by the pop-up.
To define the timer position inside the label use %@.

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type timer -accessory_view_payload "Time left: %@" -timeout 300 -main_button_label "OK"

Image Image example

To display an image style pop-up pass -accessory_view_type image parameter.

Image has a mandatory -accessory_view_payload parameter, which is URL of the image or absolute path to the image as quoted text. If image path or URL does not exist, error message is printed.

Error message when image does not exist:
Error while trying to load image at https://atlascorps.org/wp-content/2018/03/IBM-Logo.png, error: (null)

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type image -accessory_view_payload "https://atlascorps.org/wp-content/uploads/2018/03/IBM-Logo.png" -main_button_label "OK"

Video Video example

To display a video style pop-up pass -accessory_view_type video parameter.

Deprecated since 2.3.0: Video has a mandatory -accessory_view_payload parameter as direct URL of the video or absolute path to the video file as quoted text. If video path or URL does not exist or is incorrect, error message is printed.

Video has a mandatory -accessory_view_payload parameter as quoted text, which can contain one or more of the following parameters:
/url URL tells the agent that the input field cannot be empty;
/autoplay optional boolean flag to set the video to autoplay or not;
/delay INTEGER optional delay in seconds for the autoplay of the video. By default it is set to 1 second.

Error message when video is incorrect:
Unable to load video from https://direct.link.to/video.mov

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type video -accessory_view_payload "/url https://direct.link.to/video.mov /autoplay /delay 3" -main_button_label "OK"

Input Input example

To display an input style pop-up pass -accessory_view_type input parameter.

Deprecated since 2.3.0: Input has a mandatory -accessory_view_payload parameter as quoted text that represents the placeholder of the field.

Input has a mandatory -accessory_view_payload parameter as quoted text, which can contain one or more of the following parameters:
/required tells the agent that the input field cannot be empty;
/placeholder the placeholder of the input field;
/value the pre filled value of the input field;
/title Some text which will be shown as title on top of the input field.

On the click of the main button the value of the field is printed before the agent exit (ex. some).

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type input -accessory_view_payload "/placeholder Enter your name /title Name field /required" -main_button_label "OK"

Secure input Secured input example

To display a secure input style pop-up pass -accessory_view_type secureinput parameter.

Deprecated since 2.3.0
Secure input has a mandatory -accessory_view_payload parameter as quoted text that represents the placeholder of the field.

Secure input has a mandatory -accessory_view_payload parameter as quoted text, which can contain one or more of the following parameters:
/required tells the agent that the input field cannot be empty;
/placeholder the placeholder of the input field;
/title Some text which will be shown as title on top of the input field.

On the click of the main button the value of the field is printed before the agent exit (ex. some).

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type secureinput -accessory_view_payload "/placeholder Enter password /title Password /required" -main_button_label "OK"

Progress bar Progress bar example

To display a progress bar style pop-up pass -accessory_view_type progressbar parameter.

Progress bar has a mandatory -accessory_view_payload parameter as quoted text, which will control behaviour and looks of the progress bar.

Payload parameter must contain at least /percent 0 string, which will determine initial progress shown. It can also contain following optional control strings:
/top_message Some message which will be shown in the dialog just above the progress bar itself;
/bottom_message Some message which will be shown in the dialog just below the progress bar itself;
/user_interruption_allowed true which will display a Cancel button during the progress;
/user_interaction_enabled true which will display all the defined buttons for the pop-up even if the progress bar has not finished yet. /exit_on_completion true (available from v2.4.0) which will make the pop-up UI automatically exit at the end of the progress.

To control progress on the progress bar you can pass /percent number, which can be anything between 0 and 100 at which point the progress is finished and all the buttons passed at the beginning will be shown. You can also dynamically update /top_message and /bottom_message values.

The progress bar could also show an indeterminate behaviour, to do so use /percent indeterminate.

PN: you can pass from an indeterminate behaviour to a determinate one defining a different /percent but not the other way around.

From v3.0.0 only on Onboarding UI it's possible to use automatic as "payload" for the progressBarPayload JSON key to let the progress bar advance following the onboarding flow.

Progress bar example

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type progressbar -accessory_view_payload "/percent 25 /top_message ProgressBar top message /bottom_message Progress" -main_button_label "OK"

Drop down (available from v2.3.0) Drop down selector box example

To display a drop down style selector pass -accessory_view_type dropdown parameter.

Drop down has a mandatory -accessory_view_payload parameter as quoted text, which provide data to the drop down selector box.

Payload parameter must contain at least /list ITEM string, which will determine at least one possible choice for the selector. Any other item for the drop down selector can be added after a "new line" escaping char "\n" (Example: "/list ITEM\nITEM\nITEM"). It can also contain following optional control strings:
/selected INDEX integer index (first item is 0) which will select the related item from the passed array;
/placeholder Some text which will be shown as placeholder if no selection has been made;
/title Some text which will be shown as title for the drop down selector.

On the click of the main button the index of the selected item is printed before the agent exit (ex. 0).

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type dropdown -accessory_view_payload "/list First\nSecond\nThird /selected 0"

Drop down selector box example
HTML (available from v2.3.0) Parsed HTML example

To display an HTML formatted text pass -accessory_view_type html parameter.

HTML accessory view has a mandatory -accessory_view_payload parameter as quoted text, which provide the HTML formatted text that needs to be shown.
This text supports all the possible style customisation available for NSAttributedString.

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type html -accessory_view_payload "<h1>Hello, world!</h1>this is a line of text<br><br><code>this is a code block<br>this is the second line of a code block</code><br>this is <span style="color: #ff0000">red</span> text"

HTML White box (available from v2.3.0) Parsed HTML in a white box example

To display an HTML formatted text inside a white box pass -accessory_view_type htmlwhitebox parameter.

HTML White box accessory view has a mandatory -accessory_view_payload parameter as quoted text, which provide the HTML formatted text that needs to be shown.
This text supports all the possible style customisation available for NSAttributedString.

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type htmlwhitebox -accessory_view_payload "<h1>Hello, world!</h1>this is a line of text<br><br><code>this is a code block<br>this is the second line of a code block</code><br>this is <span style="color: #ff0000">red</span> text"

Checklist (available from v2.3.0) Checklist example

To display a list of elements with check boxes pass -accessory_view_type checklist parameter.

Checklist has a mandatory -accessory_view_payload parameter as quoted text, which provide the data to be shown.

Payload parameter must contain at least /list ITEM string, which will determine at least one possible choice for the selector. Any other item for the checklist can be added after a "new line" escaping char "\n" (Example: "/list ITEM\nITEM\nITEM"). It can also contain following optional control strings:
/preselection ITEM_INDEX ITEM_INDEX to pass to the accessory view an array of preselected indexes; /required to make at least the selection of one element mandatory (pop-up main button disabled);
/complete to make the selection of all the item of the checklist mandatory (this override the /required control string);
/title Some text which will be shown as title for the checklist; /radio (available from v2.5.0) to transform the list of checkboxes in a list of mutual exclusive selection radio buttons.

On the click of the main button the indexes of the selected items are printed before the agent exit (ex. 0 2 3).

Example command:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type checklist -accessory_view_payload "/list First\nSecond\nThird /required"

Checklist example

-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type checklist -accessory_view_payload "/list First\nSecond\nThird /radio"

Checklist example radio buttons
Datepicker (available from v3.0.0)

This accessory view displays a date picker to the end user.

Datepicker has a mandatory -accessory_view_payload parameter as quoted text, which provide the data to be shown.

Payload parameter must contain at least an empty space string (see first example below). It can also contain the following optional control strings:

  • /preselection yyyy/MM/dd hh:mm:ss to pass to the accessory view a preselected date/time;
  • /start_date yyyy/MM/dd hh:mm:ss an optional start date if you need to define a limited date range;
  • /end_date yyyy/MM/dd hh:mm:ss an optional end date if you need to define a limited date range;
  • /title TEXT which will be shown as title for the checklist;
  • /components [ date | time ] to show only one of the two date/time components. If not defined it will show both;
  • /style [ graphical | field | stepper field | compact ] to change the style of the date picker. If not defined will use the system default;

On the click of the main button the selected date/time is printed before the agent exit (ex. 2023-07-11 12:00:00) with the same time zone of the device.

Example commands:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type datepicker -accessory_view_payload " "

Standard datepicker example

-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type datepicker -accessory_view_payload "/title Pick a date /preselection 2022/10/10 23:00:00 /style graphical /components date"

Graphical datepicker exmaple
Slideshow (available from v3.1.0)

This accessory view displays a slideshow of given images.

Slideshow has a mandatory -accessory_view_payload parameter as quoted text, which provide the data to be shown.

Payload parameter must contain at least the list of images paths/URLs with the format /images URL\nURL\nURL or /images path\npath\npath or /images path\npath\nURL to make the slideshow to appear. It can also contain the following optional control strings:

  • /autoplay a flag that will start the image scrolling automatically;
  • /delay INT a custom delay to be applied to the images auto scrolling, in seconds. By default it's set to 3 seconds;

Example commands:
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type slideshow -accessory_view_payload "/images https://cdn.pixabay.com/photo/2015/04/23/22/00/tree-736885_1280.jpg\nhttps://cdn.pixabay.com/photo/2015/04/19/08/32/rose-729509_960_720.jpg\nhttps://cdn.pixabay.com/photo/2015/07/05/10/18/tree-832079_960_720.jpg /autoplay /delay 5"

Standard datepicker example
Clone this wiki locally