How to declare your Narrative Layout Blocks
- Sylvain Paillard
Introduction
Before you can start configuring your Narratives, you need first to declare all your Layout Blocks.
The Layout Blocks are the building blocks of your Narrative (the narrative defines what should be the layout of a page based on these building blocks and what should be the parameter values for each of the selected Layout blocks).
For example, if you want to create a Narrative with this layout, you will need to define 4 Layout Blocks:
Title
Banner
Product Slider
Product
Each Layout Block will need to have a definition of what parameters it needs to receive so it can be rendered.
This definition is very open and is defined by a JSON SCHEMA which needs to be compatible with the JDORN-EDITOR, you can see a demo here: http://jeremydorn.com/json-editor/
We recommend you to use this demo link to define your JSON SCHEMA for each Layout Block so that you can be sure your JSON is correct and will work.
Add a new Layout Block
First, Log in Boxalino Intelligence Admin (link)
Then open the Marketing Menu (the target icon) and click on Layout Block.
You will then see a list (probably empty) of already defined Layout Blocks.
Click on the “+ Add” green button on the top-left.
Then enter a name for your widget (all in small letter, without any space or special character except _ which is allowed) and press SAVE.
Please make sure to name your Layout Block well. This is the name that the Marketing Department will see when they want to create or change a Narrative, so it needs to make sense for them. Please refrain from indicating any type of naming based on a project use-case, as the Layout Blocks should make sense for other projects.
For example, do not use a name like : “brand_logo”, for the Layout Block to be used inside a slider or a grid of brand logos. instead, use a name like “image_square” or “image_cell” or “image_with_link” which describes what the template does functionally, so it will make sense in many different use-cases.
Edit a Layout Block
Now your Layout Block should appear in the list. You can edit it by clicking on the little pencil icon on the right.
You can now edit the content of your Layout Block, which mainly consists in 2 parts:
1. Define the fixed parameters
As defined in Narrative API - Technical Reference , the following fixed parameters should be defined:
Name | Example Value | Description |
|---|---|---|
template | product_list | the name of the template which should be used to display the block and its parameters |
model | product_list | (optional) the model that should be use in your MVC to manage the logic for this template rendering. In the majority of the cases you should not require any business logic and render the template directly, but in special situation (e.g.: to do a real-time look-up of a price before display) some controller method might be required in your template |
position | main | (optional) if you use a multiple column layout (e.g.: with search facets on the left column and results on the main column) this parameter will indicate for which column of your layout this block is destined. important: this parameter will change the structure of the response, see Fixed base structure above for details in Narrative API - Technical Reference |
In addition to the template, model (and optionally position), you can add other parameters if you want. They will be returned by the Narrative API, but will be fixed (so they will always be returned in the same way for the same Layout Block).
2. Define the JSON SCHEME
After creating your JSON SCHEME with the jdorn editor demo link and confirming with the preview of the generated form that it is valid and appears as you would expect (remember, this will be the form which will appear in the Narrative Editor for the marketing department), you can copy & paste it in the dialog in the JSON schema textarea (as in the image above).
In this example, we have a banner with localized values for 3 parameters:
Link when the banner is clicked (Banner Redirect URL)
Image source for the banner (Banner Source)
Alt text appearing as mouse-over on the image (Banner Alternative Text)
{
"title": "Banner",
"type": "object",
"properties": {
"banner_redirect": {
"type": "object",
"title": "Banner Redirect URL",
"properties": {
"de": {
"type": "string",
"description": "Set Banner Redirect URL in German."
},
"fr": {
"type": "string",
"description": "Set Banner Redirect URL in French."
}
}
},
"banner_src": {
"type": "object",
"title": "Banner Source",
"properties": {
"de": {
"type": "string",
"description": "Set Banner Source in German."
},
"fr": {
"type": "string",
"description": "Set Banner Source in French."
}
}
},
"banner_alt": {
"type": "object",
"title": "Banner Alternative Text",
"properties": {
"de": {
"type": "string",
"description": "Set Banner Alternative Text in German."
},
"fr": {
"type": "string",
"description": "Set Banner Alternative Text in French."
}
}
}
}
}3. Define the dynamic parameters & add their accessors to the JSON SCHEME
As defined in Narrative API - Technical Reference , there are several cases of dynamic parameters specially managed by Boxalino Narrative API. You should set them as parameters (and add their accessors to the JSON SCHEME) in the following cases:
Case | Parameter Name | Parameter Value |
|---|---|---|
Layout Block is a container of products | bx-hits | accessor |
Layout Block displays one specific product | bx-hit | accessor |
Layout Block displays a list of facets (filtering options) | bx-facets | accessor |
Layout Block displays a pagination control (user can go to the next, previous or other pages of the result list) | bx-pagination | accessor |
Layout Block displays the title of search results | bx-search-title | accessor |
Layout Block displays the currently selected product list sorting options | bx-sort | accessor |
Layout Block displays the number of results | bx-hitCount | accessor |
Layout Block displays is a container of search autocomplete textual suggestions | bx-acQueries | accessor |
Layout Block displays a specific textual suggestion | bx-acQuery | accessor |
In all of these cases, make sure to add a string property called accessor to the list of properties of your JSON SCHEME, like this:
"accessor": {
"type": "string",
"description": "hits accessor (typically leave empty)"
}This will enable the Narrative administrator to select another widget than the main one (by default).
Annex #1 - Typical Layout Blocks
We give here the full JSON (not only the schema the full json of the Layout Block you can import using the bottom-left Import button of the Layout Blocks list view.
product_list
Container of “product” Layout Blocks.
[
{
"uniqueKey": "product_list",
"parametersJsonScheme": "{\n \"title\": \"Label\",\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"object\",\n \"title\": \"Label\",\n \"properties\": {\n \"de\": {\n \"type\": \"string\",\n \"description\": \"label in German\"\n },\n \"fr\": {\n \"type\": \"string\",\n \"description\": \"label in French\"\n }\n }\n },\n \"see_all_label\": {\n \"type\": \"object\",\n \"title\": \"See all link label\",\n \"properties\": {\n \"de\": {\n \"type\": \"string\",\n \"description\": \"see all link label in German\"\n },\n \"fr\": {\n \"type\": \"string\",\n \"description\": \"see all link label in French\"\n }\n }\n },\n \"see_all_link\": {\n \"type\": \"object\",\n \"title\": \"See all link\",\n \"properties\": {\n \"de\": {\n \"type\": \"string\",\n \"description\": \"see all link in German\"\n },\n \"fr\": {\n \"type\": \"string\",\n \"description\": \"see all link in French\"\n }\n }\n },\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"hits accessor (typically leave empty)\"\n }\n }\n}",
"format": null,
"widgets": [],
"parameters": [
{
"name": "template",
"values": [
"product-list"
]
},
{
"name": "model",
"values": [
"product-list"
]
},
{
"name": "content-resource",
"values": [
"c-r=t"
]
},
{
"name": "bx-hits",
"values": [
"accessor"
]
}
],
"subRenderings": [],
"route": "visual-elements",
"reqParams": null,
"$fromServer": true,
"parentResource": null,
"restangularCollection": false,
"isSelected": true
}
]product
Display of one product in a grid or a slider.
facet_list
Display a list of faces (filtering options).
pagination
Display a pagination block (so the user can change the current page)
search_title
Display a pagination block (so the user can change the current page)
autocomplete_text_list
Container of “autocomplete_text” Layout Blocks.
autocomplete_text
Display one specific autocomplete textual suggestion (search as you type).