Working with settings
One of the most important parts of Flourish is the settings panel. The settings panel allows you to go from a static visualization to a dynamic template that can be modified by anyone.
To work with settings, we first need to add the setting to the sidebar, and then make sure the template does something with the setting's value.
For this example, we're going to create a setting that changes the background color of our visualization.
Adding a new setting
Look for the template.yml
and open this file in your code editor. The template.yml contains general information about your template, like its ID, name and template author. But there is also a section called settings
. It should look something like this:
settings:
- Section title
- property: example_state_property
name: Example number setting
description: A setting for changing a number
type: number
Looks familiar, right? It's the setting we see on the right-hand side of the preview in the SDK. You can add as many settings as you like, just take a look at the API reference to see what exactly you can do with settings. For now, we want to add an extra setting that looks like this:
settings:
- Section title
- property: example_state_property
name: Example number setting
description: A setting for changing a number
type: number
- property: background_color # property for storing the setting's value in the template's state
name: Background color # Name that appears above setting
description: Set the background color of the visualization # Description that appears on hover of question mark next to name
type: color # Setting type
There should now be an extra setting in your SDK preview:
Making the setting do something
Okay, so we've created a new setting. It's even possible to change the setting. However, when we change the setting, nothing happens. This is because we haven't told the template what to do with the setting's value.
Now of course it's up to you what the setting does exactly, you might use it to change the color of some element in the visualization, or change the color of some text. But in this case we want to change the color of the background of the body. For that, we need to dive into the src
folder of our template.
Getting the setting's value
Open src/index.js
. In there, you'll see a couple of functions and objects:
- the
data
object, that’s where user-editable data tables will be stored - the
state
object, which stores the visualization’s current state (all the current settings' values) - the
draw()
function, which is called when the visualization loads - the
update()
function, which gets called everytime the data or a setting changes
The first thing we want to do, is make sure we store the value of the background color setting in the state
. When creating the setting in template.yml
, we set a property
for the setting, we will add this property to the state
. Our property was called background_color
, so we'll add it to the state
and set it to #ff0000
:
export var state = {
example_state_property: 25,
background_color: "#ff0000"
};
Using the setting's value
What's left is some JavaScript logic to make sure the body background color is set to state.background_color
. So head to the update()
function and add this line document.body.style.backgroundColor = state.background_color
;
export function update() {
document.body.style.backgroundColor = state.background_color;
}
Now change the setting, and you'll see that the background color changes. However, when you load the visualization it still shows the white background, while the value of the setting is bright red by default. This is because when the template is loaded, only draw()
gets called, and update()
only gets called when a setting or data has changed. Therefore, we recommend calling update()
at the end of your draw()
function:
export function draw() {
// Code you want to execute on the first time the template loads
// Calling update
update();
}