SP2010 AJAX part 6: Debugging jQuery/JavaScript

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)
6. Debugging jQuery/JavaScript (tip) - this article
7. Useful tools when building AJAX applications (tip)
8. Migrating existing applications to jQuery/AJAX

In this ‘quick tip’ article I want to quickly introduce how to debug AJAX-type applications, then point you to a more detailed ‘debugging JavaScript’ article which I really like. Although every developer is (should be) comfortable with debugging their server-side .Net code, the advent of JavaScript-heavy applications means that new debugging techniques must be learned. Debugging script is typically done outside Visual Studio and as I see it you have two main options:

• Use the IE Developer Tools (separate install required for IE7) and debug with IE
• Use Firefox and install the hugely popular Firebug add-in

In many respects, the JavaScript debugging experience is fairly similar – you first select which of the .js files linked to the page should be debugged, then find the place in the code to add the breakpoint. When the code runs, the debugger will stop and allow you to step through (F10)/step into (F11) and also see/amend local variables and see the call stack etc.

In IE: (click on the images to see clearer versions)

In Firefox:

I think it’s a popular view that Firebug offers a better debugging experience than the IE tools – as the image shows, Firefox allows me to hover over a variable and see it’s value, and also gives me easy access to the ‘this’ variable in jQuery – neither of which the IE tools do. It’s possible to do many of the advanced debugging scenarios such as conditional breakpoints, set watch variables, and even break automatically on a JavaScript error. The ‘Console’ tab is also useful for analyzing the response over the wire from a HTTP module or the SharePoint Client OM – something you need to do frequently. Furthermore, as I showed in article 4, if the response is JSON then Firebug helps out by formatting the response into an expandable/collapsible view:

I’m a huge fan of Firebug, and I highly recommend digging into the other areas of functionality such as the ‘Net’ tab for analysing page load times (something I discussed in my Checklist for Optimizing SharePoint Sites article a while back).

To delve more fully into JavaScript debugging, Elijah Manor’s How to Debug your JavaScript code article should be considered required reading.

Next time: Useful tools when building AJAX applications (tip)

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)