Inject Custom JavaScript
Inject custom JavaScript (JS) to your Scroll Viewport site using the built-in JS editor. The JS editor allows you to further customize the Help Center theme beyond the options provided in the visual theme editor.
This is an advanced feature for users that are comfortable with web development. Adding custom JS can break your site or affect it in unexpected ways.
Please note, problems resulting from your custom code is not within the scope of product support.
Applying Custom JavaScript
To find the CSS editor, click Edit Theme from your site overview and go to the Templates menu. In the Additional section, expand the JS editor. To apply your code:
Enter your custom JavaScript code in the editor field.
Click the Reload icon that appears inside the JavaScript Editor. This applies the script to the theme preview on the right.
You can also use the keyboard shortcuts "⌘” + “⏎" for Mac and "Ctrl” + “⏎" for Windows and Linux.Click Save once you're happy with your code.
Your custom JavaScript resources will load on every page of the theme, directly after the theme’s own resources.
Best Practices
Check browser support
Your custom JavaScript is running directly in the browser. For this reason, make sure you stick to JavaScript syntax and features that are generally supported amongst browsers. If you’re unsure, use a resource like caniuse.com to check browser support.
Remove HTML elements from code snippets provided by third-party services
Scroll Viewport does not allow you to insert HTML but only JavaScript code. Some third-party services do provide their integrations only as snippets of HTML code and assume that you are able to insert those scripts into your HTML files. They often provide script tags that contain JavaScript code and instruct you to paste this HTML before the end of the </head> tag of your page.
Since you can't insert HTML, simply remove all HTML elements and insert only the JavaScript code that is between the <script> and </script> tags.
Avoid manipulating DOM elements whenever possible
We highly recommend that you avoid to manipulate the Document Object Model (DOM) elements of your site whenever possible. The selectors that you use to access parts of the page can change in future updates of Scroll Viewport. Also, your manipulations to dymanic parts of the page (e.g. the page tree, the table of contents) may be lost if these parts are updated by Scroll Viewport.
Safety measures you can take:
Keep your DOM manipulations to an absolute minimum.
Limit your DOM manipulations to the non-dynamic parts of the page (e.g. the article content).
Only set cookies if your site visitors have given consent
If your custom JavaScript relies on the usage of cookies (i.e it needs to set cookies in visitor's browsers in order to work), we recommend you enable the cookie notice in the Theme Editor.
Whenever your script intends to set cookies or track the site visitor, it’s good practice to make the execution of your script dependent on the visitor’s cookie choices and only run the script if your visitor has given consent to the use of cookies.
Add the following code to your custom JS to decide if you should execute your script:
if (vp.user.hasAllowedCookieUsage) {
console.log("User has allowed cookies");
}Limit script execution to live sites
Scroll Viewport pages might often be viewed by authors using the the page preview and site preview. If you use custom JavaScript e.g. to add some special tracking functionality, you want to make sure that your script will not be executed in those situations.
In those cases, it’s good to check if the current page is being viewed on a live site before running the script.
Add the following code to your custom JS to decide if you should execute your script:
if (!vp.preview.isPagePreview() && !vp.preview.isSitePreview()) {
console.log("This is a live site");
}Loading external scripts
Use the vp.loadScript(url:string): Promise<void> function to load external scripts into your Scroll Viewport pages. It returns a Promise that gets resolved once the script has been loaded.
So add the following code to your custom JS to load an external script and wait for it to be fully loaded:
vp.loadScript('https://...').then(() => {
console.log("External script has been loaded!");
});Know and inform about third-party resources
Make sure you only load code from trusted sources such as your own servers, trusted services you would like to integrate with, or trusted CDNs.
If you load and use third-party resources, inform your site visitors about it by updating your privacy statement.
Trouble With your Site After Adding JavaScript?
Is your site displaying errors or not working as expected? To exclude your custom JS as the root cause of the problem, we recommend testing your site without any custom JS applied.
Add ?disable-custom-overrides=true as a parameter to a Scroll Viewport site URL in the browser to exclude the custom resources from the theme.