Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Expression Language Reference

Bixby's Expression Language (EL) is based on UEL, and is used in conditionals and strings in the *.bxb format.

Strings can include EL functions via the #{%expression%} (or ${%expression%}) notation.

Concept values can be bound to an EL expression by wrapping the expression in the $expr() construct, optionally prefixing it with a type to coerce the value to.

// untyped expression
value: $expr(brand)

// typed expression
value: Distance$expr(calculateDistance($user.currentLocation, point, 'Miles'))

Optional parameters to EL functions are denoted in [brackets].

Layout Functions

These functions can only be used in layout files.

  • layout(name): Embed the specified layout (e.g., "address") at that point in the current layout.

  • layoutMode(name, type): Embed a layout like layout(), but override the layout type (e.g. "Summary", "Details", etc.).

  • followups(expression): Insert buttons for the followups that apply to a given expression result.

Geospatial Functions

These functions provide support for location-based GIS functions. Most of them rely on concepts in the viv.geo Core Capsule.

  • calculateDistance(point1, point2, units): Calculate the distance between two geopoints.

    In this example, calculateDistance() is used in a selection strategy to find points of interest within certain distance ranges:

      selection-strategy {
    id (point_of_interest)
    match {
    PointOfInterest (this)
    }
    named-advice ("within-100-miles") {
    advice ("${calculateDistance($user.currentLocation, this.centroid, 'Miles').magnitude}")
    advise-for { lowerBoundClosed(0) upperBound(100.0) }
    }
    named-advice ("within-1000-miles") {
    advice ("${calculateDistance($user.currentLocation, this.centroid, 'Miles').magnitude}")
    advise-for { lowerBoundClosed(0) upperBound(1000.0) }
    }
    }
  • within(point, shape): Return true if a geopoint is within a certain geospatial region, false if not.

Date/Time Functions

These functions operate on DateTime values. They utilize concepts that must be imported from the viv.time Core Capsule.

  • isFuture(datetime): Return true if the datetime occurs in the future, false if not.

  • isPast(datetime): Return true if a datetime occurs in the past, false if not.

  • isLastDayOfMonth(datetime): Return true if the day of the datetime is the last day of the month. If it is not, or if any of the month, day, or year fields are not set, return false.

  • durationBetween(datetime1, datetime2): Return the duration between two datetimes, as a time.DurationPeriod. Duration is returned in absolute time, regardless of which date is before the other.

  • durationInUnit(datetime1, datetime2, unit): Return the number of specified date/time units present between two datetime nodes. The unit can be any valid chronounit enum.

      durationInUnit(this.departureDateTime.date, now().date, 'DAYS')
    

    Note that chronunit enums must be all caps, e.g., 'DAYS', 'HOURS', 'SECONDS'.

  • addDuration(datetime, period) and subtractDuration(datetime, period): Add or subtract time duration. Takes a date/date-time and a duration, either as an ISO 8601 duration format or a viv.core.Period

      // add two days to the given date using ISO 8601 duration format:
    addDuration(dateTime, 'P2D')

    // subtract an instance of viv.core.Period from a given datetime:
    subtractDuration(dateTime, myPeriodType)
  • now([timezone]): Return the current DateTime (viv.time.DateTime). Uses the default user timezone, unless one is provided. Use now().date to return the date only.

Formatting Functions

These functions are intended to be used in template strings to aid in formatting output. This can be especially useful in dialog.

  • concept(node[, form]): Format the supplied node as a concept fragment. You can optionally pass an argument for the form (Definite, Indefinite, Proximal).

  • action(node): Format the supplied node as an action fragment.

  • input(node): Format the supplied node as an input fragment.

  • value(node): Format the supplied node as a value fragment.

  • event(node, dialogNode): Format the supplied node as a specific dialog event mode. In addition to providing the node to render, you also must provide the event mode to render the node as.

  • macro(macro-id[, param1, param2, param3, ...]): Invoke a dialog macro with the specified parameters. For example, suppose this macro has been defined with template-macro-def:

      template-macro-def (Bookmarks) {
    params {
    param (number) {
    type (example.book.Bookmarks)
    max (One) min (Required)
    }
    }
    content: template ("#{value(number)} bookmarks")
    }

    You can invoke that macro in EL with the macro command. This lets you include templates within other templates:

      template ("You have #{macro('Bookmarks', 23)}.")

    The macro ID is specified as a string in the first parameter. Parameters must be specified in the order they are specified in the macro definition; parameters can be omitted at the end if they are Optional or have a default value.

  • list(node, format): Format the individual values of the specified node in the specified format, then join those values as a conjunctive list. The format argument must be one of the fragment template functions: concept, action, value, or event. (Note: this is distinct from the list schema key.)

      if (exists(alarms.repeatDays) && size(alarms.repeatDays) < 7) {
    dialog-template ("#{list(alarms.repeatDays.day, 'value')}")
    } else {
    dialog-template ("")
    }
  • listWithLimit(node, format, limit): Format up to limit individual values of the specified node in the specified format, then join those values as a conjunctive list. The format argument must be one of the fragment template functions. If limit is exceeded, include the number of omitted values in the formatted list, for example, "John, Cindy, and 3 others".

  • joinAs(format, node1[, node2, node3, ...]): Render the individually specified nodes in the specified format, then join those formatted strings as a conjunctive list. The format argument must be one of the fragment template functions. (The list and listWithLimit functions operate on values of a single node; joinAs operates on multiple nodes that contain single values.)

    Note

    If you use joinAs in dialog, the word "and" is added by default. If you don't want the "and" to appear, then you can list the arguments one by one instead. For example, you can change #{joinAs('input', action.city, action.keyword)} to become [#{input(action.city)][ #{input(action.keyword)}].

  • raw(node): Render the single, primitive data value in the specified node as a string, if one exists.

  • integer(value): Format the specified value as an integer in the locale of the current rendering context. A value of 1000.1 would be rendered as "1,000" in the en-US locale.

  • percent(value): Format the specified value as an percentage in the locale of the current rendering context. A value of 1.1 would be rendered as "110%" in the en-US locale.

  • scientific(value): Format the specified value as an scientific number in the locale of the current rendering context. A value of 1000.1 would be rendered as "1.0001E3" in the en-US locale.

  • ordinal(value): Format the specified value as an ordinal number in the locale of the current rendering context. A value of 2 would be rendered as "2nd" in the en-US locale.

  • spell(value): Format the specified value as words in the locale of the current rendering context. A value of 32 would be rendered as "thirty-two" in the en-US locale.

  • number(value[, formatString]): Format the specified value as a number either in the locale of the current rendering context or using the optionally supplied DecimalFormat string. Example: number(airfare.total.price, '#,##0')

  • dateTime(node[, formatString]): Format the specified node as a date/time number either using the default format of the locale of the current rendering context or using the optionally supplied Joda DateTimeFormatter string. Example: dateTime(log.timeStampInfo, "h:mm a")

  • lower(string): Lowercase all characters in the supplied string.

  • upper(string): Uppercase all characters in the supplied string.

  • title(string): Convert the first character of the supplied string to title case.

  • truncate(string, length): Truncate the supplied string to the desired maximum length.

  • jsonEscape(string): Return a JSON stringified input.

Collections Functions

These functions work on a collection of items where EL functions are supported.

  • contains(node, value): Return true if the specified node contains the specified value, false if it does not.

  • subtract(node1, node2): Remove elements in node1 that are found in node2, then return the resulting subset of node1.

  • intersect(node1, node2): Remove elements in node1 that are not found in node2, then return the resulting subset of node1 (the intersection of the two nodes).

User and Device Information Functions

These functions return information about the user or their device.

  • getLocale(locale): Get locale-related information for a given locale identifier. Returns a node with the following properties:
    • country: ISO 3166-1 alpha-2 country code (for example: "US", "KR")
    • iso3Country: ISO 3166-1 alpha-3 country code (for example: "USA", "KOR")
    • language: ISO 639-1 language code (for example: "en", "ko")
    • iso3Language: ISO 639-2 language code (for example: "eng", "kor")
    • currencyCode: ISO 4217 currency code (for example: "USD", "KRW")
    • currencySymbol: currency symbol (for example: "$", "₩")
    • measurementSystem: one of USC, Imperial, or Metric

In this example, getLocale is used to determine the user's measurement system. The calculateDistance geospatial function is also used.

action (GetCurrentDistance) {
type (Fetch)

collect {
input (point) {
type (GeoPoint)
min (Required)
plan-behavior (Always)
}
}

output (Distance) {
evaluate {
if (getLocale($user.locale).measurementSystem == 'USC') {
Distance$expr(calculateDistance($user.currentLocation, point, 'Miles'))
} else {
Distance$expr(calculateDistance($user.currentLocation, point, 'Kilometers'))
}
}
}
}
  • permissionGranted(permission): Return true if the passed permission has been granted for the capsule. The available permission values are listed in the capsule.permissions reference key.
output (Something) {
evaluate {
if("#{permissionGranted('user-profile-access')}") {
...
} else {
...
}
}
}

For more information, see the Granting Capsule Permissions section of Preparing Your Capsule in the developer's guide.

Matching Functions

  • "test:values(node1, node2)": Return true if the data values of each node are equal, false if they are different values or different types.

  • "test:data(node1, node2)": Return true if the data values of each node are equal, ignoring their type.

  • min(node[, property]): Return the minimum value of the given node (using an optional property for comparison, if provided).

  • max(node[, property]): Return the maximum value of the given node (using an optional property for comparison, if provided).

  • compare(node1, node2): Compare two specified nodes, using default natural ordering. Returns a negative integer when node1 is less than node2, a positive integer when node1 is greater than node2, or zero if node1 and node2 are equal. (For purposes of comparison, non-null is greater than null.)

  • regexAllMatch(node, regex): Return true if (and only if) all values in the node match the specified regular expression, false if any values do not match.

  • regexAnyMatch(node, regex): Return true if any values in the node match the specified regular expression, false if no values match.

  • similarity(string1, string2): Return the 3-gram edit distance between two strings.

    This strategy uses similarity to help find localities the user is searching for:

      selection-strategy {
    id (locality-name-similarity)
    match {
    NamedPoint {
    from-output: ConstructNamedPointFromRegion {
    from-input: Locality (locality) {
    from-output: FindLocality {
    from-input: LocalityName (find)
    }
    }
    }
    }
    }
    named-advice ("rank") {
    advice ("${ similarity(locality.name, find) }")
    advise-against { lowerBoundClosed (0.0) upperBoundClosed (0.5) }
    advise-for { lowerBoundOpen (0.5) upperBoundClosed (1.0) }
    }
    }
  • editDistance(string1, string2): Return the Levenshtein distance between two strings.

Node Evaluation Functions

  • test:instanceof(node, type): Return true if the value(s) of the specified node are instances of the specified type, false if they are not.

      if (test:instanceOf(region, 'viv.geo.LevelOneDivision')) {
    // region is an instance of viv.geo.LevelOneDivision
    }
  • test:assignableFrom(type1, type2): Return true if type1 is a valid type identifier and can be assigned from type2, false otherwise.

  • typedValue: Return an unattached node from a value.

      typedValue('contact.EmailType', ’home’)
  • size(node): Return the number of values contained in a node or collection of items.

  • exists(node): Return true if the node has a value, false if it does not.

  • relaxed(node): Return true if one or more of the node's constraints have been relaxed, false if they have not.

  • groupRelaxed(node): Return true if the node or any of its upstream input nodes have had any of their constraints relaxed, false if none have been.

  • plural(node): Returns the plural form of this node. If the locale you are working with does not use plural forms, returns other.

  • state(node): Returns the evaluation state of this node, one of Pre (the node has not yet been evaluated), Mid (the node is currently being evaluated), or Post (the node has already been evaluated).

Special EL Variables

There are several variables available in EL that can be used to access contextual information about the user and device.

  • $handsFree: set to true if the device operates in "hands-free" mode.

  • $screenLocked: set to true if the device's screen is currently locked.

  • $sortOrder: set to one of ascending, descending, or unspecified.

  • $sortType: set to one of natural, compound, binding, explicit, or undefined.

  • $user: contains several properties with more information about the user:

    • $user.nickName: the user's nickname as a string, if set.
    • $user.currrentLocation: the user's current location, as a geopoint.
    • $user.timeZoneId: the user's current timezone. (This may be null if the timezone is not set.)
    • $user.locale: contains the structure returned by getLocale() for the user's current locale (for example, $user.locale.country). See Locale Functions for the complete list.
    • $user.is24HourFormat: boolean indicating whether the device is set to display time in 24-hour format (true) or AM/PM format (false).
    • $user.networkCountry: the country of the current network, denoted in ISO 3166-1 alpha-2. Example: US or UK.