Left Menu Right Menu
March 17, 2016

Best Practices for Implementing Javascript in Primo

JavaScript is a programming language that can be used to make changes to a website without changing its actual HTML.  It can also add dynamic content and additional functionality to a website, changing what appears on the page based on the user’s selections or actions. JQuery is a JavaScript library that simplifies JavaScript considerably, requiring fewer lines of code to execute common functionality.

This guide explains how to use JavaScript (and JQuery) to make changes to Primo’s front end.  Although most Primo Toolkit elements use JQuery, for simplicity’s sake this guide will refer to both JavaScript and JQuery scripts as “JavaScript.”

Created by: Stewart Baker, Western Oregon University

System components: PBO

Skill set requirements: Javascript

Accessibility: While JavaScript is not inaccessible per se, some implementations of it can be inaccessible.  Refer to the “Accessibility” section of each Primo Toolkit element’s documentation to determine whether or not it has detrimental effects on accessibility.  For more about JavaScript and accessibility in general, you can read WebAIM’s article on Accessible JavaScript.

Browser support: Refer to the “Browser Support” section of each Primo Toolkit element’s documentation.  JavaScript is generally compatible across browsers, but some implementations may work differently in different browsers.  You can see information on which browsers are actively supported by JQuery here.

Mobile support: Refer to the “Mobile Support” section of each Primo Toolkit element’s documentation.

Implementation steps: 

What JavaScript can do in Primo
In Primo, JavaScript is useful for adding functionality that is not provided by the out-of-the-box environment.  Examples from the Primo Toolkit include [[adding a link that directs users to Worldcat after a failed search]], [[turning the topic facets into a word-cloud]], and [[displaying Boolean operators between selected facets]].

When NOT to use JavaScript
Generally speaking, JavaScript should not be used if there is a less resource-intensive way of making the change you want.  Too much JavaScript can slow down page load times if it is processed while the page is still loading, especially if the script is stored in an external file.  

For example, although you could use JavaScript to change the font color of links to red instead of blue, this is a change that could be accomplished much more easily with CSS instead.

Some parts of the Primo experience cannot be modified with Javascript. Examples of this are the contents of the View It and Get It tabs, because these are included with iframes from Alma and cannot be modified by Primo scripts.

Including the JQuery library
Many of the elements in the Primo Toolkit are written in JQuery, a library which simplifies JavaScript.  Before these elements can be used, you must first include the JQuery library or they will not work.

There are several different versions of the JQuery library, all of which which can be called directly from the web page you are adding JavaScript to.  The main differences in the versions are differences in compression and differences in version number.

  • Compression - JQuery comes in a compressed and uncompressed version.  The uncompressed version is recommended for use in testing and debugging code, while the compressed version is better for production environments—that is, for websites that are able to be accessed by members of the general public.  For pre-built Primo Toolkit elements, you will usually want the compressed JQuery, as it reduces load time.  If you are building your own JQuery scripts, however, you may wish to use the uncompressed version for testing the code.
  • There are two main “lines” of JQuery: 1.x and 2.x.  The only substantial difference between the lines is that 2.x does not support versions of Internet Explorer prior to IE 9.  Because of this, the official JQuery documentation suggests using JQuery 1.x “unless you are certain no IE 6/7/8 users are visiting the site.”
Below is a table showing these differences.

Version Environment Browser support
 JQuery 1.x (compressed)  Production  All browsers
 JQuery 1.x (uncompressed)  Testing  All browsers
 JQuery 2.x (compressed)  Production  IE 6/7/8 not supported
 JQuery 2.x (uncompressed)  Testing  IE 6/7/8 not supported

If none of this makes sense and you just want to know which version to use in your live Primo, the safest bet is JQuery 1.x (compressed).  Some Primo Toolkit elements may also specify which version of JQuery to use.

There are several ways to include the JQuery library in a page.  The simplest is to load it from a CDN, a kind of remote code repository.  The official JQuery documentation contains links to several CDNs, including one hosted by the JQuery.com site itself.

To include JQuery, simply get the URL to the CDN for the version you wish to use and load it into your page before you include any JavaScript that uses JQuery.  In Primo, both the JQuery reference and any JavaScript code you include must be placed in the footer file or header file loaded via the PBO File Uploader utility.

Code Snippets you can copy and paste for each version of JQuery are included below.

JQuery 1.x (compressed): <script src="//code.jquery.com/jquery-1.11.3.min.js"></script>

JQuery 1.x (uncompressed): <script src="//code.jquery.com/jquery-1.11.3.js"></script>

JQuery 2.x (compressed): <script src="//code.jquery.com/jquery-2.1.4.min.js"></script>

JQuery 2.x (uncompressed): <script src="//code.jquery.com/jquery-2.1.4.js"></script>

Once you have included the JQuery library, you can use JQuery in any subsequent JavaScript.  You do not need to load the library more than once on a page.

Where to put your JavaScript

JavaScript can be put in several places in Primo, including the Header and Footer files and in a separately-uploaded JavaScript file.  For an explanation of how to edit the Primo footer and header files in Primo Back Office, see the Toolkit guide to [[Creating, loading, and maintaining mashup CSS, Primo CSS, and static HTML files]].

  • Option 1: The Footer
    JavaScript can be placed in the Primo Footer file, which can be accessed through Primo Back Office’s “file uploader” utility.  Since the footer file is loaded after the rest of the page loads, JavaScript placed here will generally not execute until after all page content has loaded.  This ensures that the user still receives the information on the page in a timely manner. 
  • Option 2: The Header
    JavaScript can also be placed in the header file.  This is useful if you need your JavaScript to execute before the page content (e.g. in the case of a redirect to another page).  Note that JavaScript in the header can have its execution delayed until after page load.  See “On Page Load” below for instructions.
  • Option 3: In a Separate File
    Long scripts can clutter up your source code and make modifications more confusing.  One way to get around this problem is to store your JavaScript in a separate file.
You can host these files on your own web server if you have access to it, or  you can upload a JavaScript file to a specific view using the file uploader tool in Primo Back Office.

Once you have uploaded your JavaScript, simply call it by placing the following line of code in the header or footer file of the view where you wish it to execute:

<script src="your.url/scriptname.js"></script>

If you have placed the JavaScript in the file uploader tool, the URL you should use is:

<script src="../uploaded_files/VID/scriptname.js"></script>

where VID is the name your Primo view and scriptname.js is the name of your script.


Related customizations

Back to Blog
Comments (0)
Reply To Article