Report templates

In the config file upload interface, we can add as many .cson files as we want and use them in the etl_config.

Here is an example of a standard report.cson template:

name: "Name of the report"
entityName: "{{ report_id }}" # This column must exist in the data returned by the REPORTS block query
entityGroup: "{{ report_group }}" # This column must exist in the data returned by the REPORTS block query
id: "{{ index }}" # DO NOT CHANGE THIS
date: "July 2015"
managerName: "{{ manager_name }}" # Optional: This is how you can add more info to a report (see the data example above)
background:
  id: 1
  overlay: false
execsumTitle: "Text displayed on top of the home page"

search: # Search among reports
  hierarchy: false
  options: [
    default: 'Global'
    key: 'entityName'
  ]
  placeholder: 'Search...'

dashboards: # Search among dashboards
  search: "Search by country" # change the search bar placeholder text here

Note: You might see some templates with a ``slideInfos`` option.
This is a deprecated option and should not be used.

Important options

  • date: The date that will be displayed at the top of the home page
  • entityName: The name of the report that will be displayed in the search bars and on the home page.
  • background: Used to configure the background. Go to the asset upload interface to change this.
  • overlay: this sub option can be used to tint the color of the background image with your base brand color.
  • execsumTitle: A text that will be displayed at the top of the home page
  • dashboards > search: Used to change the text that is displayed as a placeholder inside the dashboards search bar. This bar will appear only if more than one dashboards exist for the current report.

Multiples reports

City
Paris
Milano
Barcelona
search:
  options: [
    key:'City'
    default:'Paris'#Paris will be selected by default
  ]
  placeholder:'Look for a city'

Multiple reports belonging to different groups

City entityGroup
Paris Economy
Milano Economy
Barcelona Economy
Paris Demography
Milano Demography
Barcelona Demography
search:
  options: [
    key:'City'
    default:'Paris'#Paris will be selected by default
    groupDefault:'Demography'#Paris demography will be selected by default
    placeholder:'Look for eco or demo info on a city'
  ]

Multiple reports belonging to different levels

Country Region City
World    
France All regions All cities
France North All North cities
France North Paris
France North Lille
France South All South cities
Italy All regions All Italy cities
search:
  options: [
    key:'Country'
    default:'World'#Paris will be selected at the Country level
    placeholder:'Look for a Region'
  ,
    key:'Region'
    default:'Paris'#Paris will be selected by default
    placeholder:'Look for a city'
  ,
    key:'City'
    default:'Paris'#Paris will be selected by default
  ]
  placeholder:'Look for a country'
Note: In the etl\_config, it is possible to increase/decrease the max number of report that the API returns. It can be useful to limit the quantity of data that the API returns in the case of limited internet connection. By default, the max number is set to 100. The ``MAX_SELECTABLE_REPORTS`` option can be used to change that number.

Default report

When we arrive on the small app, 2 cases can happen:

  1. There is no default report
  2. There is a default report: we are automatically sent to that report.
  1. No default report:

In that case, we first arrive on a report selection page. To achieve that:

  • Do not configure any default report
  • In the front_config, write:
# In front_config.cson
home:
  search:
    text: "Report of"
    placeholder: "a country"
    helper: "Please enter the first 3 letters of a country" # Will be displayed under the input
  widget: # This option is not required
    selectList: "Or select a report in the list" # Will be displayed above the widget list
    type: "list" # It will display buttons with a few reports to select directly
    limit: 15 # Choose the number of buttons you want to add in the list. This is optional, default value is 10

Example: Report selector example

Report selector with a map It is possible to display a map below the search bar, when the reports refer to geographic zones.

Report selector example with map The configuration is the following:

home:
  search:
    text: 'Barometer of'
    helper: 'Please enter in english the first 3 letters of your country'
    placeholder: 'ENTER A COUNTRY'

  widget:
    type: "chart"
    chartOptions:
      chartType: "map"
      baseMapUrl: "data/world-topojson.json"
      zones:
        data: "country_code"
        topojson: "id"
      categories: "Type"
      legend: true

Where :

  • zones: an object describing the dat joint on the column names:
  • zones.data : the name of the column in the report list
  • zones.topojson : the name of the property in the topojson map
  • categories: the column used to group zones with a color code (all zones in the same category will have the same color)
  1. Default report

In the report template, there is a default option that can take a number. The default report will be the one with the greatest default value. When multiple reports have the same value, the first report will be taken.

*Notes*

In most cases, default: 1 for the default report and default: 0 for the rest should be enough.

The numbers will be useful mostly in apps where a given user can access a limited number of reports, a binary notation will not be enough then.

The skipToReport option is deprecated and should not be used. It can still exist in older apps. It is used to declared the id of the default report. This option ranks lower than the default option in terms of priorities.

If you want a default report (and no report selector page), don’t forget to remove the home.search block from the front config.

Templating syntax

Double bracket syntax ``{{ something }}`` :

This syntax allows you to fill a template with variables from your reports.csv file: In our example, for the report_id “sales”, 3 dashboards will be generated, and every {{ dashboard_id }} in the dashboard template will be replaced by France, Italy, or Germany.

``__data__`` group : This group allows you to query data from your sources. The syntax is:

__data__:
  'some_name':
    query:
      domain: "data"
      country: "{{ dashboard_id }}"
    field: "value"

This query refers to the data.csv source file (see etl_config), which looks something like this:

| country      | value   |
|--------------|---------|
| France       | 1.0     |
| Italy        | 2.2     |
| Germany      | 3.4     |

You can then use the queried value:

value: "{some_name}"

The simple bracket {} syntax is Python’s formatting syntax. See Python number formatting for more examples.

Note on double quotes

You will encounter errors if the values inserted in your templates contain double quotes. To avoid these errors, you can use the escape_quotes filter.

For example suppose you are inserting an entity_name spelled like this: WB Group "Raki-Balu" entity.

entity: "{{ entity_name|escape_quotes }}"

Report Groups

You can use report groups to group reports in the dropdown selection like so:

You see there are 2 groups visible: Subsidiaries and Region.

To configure the groups you need in your report data a column mapping each report to a report group. In the below example the report_group column plays this role.

| report_id    | dashboard_id   |   default   |manager_name |report_group |
|--------------|----------------|-------------|-------------|-------------|
| sales        | France         |     1       |   Jean      |   group_1   |
| sales        | Italy          |     0       |   Vito      |   group_2   |
| sales        | Germany        |     0       |   Hans      |   group_2   |
| marketing    | France         |     1       |   Jacques   |   group_2   |

You then just have to refer to this columns in your report.cson file as the value of the parameter entityGroup:

name: "Name of the report"
entityName: "{{ report_id }}"
entityGroup: "{{ report_group }}" # This column must exist in the data returned by the REPORTS block query
[other parameters are detailed in the above example]