article by Frank Nimphius, March 2019
List-of-values, as well a action lists (menus), use buttons for rendering the list's select items. Apart from long lists of values that result in poor usability, some messengers, including Facebook, have a limitation on the number of action items that can be displayed in a list at the same time. The solution to this is pagination, in which bot designers allow users to scroll within a list of values by showing a reduced set of values at a time.
There are two components in Oracle Digital Assistant that you can use to build list-of-values that support pagination
- System.ResolveEntities
- System.CommonResponse component
Both components require the rangeSize for pagination to be defined on the entity itself. The System.ResolveEntities component does not require any configuration than to reference a variable of the entity type from its "variable" property. For the System.CommonResponse component, pagination works with a few settings. Note that the reason that System.CommonResponse requires configuration is that it is a very flexible component that allows bot designers to customize bot responses, which you cannot using the System.ResolveEntities component.
The image below shows a list of values for which the range size is set to 3 (thus you see 3 select items at a time). For as long as there are still items to paginate, a button "Show More" is displayed.
Clicking the "Show More" Button then displays the next set of values. I am sure you ask yourself if there also is a way to have a button that allows users to scroll backwards. And yes, there is. As you will see later when I discuss the BotML code for the System.CommonResponse component, the "Show More" button can be duplicated and then used with the inverse code (setting the range start to a previous starting point).
Selecting a value from the list then e.g. prints the selected value.
Defining Pagination in the Entity
Shown below is a custom entity that lists airports by their city name. The important setting is the Enumeration Range Size field that, in the example, has its value set to 3. Note that the value for the range size can also be set using expressions (e.g. ${system.config,rangeSizeParam} to read the value from a skill bot custom configuration parameter).
Configuring the Common Response Component
To use the entity, you define a dialog flow variable that uses the entity name as its type. In the image below, the variable is airportCodes pointing to the AirportCodes entity. The airportCode variable then also needs to be referenced by the System.CommonResponse component's variable property.
To print the list of values, the System.CommonResponse component stamps action items that it reads from an iteratorVariable. The iteratorVariable in the image below uses an expression to read the list of actions to print in the list-of-values from a system variable that keeps track of the currently rendered entity. Because the System.CommonResponse component references the airportCodes variable from its variable property, the current entity is AirportCodes. So for each airport in a range of 3, starting from the current range start, the componnent adds an action button.
Note: When working with entity based iterators in the System.CommonResponse component, then the list of value is referenced from the enumValues object. However, to read the object's current item, you use an expression of ${enumValue}. The ${enumValue} expression is used twice in the System.CommonResponse configuration. It is used to set the list-of-value item label and also to update the airportCodes variable in the variables section.
The globalActions configuration of the System.CommonResponse component is used to render the Show More button.
The first expression, ${system.entityToResolve.value.needShowMoreButton}, displays the button for as long as there are more values in the entity list. If navigation reaches the last range size, then the button will be hidden.
The configuration …
variables:
${system.entityToResolve.value.rangeStartVar} : ${system.entityToResolve.value.nextRangeStart}
Actually sets the new range start value to the internal system variable that handles the pagination.
Complete Configuration
The complete System.CommonResponse component configuration is shown in the image below. If you think that this is a lot of code to write, then you are correct. However, consider this
- If you don't need to customize the list appearance, then you can use the System.ResolveEntities component
- The dialog flow editor has a + Components selector that you use to select pre-defined component templates from. Use the commonResponse – text option to create the initial list definition.
Download Sample
Oracle Digital Assistant – Skill Sample (19.1.3)
Related Content
TechExchange: How-to Use the System.ResolveEntities Component in Oracle Digital Assistant
TechExchange: Oracle Digital Assistant Primer
TechExchange Quick-Tip: Creating Loops in Oracle Digital Assistant Skill Bots using BotML
