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

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.

For example:

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

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

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:

Dynamically change series' colors

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.