Referencing Javascript Files with SharePoint 2010 Custom Actions using SciptSrc
If you’re an avid reader of this blog, you are probably aware of the fact that using Javascript plus SharePoint is a very powerful combination. In SharePoint 2007 there were a couple of techniques you could use to make sure your Javascript files would be referenced by SharePoint pages:
-
Add the Script reference to the Master Page
-
Use a Delegate Control (e.g. the AdditionalPageHead)
-
Dynamically through code, e.g. in a Web Part
Although all those techniques work, and will still work in SharePoint 2010, they all have some limitations. The first technique requires you to build a custom Master Page, which may be a little overkill just to get a Javascript file referenced. Additionally, your custom Master Page is not used on Application Pages (unless you use the Superbranding trick). The second is my favorite one in SharePoint 2007, but the requirement is that the Master Page you’re using has the corresponding Delegate Control, and you need to have either a Server Control or Web User Control that generates HTML to reference the script. The third technique is nice if you only want to use the script when the Web Part is on the page, otherwise you’ll have to put the Web Part on every page where you’d like to reference the script.
SharePoint 2010 is adding another very interesting technique to this list; using the ScriptSrc attribute of the CustomAction element in a Feature. Check the following Feature Elements file:
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
ScriptSrc="JSDemo/jquery-1.4.2.js"
Location="ScriptLink"
Sequence="100"
>
</CustomAction>
</Elements>
The first important thing to notice is that the CustomAction element contains the ScrptSrc attribute that points in this example to the jQuery Javascript library. The jQuery library is added to the /_layouts folder in the SharePoint Root, in a folder called JSDemo (the /_layouts/ prefix is added automatically). By the way, adding files to the /_layouts folder is very easy in a SharePoint project in Visual Studio 2010, using a Mapped Folder. The second important attribute is the Location; it must be set to ScriptLink so the Javascript file is referenced in the head element of the page. Optionally you can specify a Sequence attribute to determine the in which order the script references will be added (if you have multiple). When Feature is activated, it results in the following HTML:
document.write('<script type="text/javascript" src="/_layouts/jsdemo/jquery-1.4.2.min.js?rev=EAku7lY97C3Kgrd9LPWhrg%3D%3D"></' + 'script>');
It’s important to mention that adding a reference to a script using this technique only works for scripts stored in the /_LAYOUTS folder in the SharePoint Root, so unfortunately it’s not possible to do something like this:
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
ScriptSrc="http://ajax.microsoft.com/ajax/jquery/jquery-1.4.2.min.js"
Location="ScriptLink"
Sequence="100"
>
</CustomAction>
</Elements>
Besides the ScriptSrc attribute, you can also use the ScriptBlock attribute to render a script inline. The following example shows an annoying message box every time a pages load:
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
ScriptSrc="JSDemo/jquery-1.4.2.min.js"
Location="ScriptLink"
Sequence="100"
>
</CustomAction>
<CustomAction
Location="ScriptLink"
ScriptBlock="$(document).ready(function() {
alert('jQuery is loaded!!'); });"
Sequence="101"
>
</CustomAction>
</Elements>
Unfortunately the ScriptSrc attribute doesn’t work very well in combination with Sandboxed Solutions: you can’t add files to the SharePoint Root using Sandboxed Solutions, and the ScriptSrc attribute requires the referenced script to be in the SharePoint Root’s /_layouts folder. I’m still figuring out a nice way to add for example the jQuery library to a SharePoint site, only using a Sandboxed Solution. If I’m successful, you’ll can definitely read more about it in a future post! :-)