Using Flourish modules
When creating templates you'll find that some tasks get repeated very often. For example, every project might need a header and footer, or you may want to frequently parse and format numbers according to the user's settings.
This is why we create Flourish modules and add them to our templates. These modules are all in NPM and can be used by anyone in Flourish templates.
The Flourish modules
Here's a list of Flourish modules:
@flourish/axes-highlights
A module for adding axes annotations (line and range highlights).
@flourish/chart-layout
A module for creating axes and plot backgrounds.
@flourish/colors
A module for creating color palettes.
@flourish/controls
A module for adding interactive controls (dropdowns, buttons and sliders). Used in conjunction with Flourish UI styles.
@flourish/facets
A module for creating grid layouts, typically used for “small multiples” visualizations (also known as “grid of charts”).
@flourish/info-popup
A module for adding tooltips and panels and filling them with dynamic content.
@flourish/layout
A module that adds empty containers for header, footer, controls and legend and automatically creates enough space for your visualization container.
@flourish/legend
A module for adding color (numeric & categorical) and size legends.
@flourish/number-formatter
A module for parsing and formatting numbers (includes adding prefixes/suffixes, setting decimal places and more). Used in conjunction with Flourish number localization.
@flourish/number-localization
Flourish module for setting the numeric separators used in a template. Used in conjunction with Flourish number formatter.
@flourish/pocket-knife
A module containing various handy development utilities.
@flourish/radial-axis
A module for radial (or circular) axes, like those in the Radar template.
@flourish/slider
A module for creating an interactive slider.
@flourish/ui-styles
A module for styling UI elements (like @flourish/controls) in Flourish templates.
@flourish/url-state
A module for manipulating state settings via a URL hash.
Installing Flourish modules
You can install a Flourish module into your template using NPM. For example, if you want to install the legend module into your template, you can run npm install --save @flourish/legend.
Every module has specific installation instructions, so look at the module's documentation for specific installation instructions.
Importing module settings into template
Flourish modules also usually have some settings that can be imported into the template settings panel. For example, when using the legend module, you can import settings for the height of the legend, text color, etc.
Each module works slightly differently, so take a look at the module's documentation for precise instructions. In general, you can import a module's settings like this, in template.yml (Not sure how settings work? Take a look at our guide)
settings:
- property: my_property
import: "@flourish/module_name"
Then in your state object, make sure to create an empty object for my_property:
export var state = {
my_property: {}
}
When the template gets initialized, this empty object will be populated with all the module's settings values.
Module settings overrides
In some cases you might want to tweak a setting when importing a module. For example you might want to show/hide it on a certain condition, change the name, or change the size.
It's possible to do this with the overrides property. It takes an array of settings. Each setting needs a property and all the things you'd like to override. For example:
settings:
- property: my_property
import: "@flourish/module_name"
overrides:
- property: property_name_1 # The property name of the setting you'd like to change
name: New name # The setting now has a name of "New name"
- property: property_name_2 # The property name of the setting you'd like to change
hide_if: true # This setting will now be hidden
- property: property_name_3 # The property name of the setting you'd like to change
new_section: true # This setting will now have a divider line
Conditionally showing/hiding an entire imported settings block
In some templates, you may only want to show settings when it's relevant. For example, you only want to show settings for a categorical legend if you are using a categorical color scale.
In Flourish, it's possible to do this with the show_if and hide_if property, as explained here. If you want to apply this to an imported setting block, you can do so like this:
settings:
- property: my_property
import: "@flourish/module_name"
show_if: <true/false condition>