In this article, you'll learn how to use third-party scripts in your Higher Logic Vanilla (Vanilla) community, as well as a few tips if your scripts aren't working.
What is a third-party script?
Many platforms (e.g., HubSpot and Google) provide an HTML script tag for use on sites. You can read about implementing some specific scripts in their respective articles:
If your script isn't officially supported, however, it may still be possible to use it.
Can I continue using Pockets?
If you're willing to only use legacy layouts, you can continue using Custom HTML Pockets for your third-party scripts.
However, as we continue to modernize more and more of Vanilla and provide custom layouts for every page of your community, it is recommended that you use them. These custom layouts will make your site faster, more stable, and more secure, because they're built for the modern web's browser and security standards.
⚠️ IMPORTANT: You must include the domain where the script resides in the Content Security Domains field on the Dashboard > Settings > Security page.
Scripts in custom HTML widgets
There are two important things to know about using third-party scripts in custom HTML widgets:
- Each widget is in a shadow DOM, which means anything you put in the widget can only affect other things inside the widget. In other words, if you want to change something in the footer, or on the entire page, putting it in a custom HTML widget will not work. For this, you need to insert scripts in the Style Guide (more on this below).
- <script /> tags in the HTML tab of a widget will be ignored.
Add a script to a custom HTML widget
To add a third-party script to a custom HTML widget, you will need to create a <script /> tag using JavaScript, like this:
//Create a <script /> tag, set its src to the script's URL,
//and set the defer property
var script = document.createElement('script');
script.src = "{URL}";
script.defer = true;
//Add the script to the root of the shadow dom
customHtmlRoot.shadowRoot.appendChild(script);
Scripts in the Style Guide
If you want a third-party script to apply to every page, or to affect the header or footer, you need to insert them in the Style Guide's JavaScript tab.
This works essentially the same in principle, but we're going to structure the code a little differently for readability and usability purposes.
//Wrap the script creation in a function for reusability
function addScript(src) {
//Want to place the script in the header or footer of the page?
//Include one of these lines in the function
var themeHeader = document.querySelector("#themeHeader").shadowRoot;
var themeFooter = document.querySelector("#themeFooter").shadowRoot;
//Create a <script /> tag, set its src to the URL passed in via the function,
//and set the defer property
var script = document.createElement('script');
script.src = src;
script.defer = true;
//If the script needs to be placed in the <head> of the document,
//use document.head.appendChild(s); If you want to place it
//in the header of footer, use themeHeader.appendChild(s); or
//themeFooter.appendChild(s);
document.body.appendChild(script);
}
//We're only going to call the above function once Vanilla is ready to go...
onVanillaReady(() => {
//Call the addScript function and pass it the script URL
addScript("{URL}");
}
);
Why doesn't my script work?
Some scripts simply won't run correctly in a shadow DOM.
- They may evoke scripts on other domains that you haven't included in your Content Security Domains list.
- They may expect to have access to the top-level dom, or weren't written with strict web-security processes in mind.
Either way, we have no ability to guarantee every third-party script is going to work.
