Customize embeds

Embed Parameters

Additional panel

Applicable only on stories.

You can programmatically choose to show the additional panel that allows to display of sharing options.

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}=true" type="text/javascript"></script>

Initialize filters values

By default, your filters will initialize with the configured default value or the first value.

You can pass down the initial filters' values in order to load your visualization with a chosen set of filter values.

<script
  async
  src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}
&token={TOKEN}&filters.{FILTER_ID}={ENCODED_FILTER_VALUE}"
  type="text/javascript"
></script>

where ENCODED_FILTER_VALUE is a filter value that is JSON-stringified and then URI-encoded. It should be of different shape based on the filter kind

single filters (dropdown, hierarchical, single button): a key-value object with keys being dataset columns and values being values in the dataset row
multiple filters (checkboxes, multiple buttons): an array of single filter values
date range filters: a key-value object with two optional start and end keys and date values

For example, let's say we have a dataset of movies and whether they pass the Bechdel test:

movie_name	bechdel_test	release_year	director_nationality
The Social Network	fails	2010	american
Gran Torino	fails	2008	american
No Country For Old Men	pass	2007	american
V For Vendetta	pass	2005	australian
Fight Club	fails	1999	american

movie_name

bechdel_test

release_year

director_nationality

The Social Network

fails

2010

american

Gran Torino

fails

2008

american

No Country For Old Men

pass

2007

american

V For Vendetta

pass

2005

australian

Fight Club

fails

1999

american

and three filters:

0953c8d4-c5d0-4f2d-b3ba-e83480c337a3 dropdown on bechdel_test
2896ad55-4e45-49a1-80c2-00b74ae6d857 date range on release_year
7e1050e1-5f9f-433a-aeeb-14b47315c218 checkboxes on director_nationality

A reference implementation in JavaScript creates a script src attribute to display american or canadian movies released before 2000 that pass the Bechdel test would be:

const url = new URL('https://myinstance.toucantoco.com/scripts/embedLauncher.js');
url.searchParams.set('id', 'ID');
url.searchParams.set('token', 'TOKEN');
url.searchParams.set(
  'filters.0953c8d4-c5d0-4f2d-b3ba-e83480c337a3',
  JSON.stringify({ bechdel_test: 'pass' }),
);
url.searchParams.set(
  'filters.2896ad55-4e45-49a1-80c2-00b74ae6d857',
  JSON.stringify({ end: new Date('2000-01-01') }),
);
url.searchParams.set(
  'filters.7e1050e1-5f9f-433a-aeeb-14b47315c218',
  JSON.stringify({ director_nationality: ['american', 'canadian'] }),
);
console.log(url.href);

Note that URLSearchParams.prototype.set URI-encodes strings for you, so no need to use encodeURIComponent on top of it

That would make your script look like this:

<script
  async
  src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id=ID&token=TOKEN&filters.0953c8d4-c5d0-4f2d-b3ba-e83480c337a3=%7B%22bechdel_test%22%3A%22pass%22%7D&filters.2896ad55-4e45-49a1-80c2-00b74ae6d857=%7B%22end%22%3A%222000-01-01T00%3A00%3A00.000Z%22%7D&filters.7e1050e1-5f9f-433a-aeeb-14b47315c218=%7B%22director_nationality%22%3A%5B%22american%22%2C%22canadian%22%5D%7D"
></script>

After that initializing your filters, you can programmatically update Filters' values with the SDK.

Compact mode

Applicable only on stories

Our stories are made to automatically adapt their display to the size of the screens. If a story is inside a small container or displayed on a mobile (a device with small screen), it will be displayed in “compact mode”. You may want to force or forbid the compact mode:

Force compact mode

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}" type="text/javascript"></script>

Forbid compact mode

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}" type="text/javascript"></script>

Display staging version

Important

staging isn't accessible with view privilege

As you should know, our stories have a built-in production/staging versioning. That help you to have control on what it is displayed to your end-users. In order to display this “staging” version, you can set it right on the embed script.

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}" type="text/javascript"></script>

I18n

You can specify the used language of your embeds by passing by the “lang” parameter. More info here on how to setup locales on your platform and your application

<script async src="https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}&" type="text/javascript"></script>

Style Customization

You can customize all colors with the interface in Toucan Studio. (cf. Color Schemes)

What's interesting is that you can dynamically change those colors through the embed script via the colors attribute for webcomponent or query parameter for iframes.

For example:

webcomponent

<script
      async
      src='https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}'
      colors='{"chart-color-0": "pink"}'
      type='text/javascript'
></script>

iframe

<iframe src="https://myinstance.toucantoco.com/embed.html?id={EMBED_ID}&token={TOKEN}&colors={%22chart-color-0%22:%22pink%22}"></iframe>

Themes Name Code

Themes	Name	Code
Highlights (Active states, selections)	Emphasis	`emphasis-color`
	Accent	`secondary-emphasis-color`
	Positive	`positive-color`
	Warning	`warning-color`
	Negative	`negative-color`
	Neutral	`neutral-color`
Charts (Series data)	Serie #1	`chart-color-0`
	Serie #2	`chart-color-1`
	Serie #3	`chart-color-2`
	Serie #4	`chart-color-3`
	Series #x	`chart-color-x+1`
Scales (Quantified data)	Quartile #1	`scale-color-0`
	Quartile #2	`scale-color-1`
	Quartile #3	`scale-color-2`
	Quartile #4	`scale-color-3`

Highlights (Active states, selections)

Emphasis

emphasis-color

Accent

secondary-emphasis-color

Positive

positive-color

Warning

warning-color

Negative

negative-color

Neutral

neutral-color

Charts (Series data)

Serie #1

chart-color-0

Serie #2

chart-color-1

Serie #3

chart-color-2

Serie #4

chart-color-3

Series #x

chart-color-x+1

Scales (Quantified data)

Quartile #1

scale-color-0

Quartile #2

scale-color-1

Quartile #3

scale-color-2

Quartile #4

scale-color-3

Custom Series

You can also customize by data label.

Basically, tc-series-colors is a string with data labels in escaped double quotes, followed by the color separate by a space. You can define multiple labels, those groups are separated by commas. The following snippet will color bars with label Level 1 in red and label Level 2 in pink.

<script
      async
      src='https://myinstance.toucantoco.com/scripts/embedLauncher.js?id={EMBED_ID}&token={TOKEN}'
      colors='{"tc-series-colors":"\"Level 1\" red, \"Level 2\" pink}"'
      type='text/javascript'
></script>

Result as:

Fonts

Note

Custom CSS is a feature flag that we need to activate. By default the Custom CSS stylesheet is hidden as we’re not providing any support on it. To activate the Custom CSS on your instance please contact us.

For fonts, you can use our “Custom CSS” feature that lets you specify CSS rules within the Theme -> Color Scheme Interface. For now, you can only use a font host online. Let us know if it’s a big limitation for you.

Example, with Lato font:

Result as:

Deep Customization

Do you dream about having a complete control over the style of your embeds?

Click here for an example on the Dashboard Builder.

Last updated 11 days ago