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

As Best Practice, we recommend you to set template and model with the same value and to name them exactly as you named your Layout Block, this will make things easier and consistent.

Also, you might see some parameters appear by default like “content-resource” and can ignore them.

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)

For every parameter which is localized (meaning it could be different in each language), the structure of the example must be followed, so your property must be of the type “object” and have sub-properties with, as keys, the possible language codes (e.g.: “en”, “de”, “fr”, “it”, …). The value of each language must be of the type “string”.

In the response from the Narrative API, you will not receive the same structure, but only one string value for that property with the value in the requested language (i.e.: in this example, “banner_redirect” will be set with String as value with the value in the requested language).

{
  "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

The value can always be set to “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).

For example, if your Narrative contains several blocks of product recommendations, one of them (probably the first one) will be the connected to the main widget of the Narratives, but the other ones will create additional requests to other widgets. The Narrative administrator can then define the name of the widget in this accessor parameter. By knowing which accessor is defined, the Boxalino Narrative API will return the correct dynamic information.

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.

The JSONs are always provided below as list with one element, so you can directly copy & paste them in the import text-area which expects to receive not only one element, but a list of elements.

product_list

Container of “product” Layout Blocks.

must contain the parameter bx-hits with the value “accessor”

[
  {
    "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.

must contain the parameter bx-hit with the value “accessor”

[
  {
    "uniqueKey": "product",
    "parametersJsonScheme": "{\n  \"title\": \"Product\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"accessor\": {\n      \"type\": \"string\",\n      \"description\": \"hits accessor (typically leave empty)\"\n    }\n  }\n}",
    "format": null,
    "widgets": [],
    "parameters": [
      {
        "name": "template",
        "values": [
          "product"
        ]
      },
      {
        "name": "model",
        "values": [
          "product"
        ]
      },
      {
        "name": "content-resource",
        "values": [
          "c-r=t"
        ]
      },
      {
        "name": "bx-hit",
        "values": [
          "accessor"
        ]
      }
    ],
    "subRenderings": [],
    "route": "visual-elements",
    "reqParams": null,
    "$fromServer": true,
    "parentResource": null,
    "restangularCollection": false,
    "isSelected": true
  }
]

Display a list of faces (filtering options).

must contain the parameter bx-facets with the value “accessor”

[
  {
    "uniqueKey": "facet_list",
    "parametersJsonScheme": "{\n  \"title\": \"Facets\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"accessor\": {\n      \"type\": \"string\",\n      \"description\": \"facet accessor (typically leave empty)\"\n    }\n  }\n}",
    "format": null,
    "widgets": [],
    "parameters": [
      {
        "name": "template",
        "values": [
          "facet-list"
        ]
      },
      {
        "name": "model",
        "values": [
          "facet-slider"
        ]
      },
      {
        "name": "content-resource",
        "values": [
          "c-r=t"
        ]
      },
      {
        "name": "position",
        "values": [
          "left"
        ]
      },
      {
        "name": "bx-facets",
        "values": [
          "accessor"
        ]
      }
    ],
    "subRenderings": [],
    "route": "visual-elements",
    "reqParams": null,
    "$fromServer": true,
    "parentResource": null,
    "restangularCollection": false,
    "isSelected": true
  }
]

pagination

Display a pagination block (so the user can change the current page)

must contain the parameter bx-pagination with the value “accessor”

[
  {
    "uniqueKey": "pagination",
    "parametersJsonScheme": "{\n  \"title\": \"Pagination\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"accessor\": {\n      \"type\": \"string\",\n      \"description\": \"hits accessor (typically leave empty)\"\n    }\n  }\n}",
    "format": null,
    "widgets": [],
    "parameters": [
      {
        "name": "template",
        "values": [
          "pagination"
        ]
      },
      {
        "name": "model",
        "values": [
          "pagination"
        ]
      },
      {
        "name": "content-resource",
        "values": [
          "c-r=t"
        ]
      },
      {
        "name": "bx-pagination",
        "values": [
          "accessor"
        ]
      }
    ],
    "subRenderings": [],
    "route": "visual-elements",
    "reqParams": null,
    "$fromServer": true,
    "parentResource": null,
    "restangularCollection": false,
    "isSelected": true
  }
]

search_title

Display a pagination block (so the user can change the current page)

must contain the parameter bx-search-title with the value “accessor”

must also contains in the JSON schema a parameter called “title” and a parameter called bx_alternate_title so that a different label can be defined if an auto-correction occurred.

In the Narrative API response, the parameter bx_alternate_title can be ignored because the right value is always returned in the “title” parameter.

[
  {
    "uniqueKey": "search_title",
    "parametersJsonScheme": "{\n  \"title\": \"Title (H1)\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"title\": {\n      \"type\": \"object\",\n      \"title\": \"Normal Search Title\",\n      \"properties\": {\n        \"de\": {\n          \"type\": \"string\",\n          \"description\": \"normal search titlein German\"\n        },\n        \"fr\": {\n          \"type\": \"string\",\n          \"description\": \"normal search title in French\"\n        }\n      }\n    },\n    \"bx_alternate_title\": {\n      \"type\": \"object\",\n      \"title\": \"Corrected Search Title\",\n      \"properties\": {\n        \"de\": {\n          \"type\": \"string\",\n          \"description\": \"corrected search title in German\"\n        },\n        \"fr\": {\n          \"type\": \"string\",\n          \"description\": \"corrected search titlein French\"\n        }\n      }\n    },\n    \"accessor\": {\n      \"type\": \"string\",\n      \"description\": \"facet accessor (typically leave empty)\"\n    }\n  }\n}",
    "format": null,
    "widgets": [],
    "parameters": [
      {
        "name": "template",
        "values": [
          "title"
        ]
      },
      {
        "name": "model",
        "values": [
          "title"
        ]
      },
      {
        "name": "content-resource",
        "values": [
          "c-r=t"
        ]
      },
      {
        "name": "bx-search-title",
        "values": [
          "accessor"
        ]
      }
    ],
    "subRenderings": [],
    "route": "visual-elements",
    "reqParams": null,
    "$fromServer": true,
    "parentResource": null,
    "restangularCollection": false,
    "isSelected": true
  }
]

pagination

Display a pagination block (so the user can change the current page)

must contain the parameter bx-pagination with the value “accessor”

[
  {
    "uniqueKey": "pagination",
    "parametersJsonScheme": "{\n  \"title\": \"Pagination\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"accessor\": {\n      \"type\": \"string\",\n      \"description\": \"hits accessor (typically leave empty)\"\n    }\n  }\n}",
    "format": null,
    "widgets": [],
    "parameters": [
      {
        "name": "template",
        "values": [
          "pagination"
        ]
      },
      {
        "name": "model",
        "values": [
          "pagination"
        ]
      },
      {
        "name": "content-resource",
        "values": [
          "c-r=t"
        ]
      },
      {
        "name": "bx-pagination",
        "values": [
          "accessor"
        ]
      }
    ],
    "subRenderings": [],
    "route": "visual-elements",
    "reqParams": null,
    "$fromServer": true,
    "parentResource": null,
    "restangularCollection": false,
    "isSelected": true
  }
]

How to declare your Narrative Layout Blocks

Introduction

Add a new Layout Block

Edit a Layout Block

1. Define the fixed parameters

2. Define the JSON SCHEME

3. Define the dynamic parameters & add their accessors to the JSON SCHEME

Annex #1 - Typical Layout Blocks

product_list

product

facet_list

pagination

search_title

pagination