Bixby Developer Center

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

Defining Layout Macros

Layout macros are defined with the macro-def key.

Here is an example of using a macro-def key:

macro-def (space-resort-details) {
  params {
    param (spaceResort) {
      type (SpaceResort)
      min (Required) max (One)
    }
  }
  content {
    section {
      content {
        image-carousel {
          images (spaceResort.images)
        }
        title-area {
          halign (Center)
          slot1 {
            text {
              value ("#{value(spaceResort.name)}")
              style (Title_L)
            }
          }
          slot2 {
            single-line {
              text {
                value ("#{value(spaceResort.planet)} • #{value(spaceResort.gravity)}g")
                style (Title_XS)
              }
            }
          }
        }
        paragraph {
          value ("#{value(spaceResort.description)}")
          style (Detail_M)
        }
        partitioned {
          content {
            for-each (spaceResort.attributes) {
              as (attribute) {
                single-line {
                  text {
                    value ("#{value(attribute)}")
                    style (Detail_L)
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This macro could be used within a larger layout or view file:

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

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 false for the fromQuiz parameter in the example.movieAgent sample capsule:

    param (fromQuiz) {
      type (core.Boolean)
      min (Optional)
      max (One)
      default (false)
    }

View master on GitHub

You can set default values for these types of values:

• Text
• Boolean
• Integer
• Decimal

Invoking Layout Macros

Use the macro key 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-summary 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) {
        where-each (item) {
          macro (space-resort-summary) {
            param (spaceResort) {
              expression(item)
            }
          }
        }
      }
    } else-if (size (result) == 1) {
      layout {
        macro (space-resort-details) { // calling a more generic macro that defines a "section"
          param (spaceResort) {
            expression (result)
          }
        }
      }
    }
  }
}

Here is what the layout would look like, which has the space-resort-details information displayed above:

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 might want to test against the $promptMode.

Why Use Macros

As mentioned previously, layout macros are useful in reusing content that can be placed in multiple places. They can aid in rendering content with complex logic. For example, in the shirt Sample Capsule walkthrough, the confirmation view varies only in the message, depending on if the order was first made or if it was updated. The use of a macro lets you reuse the majority of the layout, but with the differing messages depending on the match-pattern, which calls the appropriate confirmation view.

Macros are useful when handling various languages and locales. If you are creating a capsule that should work in different locales, you can tweak a view but still display the same components by using macros. For example, you might have a compound card that displays various flowers for order. The image card within that compound card might have the same information, no matter what region you are in: a picture of the arrangement being sent, the name of the arrangement, and a price. However, the text in the attribution-link might differ because where you punch users out to might depend on the local florists available in that region.

Additionally, macros are useful if you are developing across multiple devices. For example, when you are displaying a list of results, you might want to use image cards on devices with larger screens, but for a watch, you might want to use a thumbnail card to display content because you want to use smaller images. You can use macros here to repeat the title-area content.