-
Notifications
You must be signed in to change notification settings - Fork 51
Pop up UI Accessory Views
Whitebox
![White box example](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_whitebox.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_whitebox_markdown.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_timer.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_image.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_video.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_input.png)
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"
Secured input
![Secured input example](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_secured_input.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_progressbar.png)
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 /percent automatic
to let the progress bar advance following the onboarding flow.
![Progress bar example](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/popup_progressbar_done.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/drop_down_1.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/drop_down_2.png)
HTML (available from v2.3.0)
![Parsed HTML example](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/html.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/html_whitebox.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/checklist_1.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/checklist_2.png)
-type popup -title "Test title" -subtitle "Test subtitle" -accessory_view_type checklist -accessory_view_payload "/list First\nSecond\nThird /radio"
![Checklist example radio buttons](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/checklist_3.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/datepicker_1.png)
-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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/datepicker_2.png)
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](https://github.com/IBM/mac-ibm-notifications/raw/main/Images/Popup/slideshow_1.png)
-
Deprecated documentation