Adding script like jQuery to your pages

When working with the post of Andrew Connell I faced some challenges with implementing my solution. I wanted to add multiple scripts with dependencies to my pages. When creating one elements.xml containing all three script links the order of the <CustomAction Location=”X” ScriptScr=”Y” /> elements is important.

The following elements.xml is packaged in a feature.

<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction 
    Location="ScriptLink" 
    ScriptSrc="~site/_layouts/project_name/js/custom-1.0.0.js?rev=20110413" />
  <CustomAction 
    Location="ScriptLink" 
    ScriptSrc="~sitecollection/_layouts/project_name/js/ jquery_query-2_1_7.js?rev=20110413" />
  <CustomAction 
    Location="ScriptLink" 
    ScriptSrc="~site/_layouts/project_name/js/jquery-1.5.1.min.js?rev=20110413" />
</Elements>

This results in the following HTML in your pages.

document.write('<script type="text/javascript" src="/_layouts/project_name/js/jquery-1.5.1.min.js?rev=20110413"></' + 'script>');
document.write('<script type="text/javascript" src="/_layouts/project_name/js/jquery_query-2_1_7.js?rev=20110413"></' + 'script>');
document.write('<script type="text/javascript" src="/_layouts/project_name/js/custom-1.0.0.js?rev=20110413"></' + 'script>');

Important to know is the order in the elements.xml is the opposite sequence in the HTML. Meaning the script “jquery_query-2_1_7.js” is depending on “jquery-1.5.1.min.js” and needs to be the last item in the elements.xml.

In the script link I’m using “~site” and “~sitecollection” tokens to change the link according to the site or site collection where the user is located. This is important when creating a generic feature used on multiple sites.

By using the “?rev=20110413” at the end of your link you can force the browser to refresh its local cache. A (script) file is downloaded the first time accessing the page. As long as the link does not change the browser does not download the file. By changing the query string you can force a download of the script when changes are made. The actual value “20110413” is todays date, but can be your own versioning logic.

The example above also has a version number in the file name, this is another way of forcing a download. I simply wanted to illustrate the possibilities, you probably will use either query string or version number.

Lessons learned / best practices:

• Order in elements.xml for <CustomAction /> elements is of influence of the order of script links in the resulting HTML.
• Use “~site” and “~sitecollection” tokens to control the script link.
• Use “?rev=20110413” query string or version number in filename to force a download of the file.