Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Creating Bixby Views

Bixby lets you construct views to build your capsule's user interface. Bixby Views uses the same key-value modeling language that Bixby's models are defined in. By using them, you can create interactive designs for Bixby in a simple, consistent manner.

There are three view types:

  • Input Views contain buttons, fields, and other input elements that allow users to give Bixby information.
  • Confirmation Views are shown when Bixby is about to execute an action that requires user approval/review before proceeding.
  • Result Views define the layout used for results returned from Bixby.

View definitions start with high-level keys. In input views, these can be direct input fields such as date pickers; in other views, these are layouts, which are wrappers for components. These components include containers for text and images, titles, sections, and even maps and image carousels. Not all components are valid in all views, and some views like date pickers do not wrap other components.

A layout can be fully defined within a result-view or confirmation-view, or contained in a separate file specified via layout-match or layout-macro. This lets you reuse layouts or sections of layouts in different views.

Input Views

Input views let your capsule gather information from the user. Examples include components that allow users to easily pick time, date, images, and find information with the aid of auto-complete. You can also use components to create forms with text and numbers.

Here is an example of an input component that allows the user to make a single selection from a list:

Screenshot of Single Select Picker

The input-view includes a required match block that defines the data this view is for: in this case, picking the checkout date. The render block renders the view, using a calendar component.

The keys that can go in the render block of an input-view include pickers, auto-complete (search fields), and forms:

  • date-picker: lets users select a date
  • time-picker: lets users select a time
  • calendar: lets users select a date or date range from a calendar
  • image-picker: lets users select one or more images
  • selection-of: lets users choose one or more items from a given list
  • auto-complete: presents a search field with completion suggestions from a given list
  • form: generates a view with editable fields for users to input information

Confirmation Views

Confirmation views let you build user interfaces for reviewing and confirming actions. As with result views, confirmation views can use layouts and layout-macros. In addition, confirmation views can use transaction properties in their layouts.

Here is the confirmation view for the space resort capsule, which confirms the order:

confirmation-view {
match: common.Confirmation {
confirming {
CommitOrder(action)
}
}
mode (PositiveEmphasis)
message {
template ("Book the room?")
}

render {
layout-macro (order-details) {
param (order) {
expression(action.order)
}
}
}
conversation-drivers {
conversation-driver {
template ("Pay")
}
}
}

The render block of a confirmation-view can only include layouts:

  • A layout can be directly included in the render block with layout
  • A layout can be defined in an external file with layout-match or layout-macro can be defined in an external layout.bxb file

Result Views

Result views let you build displays for search results, individual details page, image carousels, and more. Additionally, you can render a layout from your *-view file and use several components via layout-macros.

If you need the user to be taken to an outside application, Bixby can directly launch that application with the result-view.

Here is an example of a result-view from the space resort capsule. This shows just one resort, and uses layout-macro to include both an image carousel and a detail view:

result-view {
match: SpaceResort (result) {
min (Required) max (One)
}

render {
layout {
layout-macro (space-resort-image-carousel) {
param (spaceResort) {
expression (result)
}
}
layout-macro (space-resort-details) {
param (spaceResort) {
expression (result)
}
}
}
}
conversation-drivers {
conversation-driver {
template ("Make Reservation")
}
}
}

This is the SpaceResortDetails.layout.bxb file, showing the layout macro definition that defines the space resort details. The parameter spaceResort is passed from the result view file above.

layout-macro-def (space-resort-details) {
params {
param (spaceResort) {
type (SpaceResort)
min (Required) max (One)
}
}
content {
section {
title {
template ("#{value(spaceResort.name)}")
}
content {
single-line {
text {
value ("#{value(spaceResort.planet)} • #{value(spaceResort.gravity)}g")
style (Detail_M)
}
}
paragraph {
value ("#{value(spaceResort.description)}")
style (Detail_M)
}
}
}
}
}

Notice that a layout macro is defined with layout-macro-def.

A result-view can have the following elements in its render block:

The contents of the layout macro file above could have been included in the view file directly. (Note that we refer to result, not spaceResort, as the value of SpaceResort is bound to result by thematch` block.)

result-view {
match: SpaceResort (result) {
min (Required) max (One)
}

render {
layout {
layout-macro (space-resort-image-carousel) {
param (spaceResort) {
expression (result)
}
}
content {
section {
title {
template ("#{value(result.name)}")
}
content {
// continues . . .
}
}
}
}
}
}

Here is another example of components in a result view. This uses the list-of component to display a list of results:

result-view {
match: SpaceResort (result) {
min (Required) max (Many)
}

render {
list-of (result) {
where-each (item) {
layout-macro (space-resort-summary) {
param (spaceResort) {
expression(item)
}
}
}
highlights {
select(pick) {
label("#{raw(pick.highlight)}")
layout-macro (space-resort-highlight) {
param (spaceResort) {
expression(pick)
}
}
filter-by (exists(pick.highlight))
}
select(pick) {
label("#{raw(pick.highlight)}")
layout-macro (space-resort-highlight) {
param (spaceResort) {
expression(pick)
}
}
filter-by (exists(pick.highlight))
}
select(pick) {
label("#{raw(pick.highlight)}")
layout-macro (space-resort-highlight) {
param (spaceResort) {
expression(pick)
}
}
filter-by (exists(pick.highlight))
}
}
}
}
}

That result view uses a layout macro, space-resort-highlight, to present an image-card for each resort in the list. Here's the macro definition file:

layout-macro-def (space-resort-highlight) {
params {
param (spaceResort) {
type (SpaceResort)
min (Required) max (One)
}
}
content {
image-card {
size (M)
image-url {
template ("#{value(spaceResort.imageUrls[0])}")
}
title-area {
hAlign (Start)
slot1 {
text {
value ("#{value(spaceResort.name)}")
style (Title_L)
}
}
}
}
}
}

View Components

Layouts are built from smaller components: cards, cells, and various text objects such as titles and paragraphs. There are examples of those in use above.

Components are placed within a content block under layout. A content block consists of one or more section blocks.

Each section block can itself have just two child keys:

  • title: The title that will be displayed for the section. Unlike titles within other components, this title cannot be styled (although it can be a template). This is optional, and only one is allowed for a content block.
  • content: The actual components within this section.

A layout block has only one content block as a direct child; that content block can have multiple section blocks that each have one content block. So a layout with multiple sections would look like this:

layout {
// the match directive for the overall layout
match: Object (variable)

content {
section {
content {
// content for first section
}
}
section {
content {
// content for second section
}
}
}
}

The content block within a section contains one or more view components, which are divided into the following types:

Areas

  • title-area: a container for titles and subtitles. A title-area has three slots that can contain either a text or a single-line component.
  • cell-area: An area that contains a cell, which displays information for a single subject. This has three child keys for slots (slot1, slot2, and slot3); see the discussion of slots below.

Text

  • paragraph: a paragraph of styled text.
  • single-line: a single line of text that can contain styled text, spacers, and images. A single-line block may have one or more text, image, and spacer keys within it; when it is rendered, they are concatenated into a single display line.
  • text is an interior container for styled text (see below) that can only appear inside other elements such as single-line.

The paragraph and single-line blocks seem similar, but they have different use cases. A paragraph is a single unit of styled text that can be one or more lines, with wrapping left up to the display device. A single-line always displays as a single line of text, but can include spacers and inline images, letting you build a more complicated line of data. Note that if a single-line component generates more text that can be displayed on the device's screen in one line, it will be truncated with an ellipsis ("…").

Styled text blocks such as paragraph and text have two keys:

Cards

A card is a representation of a single subject or result: for example, a hotel room being booked, or a calendar event. Cards should always have title text, and usually have detail text (for example, a description of the hotel room). In addition, they might have image backgrounds, solid color backgrounds, image thumbnails, and even maps with pins. Cards all can have title-area components, and in addition, all cards can have on-click blocks that let you provide an intent to be executed when the card's label is clicked or tapped.

  • title-card: a container that in turn contains a title-area.
  • cell-card: This cell/card hybrid is styled like a cell, and has the same three child keys for slots (slot1, slot2, and slot3) that cell-area does. But, like other cards, it has an on-click block.
  • image-card: similar to title-card, but with an image-url to let you specify a background image for the card.
  • thumbnail-card: treats the image as a thumbnail that can be given a position on the card rather than as a background image.
  • map-card: a component that holds a static map in your view. Map card include a title-area and an on-click action, and also let you set markers (map pins).
  • compound-card: a flexible component that includes a content block (which can contain most of the non-transactional view components) and a chin with two slots at the bottom of the compound-card. (Also, see transaction properties, which are variants of cells that allow input for use with transactional workflows.)

Images

These components allow the presentation of multiple images in carousel or list form. (Individual images can be displayed with image-card.)

  • image-carousel: a component for multiple images, specified as a type or subtype of Image, that can be swiped through horizontally by the user.
  • image-list: a single-line list of multiple images, specified as a type or subtype of Image. If there are more images than can fit on the screen, the user can scroll the list.

Lists and Partitions

The partioned component lets you present multiple rows or lines of data with visual separation between them. It can be used to present lists, tables, and grids.

  • partitioned: used for visually separated data. It contains an unstyled title and a content block. The content block can contain most of the non-transactional view components (e.g., cards, cells, titles, and text).
  • hbox: a "horizontal box" container. An hbox contains a content child, which in turn can only contain one or more vbox components.
  • vbox: a "vertical box" container. This contains controls for horizontal and vertical alignment and a content block which can contain single-line, text, or layout-macro blocks.

A vbox container must be inside an hbox. You can think of an hbox as a row and vbox as an item in a column. The width of each column is determined by its content; Bixby will try to display the full content of each column. If there is not enough horizontal space to do so, left-aligned columns will be truncated with ellipsis marks (…); if there is still insufficient space, centered and right-aligned columns will be cut off (without the ellipsis to indicate truncation).

Note that hbox blocks do not have to be inside a partitioned block, and partitioned blocks do not have to contain hbox blocks.

Transaction Properties

Transaction properties are used within transactional workflows. They allow users to confirm actions and prompt for selections. For instance, a reservation confirmation for a restaurant might allow the user to change the party size and the reservation time.

  • input-cell: a cell wrapped in an intent, to allow a selection prompt or an input form to be presented in a confirmation-view.
  • split-input-cell: a container for two input-cell blocks. A split-input-cell has two child blocks, left and right, which each contain one and only one input-cell.

Cell Slots

The cell-area and cell-card components have columnar slots for their content, numbered slot, slot2, and slot3:

  • slot1 appears as a square on the left side of a cell, and can only contain an image;
  • slot2 contains a content block that has primary and secondary text lines (this is not the same as a layout content block);
  • slot3 appears as a square on the right side of a cell, and can contain an image and a label.

When you lay out a cell, you can choose to have one, two, or all three slots filled, but slot2 must always be filled. So there are four possible display options:

Cells with Slots

Where to Add Views

You should place view files, including layouts and layout macros, in your capsule's /resources/base/ folder. While the capsule can find them anywhere, a good practice is to put them in a layouts/ subfolder, and optionally use subfolders within layouts/ if you want further organization. The space resorts capsule uses this structure:

resources/
  base/
    layouts/
      DateInterval/
        Input.view.bxb (the calendar input picker)
      HabitatPod/
        Input.view.bxb (an input view for choosing rooms within the space resorts)
        Summary.layout.bxb (a layout macro used in HabitatPod's input view)
      Order/
        Confirmation.view.bxb (the order confirmation view)
        order-details.bxb (a layout view used in Order's confirmation view)

(There are more files and folders in the space resort capsule's layout folder, but this gives you an idea.)

Styling Components

Bixby Views offers limited styling of components that remain consistent with the rest of Bixby's design. All text blocks and titles can be given styles that control their size and, in some cases, a choice between normal and "soft" color. (The rendering of "Soft" styles is device-dependent, but generally has less opacity, giving it a dimmer or lighter look depending on its background.)

When styles affect size, they are listed from smallest to largest.

Title Styles

  • Title_XS
  • Title_S
  • Title_M
  • Title_L
  • Title_XL
  • Title_XL_Soft
  • Title_XXL
  • Title_XXL_Soft

Labels

  • Label_M
  • Label_M_Soft
  • Label_L
  • Label_L_Soft

Detail (Body Text) Styles

  • Detail_M
  • Detail_M_Soft
  • Detail_L
  • Detail_L_Soft

Image Sizes

Image sizes can be set to any of the style names for Title, Label, and Detail. The image has the same height as the font size of the specified style. (You should match image styles to the styles of their accompanying text, although the _Soft suffix will not affect the image's display.)

Thumbnail Image Shapes

  • Circle
  • Square

Card Sizes

Cards are always the full width of the content window; the size affects the height.

  • S (2:1 ratio)
  • M (3:2 ratio)
  • L (4:3 ratio)
  • XL (1:1 ratio)

Dividers

You can add a divider between content child components in compound cards and in section contents.