Inject Custom JavaScript

Inject custom JavaScript (JS) into the your site to customize the help center theme beyond the options offered in the visual theme configurator UI.

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.

We recommend you only use this feature if you’re experienced using JavaScript. Adding custom JavasScript 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

You can inject custom JavaScript using the JavaScript code editor built into the theme configurator:

1. Open the theme configurator from Site Settings > Look and feel > Customize theme.

2. Click on the Code tab.

3. Enter your custom JavaScript code in the JS editor field.

4. Click Save changes once you are happy with your code.

Now you can Close the editor and click Publish changes from your site settings.

Once applied, 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

The help center theme 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 cannot 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 the help center theme. 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 Sites.

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 consent management in the theme configurator.

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.

Use the following pointers to decide if you should execute your script:

if (sts.cookies.acceptedCategory('analytics')) {
  console.log('user accepted the analytics category');
}

sts.cookies.on('change', () => {
  if (sts.cookies.acceptedCategory('analytics')) {
    console.log('user changed consent for the analytics category');
  }
})

Limit script execution to specific pages

You can limit a script to specific pages in your site using the page’s data-page-id. This lets you display specific content or functionality only on those specified pages.

To find out the data-page-id for a specific page, navigate to the page in your Scroll site, inspect the HTML for data-page-id and copy out the ID.

Add the following line before your JS code and insert your copied ID to limit the execution of your JS to that page:

if (document.documentElement.getAttribute('data-page-id') === 'PAGE_ID') {

Loading external scripts

Use the sts.loadScript(url:string): Promise<void> function to load external scripts into your Scroll site’s 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:

sts.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 site’s URL in the browser to exclude the custom resources from the theme.