Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Layout Macros

The same complex user interface patterns often are used in multiple places in your capsule. By turning these patterns into layout macros, you can easily reuse them.

Defining Layout Macros

Layout macros are defined with the layout-macro-def key:

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)
}
}
}
}
}

The params key starts a block that lets you specify parameters for the macro. These parameters are defined similarly to properties in structure concepts:

  • a type that matches either a primitive like Integer or Text, or a previously-defined concept, like SpaceResort
  • min to set optionality to Required or Optional
  • max to set cardinality to One or Many
Note

You cannot have a macro with the same ID if the macro is defined in the same resource bucket. For example, if you have a macro with the ID "this-test-macro" in the bixby-mobile-en-US target, you cannot have another different macro with the same name in that target.

However, if the macro's target is in a higher level resource bucket, the more specific target will override the more general target. For example, say you have a macro in bixby-mobile-en and another macro in bixby-mobile-en-US, both with the ID "this-test-macro". The macro in the bixby-mobile-en-US target will render for the bixby-mobile-en-US target, but the bixby-mobile-en macro will render for the bixby-mobile-en-GB target.

Macros with the same ID but in different targets (for example, bixby-mobile-ko-KR and bixby-mobile-en-US) are allowed and are encouraged when localizing.

Specifying Parameter Default Values

Your macro definition can include a default key in a param block to set a default value for that parameter. This sets a default value of 2 for the numberOfDiners parameter:

param (numberOfDiners) {
type (Integer)
min (Required) max (One)
default (2)
}

You can set default values for these types of values:

  • Text
  • Boolean
  • Integer
  • Decimal

Invoking Layout Macros

Use the layout-macro in the render block of your views to invoke macros. Use param blocks to pass values to the macro's parameters.

This example shows a result view that can be either a list of search results, in which case list-of is used to construct a list of space-resort-summmary layouts for each resort, or a single space-resort-detail layout if only a single result has been returned.

result-view {
match: SpaceResort (result)

render {
if (size(result) > 1) {
list-of (result) {
has-details (true)
where-each (item) {
layout-macro (space-resort-summary) {
param (spaceResort) {
expression(item)
}
}
}
}
} else-if (size(result) == 1) {
layout {
layout-macro (space-resort-details) {
param (spaceResort) {
expression (result)
}
}
}
}
}
}
Note

Macros from capsules that you import but do not alias must include the full namespace:

layout-macro (example.SpaceResort.space-resort-summary)

Target Model Parameters

min and max are required attributes for target-defined parameter types.

  • min: Optional or Required
  • max: One or Many

When adding parameters, you should start with less restrictive constraints such as Optional and Many so that your macro is usable in more places.

Ensure that you test if the parameter is populated when using it inside your macro template.

if (exists(targetParameter) {
// ...
}

Layout Modes

Conditional blocks can test which, if any, layout mode is being used by using the special variable $layoutMode.

if ($layoutMode == 'Details') {
// ...
}

The conditions require one of these enums for testing:

  • Summary
  • Details
  • Confirmation
  • Input

Prompt mode can change between views, so if your macro is used across multiple layout modes, you may want to test against the $promptMode.