Customize embeds

Embed Parameters

Additional panel

Applicable to stories only (not tiles).

The Additional Panel can be customized to include features like Annotate and Share, Export Data, and Send by Email. To enable or disable these options:

1. Go to the Advanced Configuration of your Toucan application, accessible from the Settings button in the staging bar.

2. Edit the app_config file:

   • Set true to enable an option or false to disable it.

Example: To enable “Annotate & Share,” set: annotateAndShareEnabled: true.

Enabling the Additional Panel in Embeds

In an Embedded Story: Enable the panel options in the application and activate them in the embed modal.

In an Embedded Dashboard: Enable the options in the app, then add &panel=true in the embed script.

<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, filters load with the default or first value.

You can set initial filter values by adding them to the embed URL:

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

ENCODED_FILTER_VALUE should be JSON-stringified and URI-encoded, formatted depending on the filter type (single, multiple, or date range).

• 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

For instance, to display only American or Canadian movies from before 2000 that pass the Bechdel test:

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

For stories in small containers or on mobile, stories automatically display in compact mode. To control this manually:

• Force compact mode

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

• Disable 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

Toucan provides production and staging versions. To display the staging version, add &stage=staging to the embed URL:

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

Language Customization (i18n)

Set the language of your embed by adding the lang parameter:

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

Style Customization

Adjust colors dynamically within the embed script:

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:

Web Component

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