Tutorial

In this tutorial we’ll show you how to build a simple template.

We’ll start with a simple Flourish template that draws a single circle, and build on it to create data-driven circles with popups:

Screenshot of data-driven circles template

The finished template is available online. If you want to refer to the final code at any point, see the final repo.

You can use this tutorial as a guide for building your own Flourish templates. Important points are highlighted at the end of each section.

Get a basic template

Install the Flourish SDK (see the quick start for details), then get a basic Flourish example template:

git clone https://github.com/kiln/example-template-circle
cd example-template-circle
flourish run

Open http://localhost:1685 to see the basic template running.

This shows the core of Flourish: editable options to the right, and a live visualisation preview to the left.

Have a look at the files in the repo. In this tutorial, we’ll mainly be working with src/index.js (template code, compiled to template.js) and template.yml (which specifies the template settings).

This repo has extra files, including package.json to manage dependencies, and rollup.config.js to define the compilation process. You can ignore these.

template.js and template.yml are the only files actually required in a Flourish template. If you’re curious about what the other files do, see the guide to template files.

Add some data

Data visualisations need data! In Flourish it works like this: you define one or more user-editable data tables in the template.yml and specify default sample data in CSV format.

Create a directory called data, and add a CSV file:

mkdir data && cd data
curl -LO https://raw.githubusercontent.com/kiln/example-template-data-circles/master/data/Circles.csv

Open template.yml, and add the following section:

data:
- dataset: circles
key: x
name: x-value
type: column
column: Circles::A
- dataset: circles
key: y
name: y-value
type: column
column: Circles::B
- dataset: circles
key: size
name: Size
type: column
column: Circles::C
- dataset: circles
key: word
name: word
type: column
column: Circles::D

This tells Flourish that the template feautres a user-editable dataset called circles (which can be referenced in the template code in data.circles) and populates that dataset with sample data from data/Circles.csv. The end user in Flourish will be able to replace this data with their own and also change the specified columns.

To add a user-editable data table, set up a new dataset in template.yml and populate it with sample data in CSV format in the data directory. The resulting dataset is available in the template source code in the top-level data object.

Visualise the data

Now open src/index.js and start visualising your data. This example uses D3, though you can use any approach you like with Flourish.

First, add the data variable just above var circle;, to tell Flourish we want to import it from the settings file:

export var data = {};
var circle;

Then add the following line at the beginning of the draw() function:

export function draw() {
console.log('data', data.circles);

Open a developer console and you should see the data! It’s an array with a series of objects, one for each row of our CSV file.

Now we can use this data to draw new circles. First, replace var circle;, with:

var w, h, svg;

Replace the existing content of draw() with the following:

w = window.innerWidth,
h = window.innerHeight;
svg = select(document.body).append("svg").attr("width", w).attr("height", h);
update();

And replace the existing content of update() with the following:

var circles = svg.selectAll("circle").data(data.circles);
circles.enter().append("circle")
.attr("fill", state.color)
.attr("opacity", 0.5)
.attr("cx", function(d) { return d.x * w; })
.attr("cy", function(d) { return d.y * h; })
.attr("r", function(d) { return Math.sqrt(d.size); });
circles.exit().remove();

And finally delete the line if (!circle) return;. (If you’re confused, the GitHub repo shows the final file.)

You should see new circles in your browser!

Flourish expects all templates to have a draw() and an update() method. The draw() method is called when the document is first loaded: the update() method is called whenever there is user interaction.

Change the autoheight setting

Since this template is using the window height to set the height of the svg, we need to define the default height for the template. You can do this in the template.yml with the autoheight setting. You can either set a fixed height (px), a proportional height (vh) or an aspect ratio (width x height).

For this example, we always want the visualisation to be square. You can do this by adding autoheight: 1x1 to the top-level settings in template.yml, this should now look something like this:

id: ''
name: Untitled template
description: A Flourish template
author: Unknown author
autoheight: 1x1

Change the user-configurable options

The existing template allows the user to change the colour, radius and stroke of the circle: we will change this to colour and opacity.

User configuration options are defined in template.yml. Open this file and replace the existing settings section with the following:

settings:
- property: color
name: Color
description: The color of the circles
type: color
- property: opacity
name: Opacity
description: The opacity of the circles
type: number
min: 0
max: 1
step: 0.05

Refresh the app and you will see that these new options have appeared, but clicking on them doesn’t do anything yet.

Now wire them to our visualisation. First, replace the existing export var state line with our new state variables:

export var state = {
color: "#4f24ff",
opacity: 0.5
};

Then, add a new function:

function setAttributes(selection_or_transition) {
selection_or_transition
.attr("fill", state.color)
.attr("opacity", state.opacity)
.attr("cx", function(d) { return d.x * w; })
.attr("cy", function(d) { return d.y * h; })
.attr("r", function(d) { return Math.sqrt(d.size); });
}

And replace the existing line that starts circles.enter() with the following two lines:

circles.enter().append("circle")
.call(setAttributes);
circles.transition().call(setAttributes);

Refresh the browser. If you click on either setting, you should see the template respond!

This state variable tells Flourish the template’s current state, and is automatically updated by Flourish when the user changes a setting.

Add popups

Flourish can be extended with components. Here, we’ll show how to add popups with the Flourish popup component.

First, run:

npm install --save @flourish/popup

Next, open src/index.js and import it:

import Popup from "@flourish/popup";

And initialise it:

var w, h, svg, popup = Popup();

Now add a click event to your existing event in update():

circles.enter().append("circle")
.on("click", function(d) {
popup.point(d.x * w, d.y * h).html(d.word).draw();
event.stopPropagation();
})
.call(setAttributes);

And update the svg = ... line in draw():

svg = select(document.body).append("svg").attr("width", w).attr("height", h)
.on("click", function() { popup.hide(); });

Refresh, and you should see popups! If you’ve ever written your own D3 popup code, you’ll appreciate how much easier this component-based approach is.

You’re not restricted to Flourish components to extend your templates. You can add other NPM dependencies in exactly the same way.

Make it responsive

We want our visualisation to be responsive, so that the position of the circles will change when resizing the window. You can do this by adding a resize listener to the page. In the simple example below, every time the page resizes, the svg will be removed, and draw will be called again.

window.addEventListener("resize", function() {
svg.remove();
draw();
});

Prepare for publication

Open template.yml to see the template’s settings. Edit the name and author settings:

name: My example template
author: <your name>

Finally, you may want to update the thumbnail.png file in the root of your template - this shows a nice image when the template is published on Flourish Studio.

You may also want to update the content of README.md, which is displayed alongside your running template.

Publish to Flourish Studio

Make sure you’re registered (as per the quickstart) then publish the template:

flourish publish

Your template is now online, ready to share with your users!

Ready to do more? See the guide to template files, list of example templates and the reference.

If we can improve this tutorial, or help you get started with Flourish, please let us know.