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_namebechdel_testrelease_yeardirector_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>
ThemesNameCode

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