Sometimes you need a small piece of JavaScript on your CiviPlus site — a button that scrolls the page back to the top, a tweak to how a form behaves, or a snippet a third party has asked you to add. The JS injector module lets you add that code yourself, from the CiviPlus admin screens, without waiting for a code release.

This page is for administrators. It covers where to find the JS injector, how to add a rule, how to limit it to the pages you choose, and how to switch it off again if it does not do what you expected.

The JS injector is not available to CiviPlus users by default. As a first step, please contact your account manager or helpdesk agent and ask them to grant you the Administer JS injector permission.

Please read before you start. JavaScript runs in your visitors' browsers and can change how pages behave, so a mistake here can stop parts of your site working — for everyone, not just for you. Always target a single page first rather than the whole site, and check the result before widening it. If something does go wrong, Disable the rule and your site returns to normal straight away.

What can I do with the JS injector?

Add a snippet of JavaScript to your portal or website without a code release.
Choose exactly which pages the snippet runs on, using paths and wildcards.
Choose whether the code loads in the page header or footer.
Disable a snippet without deleting it, so you can undo a change instantly.

Before you start

You need the Administer JS injector permission. If you cannot see the screens below, this is almost certainly why — ask the helpdesk.
Have your JavaScript ready, and know which page or pages it should run on.
The JS injector is for behaviour. If you only want to change how something looks, use the CSS injector instead — it is the safer tool for styling.

Adding a JavaScript rule

The steps below use this example snippet, which adds a "Back to top" button to the bottom right of a page. You do not need to include <script> tags — the module adds those for you.

jQuery(document).ready(function ($) {
  $('<button type="button" id="back-to-top">Back to top</button>')
    .css({
      position: 'fixed', bottom: '24px', right: '24px', zIndex: 999,
      padding: '10px 18px', border: 0, borderRadius: '4px',
      background: '#0082f1', color: '#fff', cursor: 'pointer'
    })
    .on('click', function () {
      $('html, body').animate({ scrollTop: 0 }, 400);
    })
    .appendTo('body');
});

Go to Configuration > Development > JS injector — or straight to /admin/config/development/js-injector. You will see the rules that already exist on your site, with an Add button above them:

To add your rule:

Click Add.
Enter a Friendly name. This is the rule's unique ID, so use something you will recognise later, such as back_to_top_button. Only letters, numbers, spaces, underscores and dashes are allowed.
Enter a Description — a plain-English sentence saying what the rule does and why. This is what your colleagues will read when they find the rule in six months' time.
Paste your JavaScript into JS code.
Under Placement options, set Position of the javascipt to Footer. Footer is the safer default, because the page content has loaded by the time your code runs. (The spelling of that label is a quirk of the module, not a mistake on this page.)
Leave Preprocess JS and Inline JS unticked unless you have been told otherwise. Ticking Preprocess JS bundles your code in with the site's other JavaScript — if JavaScript aggregation is switched on in your site's performance settings — which means you have to clear the cache before any change appears.
Under Pages, choose The listed pages only and enter the path of the page you want the code on — one path per line, with no leading slash. For example, ssp/resources is the member Resources page. A * is a wildcard, so ssp/* matches every page whose path starts with ssp/ — if you want the portal home page itself as well, add ssp on its own line. <front> means your site's front page. These radio buttons are labelled Add tracking to specific pages — ignore the word "tracking", this setting simply controls where your JavaScript runs.
Click Save.

Always enter at least one path. If you leave the Pages box empty, your code runs on every page of your site — and that happens whichever radio button you choose. Selecting The listed pages only and leaving the box empty does not switch the rule off. To stop a rule running, use Disable.

A completed rule looks like this:

If your change does not appear straight away, flush the cache. Go to the Home icon at the far left of the black admin bar > Flush all caches > CSS and JavaScript, then reload your page.

Checking it worked

Open one of the pages you listed and look for your change. In the example above, the blue Back to top button appears in the bottom right corner of the member Resources page — and only there. Visit any other page and it is not present, because the rule is limited to the path you entered.

That's it. If the page looks wrong, or something on it has stopped working, go back to the rule list and Disable the rule — the page returns to how it was, and your code is kept for you to fix.

Editing, disabling and deleting a rule

Every rule in the list has an Edit button, with more options behind the small arrow next to it:

Edit — change the code, the pages or the placement. Save to apply your changes.
Disable — stop the rule running but keep it. This is the quickest way to undo a change, and the one to reach for if a rule has broken something. Disabled rules can be switched back on with Enable.
Delete — remove the rule and its code permanently.
Clone — copy an existing rule as the starting point for a new one, which saves retyping a snippet you want to run on a different page.
Export — show the rule as text you can copy, which is handy when you want to send a rule to the helpdesk for a second opinion.

Tips for writing rules that don't break your site

Start with one page. Get the rule working on a single path before widening it with a wildcard. A rule that runs everywhere fails everywhere.
One job per rule. Separate rules for separate changes are much easier to manage — you can disable the one that is misbehaving without losing the others.
Wrap your code so it waits for the page. The jQuery(document).ready(function ($) { … }); pattern in the example makes sure the page exists before your code touches it.
Use the CSS injector for anything visual. Colours, spacing and hiding elements are all styling jobs — see CSS injector. Keep the JS injector for behaviour.
Name rules so the next person understands them. back_to_top_button with a clear description beats test2.
If you are unsure, ask first. Send us the snippet through the helpdesk before you add it to a live site — particularly anything a third party has given you.

CSS injector — the companion module for changing how your site looks, rather than how it behaves.

CSS injector

JS injector