Our URL settings allow you to control any of the settings you can change in a visualization or the views you can achieve, for example, selecting a value in a filter or setting a zoom level on a map.
NOTE: Please reach out to your Customer Success Manager if you are interested in using this advanced feature.
By identifying and adding a unique hash to the end of the URL in your embed, you can tell the template exactly what it should show and embed the visualization in this exact state.
There are a whole host of potential use cases for this feature, but here are a few of the most common ones:
- When you click on a region in a map, a panel opens with an embedded visualization showing...
- a column chart that highlights the bar for that region in a different color
- a line chart with a pre-selected filter showing only the line for that region
- a table with a pre-filled search field showing only rows for that region
The example below shows a projection map of London boroughs with three visualizations inside the panels that each use the URL state in the different ways described above.
Please bear in mind this is a very new feature and we are still working on making it more user-friendly and easy to implement. We hope to improve the user experience of URL settings in the future, but given its flexibility and the amount of control it provides, we just couldn't wait to share it with you!
In the meantime, you can follow these specific steps to get started:
Please note the URL settings are currently only available in our Line, bar, pie template and are only available for visualizations, not stories. This feature is only available to certain customers. If you are such as customer, you may need to contact us to be granted access.
Getting started
- 1
- Make the visualization you are wanting to control with URL settings as you would normally: adding your data and customizing it with settings to your preference.
- 2
- Notice the URL settings at the bottom of the settings panel.
- In this box, we need to include the names of the settings we want to be able to control with the hash at the end of the URL. If a setting isn't whitelisted here, the URL with the hash won't work as expected even if you follow all the other steps.
- We'll come back to this later when we've identified the settings we should include here.
-
(If the URL settings are not visible for you, you may need to contact us to be granted access to the feature)
- 3
- In the visualization editor page, click create a story, and change the visualization to a different view using the setting you want to manipulate.
-
In this case, we are selecting Series 3 from the series filter dropdown.
- 4
- In the story editor, open the console and type
Flourish.app.current_slide.state. This will return a list of the settings that are used in the story slide to set that particular view. -
Here, we can see the setting name
series_filteris used to select Series 3 from the dropdown. - 5
- Copy this setting, and re-write it as a JSON object in the console, assigning it to a variable, like so:
var myState = {series_filter: ["Series 3"]} -
TIP: If the setting you are using is nested you will need to use a nested JSON format for this step, like so:
var myState = {"color":{"categorical_custom_palette":"Series 3:#0b4f99"}} - 6
- Run
JSON.stringify()on this variable, and thenencodeURIComponent()on the stringified JSON object, like so: -
var myStateStr = JSON.stringify(myState) encodeURIComponent(myStateStr)
-
This will return the hash you need to add at the end of the viz URL to achieve the same, pre-selected view as in the story slide.
- 7
- Copy the hash from the console, and click through to your underlying visualization again.
-
TIP: Note that the hash is the string returned in the console without the quotation marks. In our example above, that would be
#%7B%22series_filter%22%3A%5B%22Series%203%22%5D%7D, not"#%7B%22series_filter%22%3A%5B%22Series%203%22%5D%7D" - 8
-
Next, we need to whitelist the setting we manipulated. Under URL settings, add the setting name as it appeared in the story editor console – in this case
series_filter. - 9
- Go into full preview mode in the visualization and add a
#to the end of the URL followed by pasting the hash you copied in the last step, like so:
#%7B%22series_filter%22%3A%5B%22Series%203%22%5D%7D
- To enter preview mode, click the Preview in new tab button in the top-left corner of the editor.
The preview should now show the visualization in the same view as in your story slide (i.e. with Series 3 selected). If it does, you now have the URL hash you're going to need.
TIP: Alternatively to using the console, you can bookmark the following URL to retrieve the JSON stringified and encoded object from a story:
javascript:(function(){alert(encodeURI(JSON.stringify(Flourish.app.current_preview_slide.state)))})();
- 10
-
Publish your chart and copy the iframe embed code.
When you embed this code on your site (or in a popup or panel of another visualization), at the end of the URL in the embed code add the
#symbol followed by the hash you identified, like so:<iframe src='https://flo.uri.sh/visualisation/6003757/embed#%7B%22series_filter%22%3A%5B%22Series%203%22%5D%7D' title='Interactive or visual content' frameborder='0' scrolling='no' style='width:100%;height:600px;' sandbox='allow-same-origin allow-forms allow-scripts allow-downloads allow-popups allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation'></iframe><br>
For some examples of URL hashes you can simply copy and paste to use yourself, take a look at our help doc here.