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();
}