template.yml

The main template configuration file. The top-level properties are:

  • sdk_version Which major version of the Flourish SDK the template is compatible with. Currently this should be 2.
  • id A unique identifier for your template. If you publish a template and the id is already in use by you, the Flourish server will assume you are updating an existing template and overwrite it.
  • name What the template will be called within Flourish
  • author Who wrote the template
  • description A short description of the template
  • credits Optional credits for data sources, map tiles, etc, in Markdown format
  • image_download Flag to indicate whether an image snapshot can be generated. Defaults to true.

Other properties are settings, data and build, which are described below.

settings:

The template.yml file will usually also include a settings section which populates the settings panel in the Flourish visualisation editor (and SDK). Each setting allows the user to change a specific property in the template state. When a setting is changed by the user , state is updated and the template’s update() function is called.

If an entry in the settings array is a string, it is interpreted as a section title. Otherwise it must be an object with the property and type properties. Other properties are optional, but name and description are recommended to help the user understand the role of the setting.

settings:
- Section title # Headings can be used to break up the settings into collapsible sections
- property: my_state_property # Required; must be a property of the [state object](template-api.html#state)
name: Example number setting # Optional; appears next to the setting
description: A setting for changing a number # Optional; appears on mouseover
type: number # Required; see available types below

To improve the layout of your settings, you can set the width of any setting to be half or quarter of the width of the settings panel. You can also add a horizontal separator above a setting using new_section: true.

- property: my_number
name: Near little number input
width: quarter # Optional; sets the width of the setting
new_section: true # Optional; starts a new line with the current setting and adds a line above

Settings types

The following types of settings are supported:

boolean

Creates a checkbox that sets the state property to true or false.

color

Creates a colour picker that sets the state property to a string containing a hex RGB colour e.g. "#123456".

number

Creates a number input that sets the state property to a number. Optionally add min and max properties to limit the range, step to control the input’s increment buttons. By default number settings always return a number and blanked inputs are set to zero; to allow blanked input, with null returned as the value, add optional: true.

string

By default, creates a single-line text input that sets the state property to the relevant string text. If you add a valid choices property, the setting instead creates a dropdown (by default) or button group (if you also add style: buttons). The choices property must be an array. Each of its element can be a string (in which case this string is returned to the state) or an array containing a display name, the associated string value and (for button groups) a background image.

To a special dropdown that allows the user to specify any text in addition to choosing from the list, add choices_other: true. This is ignored for button groups.

- property: size
name: Size
type: string
choices: # An array of values to fill the dropdown
small_size # A choice can be a string
# Or a choice can be an array of two or three elements …
Absolutely enormous # … in which case the first string is the display name,
large_size # … the second string is the value passed to the template
massive.jpg # … the third is an image file name in your `static` directory
choices_other: true # allows the user to input any value they like
text

Creates a user-resizeable multiline text input. Defaults to two lines tall. Can be made taller by adding size: large, which sets the height to half of the viewport height.

code

Same as text but with a monospace font and text-wrapping control.

url

Creates a single-line text input with an upload button next to it. The file will be uploaded to a Flourish server and the field will be populated with the url of the uploaded file.

Conditional settings

Sometimes you might want to simplify the user experience for Flourish users by hiding some settings depending on whether they are needed or not. You can use the show_if and hide_if properties to control whether or not a setting should be displayed based on another setting’s value.

In the following example, the x axis label setting will only be displayed if “Show x axis” is selected:

- property: show_x_axis
name: Show x axis
type: boolean

- property: x_axis_label
name: X axis label
type: string
show_if:
show_x_axis: true

You can use the following shorthand syntax for booleans. This is equivalent to the previous example:

show_if: show_x_axis

If you specify an array of conditional values, this setting will be displayed if the referenced setting has any of the specified values. In the following example, the setting is displayed if color_mode is set to either "diverging" or "continuous":

show_if:
color_mode: [diverging, continuous]

You can specify multiple conditions. All of these tests must pass for the setting to be displayed. For example:

show_if:
show_x_axis: true
color_mode: diverging

The hide_if option works in exactly the same way, except that the setting is hidden if the conditional test passes.

hide_if:
color_mode: diverging

You can also control settings display depending on whether or not particular data bindings have been specified. A binding is specified using the syntax data.[dataset].[key]. For example:

show_if: data.values.filter1 // shorthand syntax

show_if:
data.values.filter1: true

You cannot specify both show_if and hide_if options on the same setting.

data:

The template.yml file may also include a data section. This section consists of an array of data ‘bindings’ that sets how the template should use and refer to the template’s editable data tables (which are initially populated by the CSV files in data/). Each binding adds one or more columns of data to a dataset under a particular key. You can define as many datasets as you like. They are made available to the template as properties of the data object. Each one consists of an array containing an object for each row of the relevant data table, as shown in the example below.

Once your template is published, Flourish users can change the data in the Flourish editor, and also change which columns are linked to each binding. But in your code you don’t need to worry about this because you just refer to the key rather than referencing the column header or index.

There are two types of data binding: column is used when the number of columns is and must always be one; columns supports any number of columns, including none.

A default value must be supplied for each data binding, unless you have specified optional: true (only supported for single column bindings). The example below shows how this is done.

Example data configuration

The following example sets up a dataset with two keys, one single-column and one multi-column.

data:
- Locations # Optional title; breaks up the bindings into collapsible sections
- Binding description # Optional description for this section, shown in the UI
- name: Country code # Name shown in UI
description: Requires ISO 3166-1 alpha-2 codes # Optional description for the UI
dataset: country_scores # Which dataset this binding is part of
key: iso_code # The key used to access the data in this binding in the template code
type: column # This binding can take only one column
column: By Decade::A # The default values are drawn from column A of `By Decade.csv`
- name: Values
dataset: country_scores
key: values
type: columns # This binding can take any number of columns
columns: By Decade::B-D,F # The default values are arrays drawing from columns B-D and F of `By Decade.csv`
- name: Flag image
dataset: country_scores
key: flag_pic
type: column
optional: true # Default values can be omitted for an optional binding

In this example, if By Decade.csv contained the following…

Country,1970s,1980s,1990s,20th_century_mean,2000s
US,3122,3128,3129,984,3119
GB,1203,1205,1208,1121,1200
FR,1030,1005,1010,3076,1024

… then in your template data.country_scores would be:

[
{ iso_code: "US", values: [ "3122", "3128", "3129", "3119" ]},
{ iso_code: "GB", values: [ "1203", "1205", "1208", "1200" ]},
{ iso_code: "FR", values: [ "1030", "1005", "1010", "1024" ]}
]

The column headers are available in any dataset via the column_names property of the data array. E.g. in the above example data.country_scores.column_names is:

{ iso_code: "Country", values: [ "1980s", "1990s", "2000s", "2010s" ]}

build:

The template.yml file will usually also include a build section defining build rules.

It defines the build processes used to build your template from source. You can have any number of build processes, and changes to the relevant files will trigger the appropriate build.

The following example defines build scripts for JavaScript and CSS:

build:
src:
script: npm run build
directory: src
files:
- rollup.config.js

less:
script: npm run less
directory: less

Each build rule defines a script, and a directory and/or an array of files. If any file in the specified directory, or any file named in the array, changes while the SDK is running then the appropriate build script is executed. The flourish build command can be used to test build rules.