Unity Scopes API
|
The following widget types are recognized by Unity:
audio
video
image
gallery
header
actions
icon-actions
progress
text
rating-input
rating-edit
reviews
comment-input
comment
expandable
table
The audio widget displays a list of tracks with play/pause controls.
List of attributes:
tracks
A composite attribute containing an array of tuples, where each tuple has up to four fields: title
(mandatory string), subtitle
(optional string), source
(mandatory URI), and length
(optional integer specifying the track length in seconds)You can construct composite attributes with unity::scopes::VariantBuilder:
The video widget displays a still from a video and allows playing the video.
List of attributes:
source
A URI pointing to the video screenshot
A URI pointing to a screenshot of the video (optional) share-data
An optional dictionary for making this video shareable with Content Hub. See content sharing below.The image widget displays a single image.
List of attributes:
source
A URI pointing to the image zoomable
A boolean specifying whether the image is zoomable (default: false
) fallback
A fallback image to be used if the image URI is empty or cannot be retrieved (default: none) share-data
An optional dictionary for making this image shareable with Content Hub. See content sharing below.The gallery widget displays a set of images.
List of attributes:
sources
An array of image URIs fallback
A fallback image to be used if an image URI is empty or cannot be retrieved (default: none)The header widget displays basic infomation about the result.
List of attributes:
title
A string specifying the title subtitle
A string specifying the subtitle mascot
A URI specifying the mascot fallback
A fallback image to be used if the mascot URI is empty or cannot be retrieved (default: none) emblem
A URI specifying the emblemThe actions widget displays one or more buttons.
List of attributes:
actions
A composite attribute containing an array of tuples, where each tuple has at least these fields: id
(a mandatory string that is passed to unity::scopes::ScopeBase::activate_preview_action()), label
(mandatory string), and icon
(optional URI).You can construct composite attributes with unity::scopes::VariantBuilder:
The icon-actions widget displays one or more buttons represented by icons and/or labels. It's similar to actions widget, but uses different layout. Every button can provide an optional temporary icon to be displayed immediately after user taps it.
List of attributes:
actions
A composite attribute containing an array of tuples, where each tuple has at least these fields: id
(a mandatory string that is passed to unity::scopes::ScopeBase::activate_preview_action()), label
(optional string), icon
(optional URI, required if label is missing), temporaryIcon
(optional URI).The progress widget displays the progress of an action, such as download progress.
On completion, the scope receives a preview action activation with the id "finished"
or "failed"
, depending on the outcome of the operation.
List of attributes:
source
A tuple with keys understood by a progress providerA text widget can be used for text of any length (without formatting).
List of attributes:
title
Optional string text
A string containing the textThe rating-input widget allows users to rate content. It consists of two types of widget: a star-based rating and an input field for the user to enter his/her review. It is possible to hide each widget as well as to require them to be filled in.
When a user presses the "Send" button, the scope receives a preview action activation with the id "rated"
. The actual rating and/or review can be accessed via unity::scopes::ActionMetadata::scope_data. The scope data will be a VariantMap with the following keys:
"rating"
- a double holding the number of stars the user selected (1 to 5)"review"
- a string holding the free text reviewList of attributes:
rating-label
String for the star-based rating (default: "Rate this") review-label
String for the review input (default: "Add a review") submit-label
String for the confirmation button (default: "Send") rating-icon-empty
URI for an empty rating icon rating-icon-full
URI for a full rating icon visible
String specifying which of the two widgets are visible ("rating"
, "review"
or default:"both"
) required
String specifying which of the two widgets are required to be filled in ("rating"
, "review"
or default:"both"
)The rating-edit widget allows users to edit an existing review and rating. When used in a preview, the widget displays an existing review and a small "pen" icon; user can update the review and/or rating after tapping the "pen" icon.
This widget supports all the attributes of rating-input widget, plus three extra attributes ("review"
, "rating"
, "author"
) to pre-fill the widget with data of an existing review.
List of attributes:
rating-label
String for the star-based rating (default: "Rate this") review-label
String for the review input (default: "Add a review") submit-label
String for the confirmation button (default: "Send") rating-icon-empty
URI for an empty rating icon rating-icon-full
URI for a full rating icon visible
String specifying which of the two widgets are visible ("rating"
, "review"
or default:"both"
) required
String specifying which of the two widgets are required to be filled in ("rating"
, "review"
or default:"both"
) author
String for the name of the reviewer (optional) review
String for the text of existing review (optional) rating
Number for the rating value (optional)Note: The rating-edit widget may not be supported by older versions of unity8 shell.
The reviews widget is used to display previously-rated content.
List of attributes:
rating-icon-empty
URI for an empty rating icon rating-icon-half
URI for an half-full rating icon rating-icon-full
URI for a full rating icon reviews
A composite attribute containing an array of tuples, where each tuple has up to three fields: rating
(optional integer specifying the number of stars), author
(mandatory string) and review
(optional string).You can construct composite attributes with unity::scopes::VariantBuilder:
The comment-input widget allows users to add comments. It displays an input box along with "Send" button.
When a user presses the "Send" button, the scope receives a preview action activation with the id "commented"
. The actual comment can be accessed via unity::scopes::ActionMetadata::scope_data. The scope data will be a VariantMap with the "comment"
field holding the text entered by the user.
List of attributes:
submit-label
String for the label of the submit button (optional, uses "Submit" by default).The comment widget shows an avatar, author name, subtitle and a comment text.
List of attributes:
source
URI for an avatar icon (optional) author
A string specifying the author of the comment (mandatory) subtitle
A string for the subtitle (optional) comment
A string for the comment text (mandatory)The expandable widget is used to group several widgets into an expandable pane. The expandable widget can be collapsed or uncollapsed. When it's uncollapsed then all the contained widgets are shown. When collapsed, only the first few widgets determined by collapsed-widgets attribute are shown.
List of attributes:
title
A string specifying the title collapsed-widgets
A number of widgets to show when the expandable widget is collapsed (optional).The table widget is used to show a table with labels and values. When used inside an Expandable widget, the topmost 3 rows are shown until it's expanded.
List of attributes:
title
A string specifying the title to be shown on top values
An array with one element per row. Each element is an array of two strings: label and valueSome widgets support content sharing with the special share-data attribute. When the widget is tapped (clicked), data (image, video etc.) can be shared with Content Hub.
The share-data attribute is a dictionary (VariantMap) that needs to contain the following keys:
uri
A single URI to share or an array of URIs. content-type
A name of the content type known to Content Hub, e.g. "links", "pictures", "videos". Please refer to Content Hub documentation for information on supported content types.Here is an example of a shareable image: