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 visualization 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 visualizations 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:

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

Visualize the data

Now open src/index.js and start visualizing 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);

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

var circles = svg.selectAll("circle").data(data.circles);
.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); });

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.

Decide how height should work

Since this template is using the window height to set the height of the SVG, the height will be determined by how the visualization is embedded. If viewed in full window mode, the SVG will fill the window. If the project is embedded explicitly at 400px tall, the SVG will be 400px tall. If the project is viewed in the editor or embedded in the default “auto” mode, the height will be set by Flourish to be a sensible standard height based on the current width.

If this behavior isn’t what you want, you can instead call Flourish.setHeight([number]) to tell the embedded project to get taller or smaller. This is useful if you want to make a visualization with a specific aspect ratio or one that grows to accommodate changing amounts of text, etc. Note that this only works in the Flourish editor or when the published project is embedded with the standard embed script.

Change the user-configurable options

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

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

- 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 visualization. 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) {
.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:


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 initialize it:

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

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

.on("click", function(d) {
popup.point(d.x * w, d.y * h).html(d.word).draw();

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 visualization 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() {

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.