Configurable Page Scripts

Configurable Page Scripts enable you to add analytics and performance metric scripts to your community.

Khoros Communities Aurora enables you to configure page scripts to run during page loads, facilitating functionality such as analytics, web tracking, performance metrics, and more.

Khoros has incorporated this feature into the community repository so that you can continually update and add to your community's script library via Git.

Note: If you are familiar with the customization framework of Khoros Communities Classic, this method replaces the practice of loading scripts in the hitbox skin or last_chance_html components.

Page Script Files

Add page scripts under the res/pagescripts directory in your community Git repository:

A page script consists of the following files:

File(s)	Description
Page Script Descriptor	Every page script must have a single page script descriptor file that configures how the page script works. The file name must match the page script's directory name, with .script.json at the end.
Static Script	One or more JavaScript (.js) files.
Handlebars Initialization Script	An optional Handlebars file (.hbs) initializes the script.

More information on each of these files is provided in the sections below.

You will need to add one additional file, groups.scripts.json, directly to the res/pagescripts directory. This file specifies when each page script is loaded and in what order. We call this the Page Scripts Groups File.

The Page Scripts Groups File

Once you have placed the groups.scripts.json in the res/pagescripts directory, you can specify which page scripts are loaded, and in what order.

Here is an example Page Scripts Group file:

{
  "beforeInteractiveFirst": [
    "exampleThree",
    "exampleFour"
  ],
  "beforeInteractiveLast": [
    "exampleFive",
    "exampleSix"
  ],
  "afterInteractive": [
    "example",
    "exampleTwo"
  ],
  "lazyOnLoad": [
    "exampleSeven",
    "exampleEight"
  ]
}

There are four different arrays to which you can add page scripts based on the nextJs script strategies:

Array	Description
beforeInteractiveFirst	Scripts added to this array load before any Next.js code. This occurs before page hydration and beforeInteractive script loading.
beforeInteractiveLast	Scripts added to this group load before any Next.js code or page hydration but after any beforeInteractiveFirst and beforeInteractive scripts.
afterInteractive	Scripts added to this group are loaded early in the page load process but after some hydration on the page occurs.
lazyOnLoad	Scripts added to this group should be loaded lazily, on demand.

The Page Script Descriptor File

The Page Script Descriptor file defines the information needed to render the JavaScript that will be inserted into the page for the page script. This information includes:

• Any asset files to load
• Any static variables that should be included in the Handlebars context used by the Handlebars init script

Here is an example Page Script Descriptor file:

testHandlebarsContext.script.json

{
  "id": "testHandlebarsContext",
  "assets": ["testContext.js", "initScript.hbs"],
  "variables": {
    "dev": {
      "someKey": "abc"
    },
    "qa": {
      "someKey": "def"
    },
    "stage": {
      "someKey": "ghi"
    },
    "prod": {
      "someKey": "jkl"
    }
  }
}

Descriptor File Fields

• Field Name: id
  Required: Yes
  Description: The id of the page script. This should match the directory name and name of the file (minus the .script.json).
  Example:

  "id": "analytics"

• Field Name: enabled
  Required: No
  Possible Values: true, false
  Defaults (if not set): true
  Description: Whether the Page Script is enabled. If this is false, the page script does not render on any pages.
  Example:

  "enabled": true

• Field Name: assets
  Required: Yes
  Description: An array that lists the names of all asset files (either .js or .hbs if a dynamic initialization script is used).
  Example:

  "assets": ["analytics.js", "init.hbs"]

• Field Name: variables
  Required: No
  Description: If needed, a phase-specific (stage/pre-prod/prod) map of static variables to add to the page init script Handlebars context.
  Example:

  "variables": {
    "dev": {
      "someKey": "xyz"
    },
    "qa": {
      "someKey": "def"
    },
    "stage": {
      "someKey": "123",
      "anotherKey": true,
      "aThirdKey": 34
    },
    "prod": {
      "someKey": "456"
    }
  }

• Field Name: variables/${phase}
  Required: No
  Description: If needed, a phase-specific map of static variables to add to the page init script Handlebars context.
  Example:

  "stage": {
    "someKey": "123",
    "anotherKey": true,
    "aThirdKey": 34
  }

Static Page Script Assets

Add all static page script assets directly under the page script's unique directory at the same level as the Page Script Descriptor file. You should also add them to the assets fields in the order you would like them included in the script output for the Page Script.

Here is an example static page asset:

(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');

The Handlebars Page Script Initialization Script Asset

You may include a .hbs file as one of your script assets to initialize your Page Script's logic. This would involve calling an initialization function provided by one of your static script assets and possibly passing dynamically generated variables from the Handlebars context to that function.

Here's an example Handlebars init script:

init.hbs

initFunction('{{script.someKey}}', '{{page.name}}');

Or, for continuing with the testHandlebarsContext example:

initScript.hbs

ga('create',  '{{context.key}}' , 'auto');
ga('send', 'pageview');

The someKey field under the script context is a static variable added to the "variables" map in the Page Script Descriptor File. It has different values depending on the site's phase. If this is your stage site, it gets the someKey value under variables/stage. If this is your production site, it receives the someKey value under variables/prod.

The name field under the page context gives you the name of the page on which the script is loaded (either the page you refreshed or where you entered the community).

In this example, JavaScript calls a function named init, which is provided by an object named analyticsProvider. One of the static script files should define the analyticsProvider object with an init function that takes the arguments for the key and page name.

The Page Script Initialization Script Handlebars Context

The Page Script Initialization Script Handlebars template has access to a Handlebars context from which it can render variables.

The objects available on the Handlebars context are listed below:

• Context Field: script
  Description: Any context objects added to the variables field of the Page Script's Descriptor file are under the phase (stage, prod, etc.) that matches the phase of the site it's being rendered on.
  Example:

  {{json script}}

  Example (rendered):

  {
    "someKey": 123,
    "anotherKey": true,
    "aThirdKey": 34
  }

• Context Field: page
  Description: Information about the page the page script has loaded on.
  Example:

  {{json page}}

  Example (rendered):

  {
    "name": "CommunityPage",
    "context": {},
    "url": "https://cyclops.qa.lithium.com/",
    "props": {}
  }

• Context Field: page.name
  Description: The name of the page the script has loaded on.
  Example:

  {{json page}}

  Example (rendered):

  ForumMessagePage

• Context Field: page.url
  Description: The URL to the page the script has loaded on.
  Example:

  {{page.url}}

  Example (rendered):

  https://mycommunity.mydomain.com/discussions/my-board/some-discussion/1

• Context Field: