How to :: structure your story in code mode

Important

This is only available from the code mode

Structure is very important when you tell a story, find out how to build the table of content of your story.

Design your chapters

You can (and should!) customize the menu and so the stories hierarchy.

front_config.cson relies on an array of slides to build the hierarchy of menus and submenus. Each slide is represented by an object that must have an unique id property and a level.

slides: [
  id: 0
,
  id: 1
,
  id: 2
]

Location of the slides in the navigation/hierarchy is commanded by the level property.

slides: [
  id: 0
  level: 1 # Categories
,
  id: 1
  level: 2 # Subcategories
,
  id: 2
  level: 3 # Actual slide
]

Relation between slides are indicated by the property parent_id. In the example below we have a full hierachy from level 1 to level 3:

slides: [
  id: 0
  level: 1
,
  id: 1
  level: 2 # Subcategories
  parent_id: 0
,
  id: 2
  level: 3 # Actual slide
  parent_id: 1
]

Manage the display order inside a level

The display order corresponds to the order (from top top bottom) in the front-config.cson file. So write categories, subcategories and slides in the order you wish to display them.

Note that level 2 is optional, a level 1 slide can be parent for a level 3 slide, like so:

slides: [
  id: 0
  level: 1
,
  id: 2
  level: 3 # Actual slide
  parent_id: 0
]

Best practices

There are only 3 levels availables. Levels 1 and 2 corresponds to chapters and sub-chapters. Level 3 corresponds to charts. We believe that more levels would confuse the user –> keep it simple!

Note

As a rule of thumb do not use sub-chapters. Break this rule when you have too many slides in a chapter (>6).

Structure your slide visibility

You can customize the visibility slides. A slide with option visibility will be visible in production and staging mode.

The values possible for option visibility are: true or false

Example:

Configuration

level: 3
 title: "Life is beautiful"
 parent_id: 10
 id: 10000
 visibility: false

Note

The slide of a hidden chapter will still be accessible via the url.

Customize your stories: 1 story per user group!

Note

If you’re not confortable with the notion of user groups/point of view on the data read the Point of views chapter.

You can restrict the access to a chapter or a screen in the app depending on the selected report or depending the groups of the connected user.

In the a slide of level 1, 2 or 3 you can add a restrictVisibility block. Here a the options:

  • Either you restrict the visibility for given reports. In this case you must have the reportEntry key and either allowedReports or excludedReports:
  • reportEntry : this is the key in the report object that you’ll be using to filter on. It is set in the report template.
  • allowedReports : an array of values that the reportEntry key can take for which the block will be visible.
  • excludedReports : an array of values that the reportEntry key can take for which the block will be invisible.
  • Or you restrict the visibility for given user groups. In this case you should have either the allowedUserGroups entry or excludedUserGroups:
  • allowedUserGroups: an array of groups for which the block will be visible
  • excludedUserGroups: an array of groups for which the block will be invisible

Example 1:

Data structure

report.csv

name type
Region_1 Region
Group Worldwide
City_A City

Objective

We want chapter with id 10 to be only accessible for reports with type = Region, or type = Worldwide.

Configuration

{
  level: 1
  title: "First Chapter of my Life"
  id: 10
  restrictVisibility:
    reportEntry: 'type'
    allowedReports: [
      'Region'
      'Worldwide'
    ]
}

The reportEntry has to be configured in the according report template. Reports with other type won’t be able to see this chapter. It will be invisible in the menu on the left.

Example 2:

Data structure

report.csv

name type
Region_1 Region
Group Worldwide
City_A City

Objective

We want slide with id 10000 to be inaccessible for reports with type = Region.

Configuration

level: 3
 title: "Life is beautiful"
 parent_id: 10
 id: 10000
 restrictVisibility:
   reportEntry: 'type'
   excludedReports: [
     'Region'
   ]

Example 3:

Objective

We want slide with id 10000 to be only accessible for user belonging to the ‘manager’ or executive groups. First you have to set correctly the groups in the user administration page and then configure the block in the front_config.

Configuration

level: 3
 title: "Life is beautiful"
 parent_id: 10
 id: 10000
 restrictVisibility:
   allowedUserGroups: [
     'manager'
     'executive'
   ]

Note

The slide of a hidden chapter will still be accessible via the url. As a consequence if the user is on slide 10000 and switch report with type Region to another with type city, the slide will be visible if only configuration of example 1 is used. In this case you shall use a restrict visibility at the chapter level and at slide level.