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 usingFlourish.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.