Carnegie Mellon University

CMU Web

A service provided by the University CMS Team

CMU Web  ›  How to Use the CMS  ›  Build Your Site  ›  Manage Your Site  ›  Advanced  ›  Site-Wide Scripts

Site-Wide Scripts

A site-wide script is a snippet of code that is to be included on every page of a site. The most popular site-wide script is Google Analytics. Follow the steps below to add a site-wide script to your site.

Important! You will need a Google user account to create a Google Analytics account. When creating a Google Analytics account, be sure to add more than one account-level administrator. Accounts should not be shared for security purposes. Any users with admin privileges should enable 2-factor authentication for secure login to their Google account.

Google Analytics Code

Check your Google Analytics code. Newer code is missing the async="true" value which is required in the CMS. Find async in the code and include ="true" as in this example:

<script async="true" src="https://www.googletagmanager.com/gtag/js?id=UA-xxxxxxxxx-x"></script>

Step 1: Create a Block

Blocks should be kept in a _blocks folder at the base level of a site. If your site does not have a _blocks folder, create one before proceeding (change folder settings to disable navigation and disable publishing).

  1. Select the _blocks folder in the asset tree, then click Add Content > Block
  2. For Block Type select Text, then click Choose at the upper right
  3. Enter a relevant Text Block Name (e.g., google-analytics, site-scripts); follow the requirements provided in the interface
  4. Scroll to Block Content and paste the script into the text editor; see important note regarding Google Analytics above
  5. Submit to save

Step 2: Edit the Setup Block and Choose the Script Block

  1. Select the Setup Block in the asset tree and then click Edit
  2. Scroll to the last setting for Additional Code; select Yes to enable
  3. Expand the Code section; two script locations are available, In Head (i.e., within the <head> HTML tag) and Before Closing Body (i.e., just before the </body> HTML tag); select the appropriate location based on script instructions
  4. Choose Block by browsing and selecting the block in the _blocks folder
  5. Submit to save

Step 3: Publish Full Site

You will never need to publish any blocks (script or Setup), however you will need to perform a full-site publish to add the script to the published version of every page. Moving forward, all new pages will automatically include the script when published.

Tips

If the existing block uses the same location where your script needs to go (i.e., either in the head or body HTML tag), you do not need to create another block; simply amend the existing block by pasting in the new script below any existing code (be careful not to modify any existing code).

If the existing block does not use the same location where your script needs to go, create a new block. In the setup, click the + sign near Additional Code to add a second block, then browse to choose the new block.

Note: Each site-wide script location (head and body HTML tags) should only contain one block each; additional scripts should be added to these blocks directly.

If after adding a script you receive an error when previewing a page, the script is likely not compatible with the CMS. This can sometimes be fixed by making minor modifications to the code, however any changes to third-party scripts should always be run by the third-party to ensure functionality. Below are known reasons why scripts are incompatible with the CMS and how to fix them.

Google Analytics

Google Analytics requires a minor adjustment to its script. Newer code is missing the async="true" value which is required in the CMS. Find async in the code and include ="true" as in this example:

<script async="true" src="https://www.googletagmanager.com/gtag/js?id=UA-xxxxxxxxx-x"></script>

Other Third-Party Scripts

Custom scripts provided by other third-parties may contain special characters which are not compatible with the CMS. This can sometimes be fixed by replacing the special character with its encoded version.

Example - The & symbol in this line of code caused errors loading pages in the CMS:
<img height="1" width="1" src="https://www.website.com/tr?id=xxxxxx&ev=PageView&noscript=1"/>

Correction - Replacing & with &amp; fixed the issue:
<img height="1" width="1" src="https://www.website.com/tr?id=xxxxxx&amp;ev=PageView&amp;noscript=1"/>

Note: Validation should always be performed after the installation of a script to ensure functionality.

Yes, this is possible.

  1. Complete Step 1 as instructed above
  2. For Step 2, instead of editing the Setup Block, edit the page where you want to add the script
  3. Click the Configure tab, then Choose Block for the appropriate location:
    1. Additional Optional - Head Tags - Add script to <head> HTML tag
    2. Additional Optional - Script Tags - Add script before closing </body> HTML tag
  4. Do not modify any other settings on page; submit to save
  5. Publish the page