How to dynamize Narratives with Variables
- Sylvain Paillard
What are Narrative Variables and why do I need to use them?
Narratives Variables are used in Narratives for any case where the content of parameters is needed to be dynamic. A Narrative defines a Layout and its content. A Narrative can be fully static (one narrative for one specific page with fixed content) or highly dynamic (the same narrative is used with many different data, for example, if your Narrative is a “brand” page, then while you have one narrative, you will have many different types of content going through the same narrative).
Typically, a narrative is first defined with static content, which means that a static definition of all the parameters of all the Layout Blocks is provided.
For cases where the Narrative is meant to be static (e.g.: a special Landing Page with a Contest), then no dynamic variables are needed and the static configuration can be used in production.
But for all cases where all, or parts, of the Layout Blocks parameters of the Narrative need to be dynamic, then the parameters should be defined with Narrative Variables.
Difference between Dynamic Products and Narrative Variables
If your Narrative includes one (or several) blocks of product suggestions, of course, the content of these product suggestions will be dynamic. However, this doesn’t typically require to define Narrative Variables. The Narrative API returns a dynamic structure in the parameter “bx-hits” and “bx-hit” which returns the dynamic logic defined in a WPO Widget Strategy.
So for typical cases of Product suggestions/listing, there is no need to define any Narrative Variables.
But if there is something else than products that are dynamic in your Narrative, then it is required to define Narrative Variables.
We know, it’s not very easy to understand
Have a look at this Concrete Example and things will get much more clear
Dynamic Variables can be a part of the parameter input
Dynamic Variables appear as tags in the input field:
Here is a dummy example with the Dynamic Variable in the middle of other words.
This enables you to use Dynamic Variables wither as the full value of a Layout Block Parameter (typical case) or as a part of the value, next to other static texts or other Dynamic Variables.
To create a variable, put your text cursor where you want the variable to appear in the text input and click on the “Add Variable” button below, the Dynamic Variable will appear and you can click on it to edit it.
After clicking on “Add Variable” the tag appear and you can click on it to edit.
3 types of Dynamic Variables
There are 3 types of Dynamic Variables, so the first thing you need to do is to identify which type you need for each case:
Mapping Variables
This is the most common type of variable. Mapping variables map the result (or hits) of a widget strategy to Layout Block Parameters (the parameters used by your front-end to render each template). It can be related to the current layout block (current-hit) or other blocks from the layout (response path). It is also possible to access a global variable of the response.
Widget Accessor
If your Narrative needs to use more than one widget (the main widget of the Narrative), it is required to define which widget is needed in the Layout Block parameter “accessor”. This definition is always done with a Widget Accessor.
Script Variables
Template variables are for DEV users as it requires a deeper understanding of the internal data model. However, if you know what pre-existing “Template Variables” to use, then you can simply select it in the list.