In case you missed it: Microsoft released the second part of their support tools for jQuery in Visual Studio this week. The second part comes in the form of a hotfix for Visual Studio 2008 SP1 that provides built-in support for –vsdoc.js files to – when present – automatically provide Intellisense support in Javascript documents. In combination with the recently released jQuery Intellisense file that Microsoft released you can now very easily get jQuery Intellisense in Visual Studio.

Here’s what this now looks like when accessing jQuery elements in the page:

jqueryIntellisense[1]

Note that you get Intellisense all the way down the chain – ie. not just on the first element. Notice also that plug-ins (draggable in this case) shows up as well in the list of ‘attached’ jQuery wrapped set functions.

Just as useful is Intellisense on individual members:

jQueryIntellisense2

with all parameters and some fairly detailed information provided on methods, and their parameters although there are a few functions that have missing parameters (all the before/after/append/appendto/prepend/prependTo etc.).

Notice also that the jQuery parameter stored into an instance variable is also recognized as a jQuery instance and so Intellisense works on the win variable as well as an explicit $() function.

What you need to use jQuery Intellisense effectively

Here are all the things that you need to get the best jQuery support in the VS 2008 editor:

  • Visual Studio 2008 SP1
    SP1 provides a number of enhancements to the Javascript Intellisense engine in Visual Studio and is the basis on which all the other enhancements run on. These improvements include faster parsing and some built-in knowledge of a few common Javascript libraries including jQuery to find and provide at least basic Intellisense support.

  • jQuery Intellisense document file (jQuery-1.2.6-vsdoc.js)
    This .js file is an annotated version of the base jQuery.js that includes detailed Visual Studio style Intellisense information about each of jQuery’s functions and utilities. None of the code is changed – only comments have been added. This file isn’t meant to replace your original jQuery.js file, but rather to serve as a more complete Intellisense file during development. Not meant for production.

  • VS 2008 SP1 Hotfix for –vsdoc.js Intellisense (KB958502)
    This hotfix enables any file with –vsdoc.js extension to act as an Intellisense background file for any referenced .js file. So if you have a script src referencing jquery.js all you have to do is have the jquery-vsdoc.js in the same folder as jquery.js and Visual Studio will automatically find and use the –vsdoc file for Intellisense. This works for jQuery with the above mentioned files as well as your own files.

This is all very nice and it works great.

I’ve talked about Intellisense some time back and I basically did something similar to my copy of jquery.js by providing a few key functions with Intellisense markup. So then when referencing the .js file I’d get the same Intellisense. With this support provided in Visual Studio it’s now become a lot easier to provide documentation in an external file simply by having a –vsdoc.js file for the same file.

The way this works is that Visual Studio first looks for the –vsdoc.js file, then a debug.js file and finally for the file you actually specified in the source.

In Practice

This works in basic script includes in the <head> tag or inside of the document inside of ASPX pages:

<head runat="server">
    <title>jQuery 101</title>   
    <script src="scripts/jquery.js" type="text/javascript"></script>
</head>

in script manager code:

<asp:ScriptManager ID="ScriptManager" runat="server">
    <Services>
        <asp:ServiceReference Path="~/MsAjax/MsAjaxStockService.svc" />            
    </Services>
    <Scripts>
        <asp:ScriptReference Path="~/scripts/jquery.js" />
    </Scripts>
</asp:ScriptManager>

or in script source files:

/// <reference path="~/scripts/jquery.js" />
/// <reference path="~/scripts/ww.jquery.js" />

Note that I prefer NOT to use the version number with my jQuery.js file to avoid later update renaming issues so my Intellisense file is actually jquery-vsdoc.js. Match whatever your main file name is version nunmber or not. Here’s what this looks like in a project in Visual Studio for me:

jqueryIntellisense

Note that I also have a jquery.min-vsdoc.js file in case I decide to embed the minimized version. Visual Studio is not checking for .min.js files and mapping them to the plain –vsdoc.js file – yet. So the following also works, but only if jquery.min-vsdoc.js is provided.

<head runat="server">
    <title>jQuery 101</title>   
    <script src="scripts/jquery.min.js" type="text/javascript"></script>
</head>

I spoke with Jeff King last week at PDC and there’s a chance that support for .min.js files might be added in the future natively. But even having the extra file should be no big deal because they are not used at runtime anyway so they don’t need to be deployed.

The Intellisense file and the hotfix in combination are a welcome addition to Visual Studio – it makes working with jQuery inside of the VS Javascript editor a lot easier because the documentation provided through the Intellisense interface is pretty rich and helpful in many situations.

Check it out if you haven’t already.

The Release/Debug Problem for Javascript

Although jQuery is specifically targeted here – this mechanism works with any .js file, so if you want to create Intellisense script for your own javascript files you can also store them externally. The downside is that maintaining comments in an external javascript code file is pretty much a maintenance nightmare – Intellisense currently needs to have a running Javascript file in order to interpret the comments. A better solution for this is eventually needed or else some built in tools that can strip comments automatically.

I’m doing the latter now through a custom script manager that minimizes and zips output, but really this should just not be necessary. ScriptManager does something similar but even it requires both debug and release scripts. Either way these  approraches work well only if you use resources or otherwise have ASP.NET serve the scripts rather than letting IIS optimize and do it. It’d be really nice if IIS natively could somehow participate in this process and provide minimization. I know I can do this with some ASP.NET code in a module myself, but IIS is already extremely optimized for the compression scenarios where it builds temporary files that are served with compressed data. This is something that ultimately would be nice to have native support for so developers can set a switch and not have to think about whether you’re working with release or ‘debug’ versions of files.