Bixby Developer Center

This capsule demonstrates how to effectively use a combination of template macro keys to create a variety of dialog responses to affirm an action from a user. Adding multiple dialog affirmations makes Bixby more user-friendly and natural sounding.

Download Capsule

Testing This Capsule

You can test this sample capsule with the following utterance:

"Turn on smile"

The Simulator returns a smile using a simple result view that consists of a single-line of text, as well as one of several dialog options, like the following:

How the Template Macros Work

This sample capsule demonstrates a much more layered approach of using template macro definitions. Within the resources/en-US/template-macro-defs.macro.bxb file, you can see four separate macro-def keys defined. Some of these keys rely on Expression Language formatting functions or other macro-def keys defined within this file.

Here is how the template macros parses:

1. The SMILE_RESULT template macro is called directly in the result view by the message key:

  message {
    macro (SMILE_RESULT)
  }

View 2aae7d7 on GitHub

2. The SMILE_RESULT uses the macro() EL formatting function, calling on the AFFIRM template macro with the SMILE_ON template macro as the AFFIRM macro's parameter:

macro-def (SMILE_RESULT) {
  content: template ("#{macro('AFFIRM', macro('SMILE_ON'))}")
}

View f61843b on GitHub

// Core text response to turning on the smile, in lower case
macro-def (SMILE_ON) {
  content: template ("smile is on")
}

View f61843b on GitHub

3. The AFFIRM template macro returns either a combination of an affirmation and smile is on or simply Smile is on. It uses the choose(Random) control flow function to randomize which dialog is returned. Both options have a 50% chance of being returned.

// Pick a random affirmation (or none) and prepend it to the core text content with the appropriate capitalization and punctuation
macro-def (AFFIRM) {
  params {
    param (lowerCaseText) {
      type (viv.core.Text)
    }
  }
  content {
    choose (Random) {
      template ("#{title(lowerCaseText)}!") // 50% capitalized sentence without affirmation
      template ("#{macro('AFFIRMATION')}, #{lowerCaseText}!") // 50% capitalized affirmation followed by a comma and the lower case text.
    }
  }
}

// Pick a random affirmation from a bag of words
macro-def (AFFIRMATION) {
  content {
    choose (Random) {
      template (Okay)
      template (Alright)
    }
  }
}

View f61843b on GitHub

• If it chooses just the SMILE_ON text, it uses the title() EL formatting function to capitalize the first letter.
• If it chooses to use an affirmation, the AFFIRMATION template macro is called, then a comma is printed, then the passed lowerCaseText parameter text, which is the smile is on.

4. The AFFIRMATION template macro again uses the choose(Random)control flow key to randomly choose one of the options listed. Several of the options are repeated to increase the chance of that response being chosen. For example, there are six copies of template (Okay), giving it a 30% chance of being picked out of the twenty affirmation template choices.

Notice that the AFFIRMATION template macro doesn't need to use an additional template macro to format the final dialog because all the templates are already formatted with the first letter capitalized and the original text is lower-case. For example, "Okay, smile is on".