SP2010 AJAX part 5 - Enable Intellisense for Client OM and jQuery

1. Boiling jQuery down to the essentials (technique)
2. Using the JavaScript Client OM to work with lists (technique)
3. Using jQuery AJAX with a HTTP handler (technique)
4. Returning JSON from a HTTP handler (technique)
5. Enable Intellisense for Client OM and jQuery (tip) - this article
6. Debugging jQuery/JavaScript (tip)
7. Useful tools when building AJAX applications (tip)
8. Migrating existing applications to jQuery/AJAX

This article marks a change in this series – whereas the previous four articles were detailed guides on key techniques, the next few are short and sweet tips which might be useful on the journey. Today we talk about Intellisense, specifically for JavaScript libraries a SharePoint developer may use such as jQuery or SharePoint 2010’s Client Object Model.

Although many developers put up without having Intellisense for such code (it’s not enabled by default), there’s no real reason not to enable it if you’re writing more than a couple of lines. Without it, you only get the less-than-useful default JavaScript Intellisense which looks like this:

Taking the Client OM as an example, here’s what proper Intellisense looks like when it’s enabled – that’s a long dropdown and trust me, you want it:

In terms of enabling it, there are a couple of variations depending on where you need the Intellisense, and whether we’re talking about jQuery or the Client OM. Let’s run through them.

Enabling Client OM Intellisense in a .js file

All you need for this is a couple of reference paths at the top of your .js file:

/// <reference path="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\MicrosoftAjax.js" />

/// <reference path="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\SP.debug.js" />

Sidenote: If you want Intellisense on other JS files, you’ll need to add corresponding references. For example, digging around finds a nice SP.XmlWriter class in SP.Core.js for building XML in JavaScript – you’ll get no Intellisense for this with the snippet above, but the appropriate reference to SP.Core.debug.js will fix that. I list which bits of the Client OM are in which JS file at the end of this article.

Enabling Client OM Intellisense in markup (.aspx/.ascx)

For a code in-front file (do people still call it that? :)), we need to add <script> tags as if we were adding a normal .js files to the page/control. Consider however, that SharePoint already takes care of ensuring the right JavaScript files are referenced on a page at runtime, and that by adding duplicate references we would cause problems. All that’s needed is an inline ASP.Net conditional statement which will be false at runtime (so that the contents aren’t processed), but which Visual Studio sees just fine at design-time (apologies for the color-coding here, the ASP.Net brackets would be bright yellow in Visual Studio):

<% if (false) { %>

<script type="text/javascript" src="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\MicrosoftAjax.js" ></script>

<script type="text/javascript" src="C:\Program Files\Common Files\Microsoft Shared\Web Server Extensions\14\TEMPLATE\LAYOUTS\SP.debug.js" ></script>

<% } %>

Enabling jQuery Intellisense in a .js file

Here, the process is slightly different - Visual Studio needs a special ‘vsdoc’ file which provides the jQuery documentation. This can be downloaded from the official jQuery site, look for the ‘Visual Studio’ link next to the actual jQuery release files – at the time of writing, the latest jQuery version with documentation is 1.4.1. In a JavaScript file we again need to use the reference tag, this time pointing to the vsdoc file (note by the way, that the path can be relative or absolute):

/// <reference path="jquery-1.4.1-vsdoc.js" />

Enabling jQuery Intellisense in markup (.aspx/.ascx)

You’re probably getting the idea by now, but actually there’s an extra consideration for this scenario. When a JavaScript file is referenced in markup, Visual Studio automatically looks for an associated vsdoc file in the same directory – if one is found, you’ll have Intellisense. So that’s great, all we need is a reference to our ‘real’ JS file (which we need for run-time anyway) – however, we’re unlikely to want to use an absolute path for that, meaning VS could have trouble resolving the location. In SharePoint-land for example, you’ll most likely want to refer to your JS file with a ‘LAYOUTS’ relative path such as ‘/_layouts/jquery-1.4.1.min.js’, but since the IIS website is unknown to VS there’s no Intellisense. To get the best of both worlds, I just combine the two references, like so:

<% if (false) { %>

<;script type="text/javascript" src="../jquery-1.4.1.min.js"></script>

<% } %>

<script type="text/javascript" src="/_layouts/jquery-1.4.1.min.js"></script>

Appendix - JavaScript Client OM files

Taken from http://msdn.microsoft.com/en-us/library/ee538253.aspx:

Namespace	ECMAScript File
CUI Namespace	CUI.js, SP.UI.Rte.js
CUI.Controls Namespace	CUI.js
CUI.Page Namespace	CUI.js, SP.UI.Rte.js
SP Namespace	SP.Core.js, SP.js, SP.Ribbon.js, SP.Runtime.js
SP.ListOperation Namespace	SP.Core.js
SP.Ribbon Namespace	SP.Ribbon.js
SP.Ribbon.PageState Namespace	SP.Ribbon.js
SP.UI Namespace	SP.Core.js, SP.js, SP.UI.Dialog.js
SP.Utilities Namespace	SP.Core.js, SP.js, SP.Exp.js
SP.WebParts Namespace	SP.js
SP.Workflow Namespace	SP.js

Next time: Debugging jQuery/JavaScript (tip)