article by Frank Nimphius, December 2020
About Page Ranging
Messenger behaves differently when it comes to the number of buttons or the selection of items that can be rendered. To remove limitations, you can configure the data items that are displayed simultaneously on composite bag entity items.
For the users to be able to browse all data values, you then use buttons exposed on the System.CommonResponse component or the System.ResolveEntities component. What happens when a user tabs on a button is that the component navigates to a next or previous page range.
There may be a time where you need to know what the current page range is. In composite bag entities, the page range is identified by the range start index, which, of course, is different for each bag item. In this article I explain how you can access the current page range for a bag item in a composite bag entity at runtime using an Apache FreeMarker expression.
Example
The image below shows a simpler version of a Pizza composite bag entity. It has 3 bag items of which each is a value list entity.
Each bag item has a Enumeration Range Size property that you set to the number of data to display at a time. In the image below the value is set to 4.
You create a System.CommonResponse component or System.ResolveEntities component state from the component templates in an Oracle Digital Assistant skill. The image below shows the template for the System.CommonResponse component.
After you set the component's variable property to the name of a dialog flow variable of the composite bag entity type (Pizza in this example), you can run the skill in the embedded conversation tester. As shown in the image below 4 items are displayed at a time with a Show More button places at the bottom. Once you tab the Show More button a second button is displayed allowing the user to scroll backwards.
The system.entityToResolve show the information that is accessible for a bag item. As you can see, you can access the nextRangeStart value, which is the the starting point for the next range of data items, the needShowPreviousButton, which indicates whether or not to display the "Show Previous" button, the previousRangeStart, which is the negative range size for the first page, The rangeSize set for a bag item, and the needShowMoreButton that indicates whether a Show More button should be rendered.
Though you could compute the current range start from the before mentioned information as nextRangeStart – rangeSize, there is a direct access to the current range start too. Shown highlighted in the image below, the rangeStartVar property on the system.entityToResolve node references the system variable that holds the range start. The name of the variable is different for each bag item (because the system needs to keep track of the current range start for each bag item). So what you need is to know the Apache FreeMarker expression that resolves the value for the current variable.
Accessing The Range Start Value For A Bag Item
As you can see in the image below, the system.entityToResolve.value.rangeStartVar is set with the next range start value when the Show More button is pressed and with the previous range start value when the Show Previous button is pressed. The global actions are automatically generated by the System.CommonResponse component template for composite bag entities.
So now that you know where the range start is saved, you need to get the Apache FreeMarker expression to access it. And here it is:
${(system.entityToResolve.value.rangeStartVar)?eval}
If you want to compare it with another numeric value you can change the expression to
${(system.entityToResolve.value.rangeStartVar)?eval?number}
As you can see, the expression is independent of the bag item that is rendered
Use Case
Now that you have the solution: ${(system.entityToResolve.value.rangeStartVar)?eval?number}, you may wonder what the problem is that this helps to solve.
In the image below you see the UI of a composite bag entity bag item that renders a prompt with a help button. Clicking on a help button displays a list of values. For the list of values, and for when paginating over the list, the prompt to display should be simpler than the original bag item prompt. Because of the complexity in the implementation, I worked with the range start value to help telling when to display which prompt.
The image below shows the initial prompt and the prompt displayed after pressing the "Show Help" button. Notice how the second prompt is simpler and less descriptive.
The image below shows the prompt when paging through the list of values. As you can see, the prompt is the simplified prompt. One of the "flags" I used to ensure that the bag item does not fall back to its original prompt is the range start value.
In summary, the take away from this article is that ${(system.entityToResolve.value.rangeStartVar)?eval?number} allows you to access the current range start value for a bag item without know which bag item gets rendered.
Related Content
TechExchange: Adding pagination to list and card layouts in Oracle Digital Assistant
TechExchange Quick-Tip: Implement Page Ranging for Lists using the Common Response Component
TechExchange: Use Entities To Build Powerful, Robust And Speech-Ready Action Menus
