The window.Flourish object

In each template you have access to window.Flourish, which is an object containing handy variables and functions.

.environment

Flourish.environment

The Flourish environment you're currently in. These are the possible values:

Environment	Meaning
sdk	Local SDK
editor	Flourish visualization editor
story_editor	Flourish story editor
live	Published visualizations or stories
preview	visualization in full-window preview
story_player	Story in full-window preview

.is_read_only

Flourish.is_read_only

A boolean telling the template if its settings and state can't be updated in the current Flourish environment.

• false when you are in the visualization or story editor and you have permission to edit the visualization or story, and inside the template SDK.

• true in all other environments (e.g. when viewing a visualization which you don't have permission to edit, or when viewing a published visualization).

Templates should use is_read_only to only expose controls to the user when changes to those controls will be persisted (i.e. when is_read_only is false).

.fixed_height

Flourish.fixed_height

A boolean value telling the template if the visualization is currently in a “fixed height” context.

• false when the template is embedded in a responsive iframe and has the power to change the iframe's height. This is the case in the editor (with no specific preview height set) or when embedded externally with a standard script embed code (without an explicit height set). In this context, you can optionally compute the ideal height in any situation and set it using Flourish.setHeight().

• true in all other situations, e.g. when viewed directly in a full-window preview, embedded with a simple iframe embed code, or when the user specifies an explicit height in the editor or their script embed code. In this mode your template will typically fill the available space.

A good template should do something sensible in fixed_height mode even if using setHeight() when available.

.setHeight(height)

Flourish.setHeight(number or null)

Sets the height of the embedding iframe if possible (i.e. when Flourish.fixed_height is false). Takes one argument which can be a number (the height of the iframe in pixels) or null (to revert to the default Flourish height for the current width).

setHeight() works in stories in addition to visualizations. It is harmlessly ignored if Flourish.fixed_height is true.

.static_prefix

Flourish.static_prefix

The path to the static folder of your template. For example to display an image called background.jpg from your /static folder, you could do document.querySelector("img").src = Flourish.static_prefix + "/background.jpg".

.upload()

Flourish.upload()

Upload a file to Flourish server.

.warn()

Flourish.warn({})

Display a warning message to the user in the Flourish editor. This can be useful in lots of situations, such as when:

• The user's data contains invalid values
• The user has tried to set a particular combination of incompatible settings
• The user has uploaded an image that is not valid

A message passed to warn() contains a message and explanation (both are optional). For example:

Flourish.warn({
    message: "Negative numbers are not supported",
    explanation: "The number " + bad_number + " in row " + row_number + " of the data is negative"
});

Messages appear in the top-right corner of the visualization editor. Flourish clears all messages each time the template's update() function is called.