​Adding jQuery to Your SharePoint Site

Looking to add some fancy functionality to your SharePoint site with jQuery? Many sites are using jQuery to take advantage of its robust functionality and features, and SharePoint sites are no exception. Calling in a script into SharePoint is simple enough - there are numerous ways of achieving it (which we’ll cover in a bit). But what is the best way to accomplish getting the jQuery library into your SharePoint site so you can start adding all kinds of coolness to your branding?

Well, there are a few options. Probably the easiest and most widely used method is by adding it to your master page. This ensures that no matter where you are in your site, you can take advantage of jQuery without worrying if it’s loaded or not. The only real disadvantage to using this method is if you’re only planning on utilizing jQuery in one or two specific places. In that case you might be better off loading jQuery only when it’s needed rather than on every page load.

Adding a jQuery reference can be accomplished by using a specific SharePoint tag. Although you can technically call in the jQuery library using a standard <script> tag, there is a possibility of running into issues if your custom branding is deployed on a non-root site collection. Because of the way SharePoint builds URLs of non-root site collections with managed paths, a standard <script> tag doesn’t always work, as SharePoint often can’t find the correct path to the content if you’re pulling in the jQuery library locally. If you’re loading from a CDN with an absolute URL you probably won’t run into issues. However, if you like the idea of having the jQuery load locally, you’ll probably want to use a special SharePoint script tag. (By the way, it’s worth pointing out that this script tag isn’t limited to jQuery. Any custom script can be loaded this way.)

This is done by using a <SharePoint:ScriptLink> tag. Once you upload your version of jQuery to your master page gallery, you’ll reference it as follows, within the <head> section of the masterpage, near the closing </head> tag:

<SharePoint:ScriptLink runat="server" name="~SiteCollection/_catalogs/masterpage/CustomBranding/jQuery-1.11.2.min.js" language="javscript" />

Replace “/CustomBranding/jQuery-1.11.2.min.js” with the name of your folder (and script) within the master page gallery (if necessary). You could also use a URL for loading jQuery from a CDN as well.

So, what makes this <SharePoint:ScriptLink> tag so special?  When the SharePoint server renders the master page and content page as HTML to send to the browser, it will construct a normal <script> link reference.  Because the special <SharePoint:ScriptLink> tag uses the ~SiteCollection reference at the beginning of the name property, SharePoint can build the reference to the script using the current site collection. If you used a standard <script> tag, your refrence would likely be broken upon loading the custom branding up in a non-root site collection.

Loading jQuery on a Page Layout

What if you don’t need jQuery for your entire site? Perhaps you’ve just made a custom page layout that’s going to use some of the fancy jQuery features and only want to load jQuery when pages using that particular layout are rendered. Well, in this case you’d put a reference to the jQuery library in your page layout. Unfortunately the <SharePoint:ScriptLink> tag is unsupported in page layouts, so you’ll need to use a standard <script> tag instead. If your site won’t be using multiple site collections, a <script> tag isn’t an issue. Otherwise, you may consider deploying your jQuery file to the 15 hive on the server, or using a CDN, or referencing the jQuery using an absolute URL from a designated location on the SharePoint site.

Page layouts can use a content placeholder called the Additional Page Head in order to be able to add scripts or styles to the <head> section of the fully rendered page. Custom page layouts created in SharePoint Designer don’t have this placeholder by default, but you can add it easily. On your custom page layout, simply add the following placeholder:

<asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">

Within the placeholder tag you just added, simply reference your script. It will look like this:

<asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" runat="server">
   <script src="/_catalogs/masterpage/test1/jquery-1.11.2.min.js" type="text/javascript"></script>

Now you can create your page layout as you normally would, and use additional jQuery goodness for whatever you need. Any page created from that page layout will have the jQuery library loaded, but the rest of the site will not, saving a little on the load time since you are only calling in the library on a few specific pages. This can be useful particularly on a highly stylized home page, where you might have a jQuery-based image or news rotator and not want the overhead of loading jQuery everywhere else in the site when only the homepage will utilize it.

Using jQuery on a Single Page

But what if you find yourself only needing jQuery (or any other script for that matter) on just one page? Your best bet would be to use either the Script Editor web part or Content Editor web part. Both methods work basically the same way, but the Script Editor saves you a few clicks when getting the job done.  

To use the Script Editor, you’ll simply put your page in edit mode and click the Insert tab in the ribbon, then click the Embed Code button. Type the reference to your script:

<script src="/_catalogs/masterpage/test1/jquery-1.11.2.min.js" type="text/javascript"></script>

And click Insert. That’s all there is to it. (Obviously you could use a CDN or absolute URL here, so adjust your URL as appropriate.)

The Content Editor Web Part has a few more steps involved, but the outcome is still the same.  With the page in edit mode, click the Insert tab in the ribbon, then click the Web Part button. In the categories section of the Add a Web Part toolpane, select Media and Content, then select the Content Editor web part. Click the Add button. Once the web part is on the page, click the link within the web part to add content. Finally, in the Format Text tab in the ribbon, click the Edit Source button and type your script reference and click OK.  Ultimately it’s a lot more work and the CEWP can be notorious for adding additional HTML after you click the OK button, so if you have the option it’s best to stick with the Script Editor. 

Now that you’ve added a reference to the jQuery library, you can continue adding additional scripts to either web part and create a very nice looking page.

Although this article mainly discussed jQuery, the same methods outlined here would also apply to any other custom scripts you are loading within your site. As a general rule of thumb, loading scripts on the master page ensures that the script is available everywhere in the site, while narrowing the focus down to a page layout or a single page in the site saves on overhead if you don’t need a particular script to load with every single other page in your site.  

-Ryan Keller

Powered by SharePoint 2013 © 2019 Rackspace, US Inc.