Friday, May 7, 2010

How to set programmatically a value of a watermarked TextBox via JavaScript - Update

Some time ago I've published an article How to set programmatically a value of a watermarked TextBox via JavaScript about some specifics of working with a text input box decorated with a TextboxWatermark Ajax Extender control from the Ajax Control Toolkit library. The technique described in the article has proven useful for a number of developers so when the new release of the Ajax Control Toolkit has recently been announced I've decided to update the article to cover some of the braking changes in Ajax Control Toolkit components.

Ajax Control Toolkit changes

One of the most significant changes in the recent Ajax Control Toolkit release that affected everything is renaming namespaces and control names. Most of the JavaScript classes in the ACT has been moved into Sys.Extended.UI and some of them renamed.

Correspondingly the AjaxControlToolkitTextboxWrapper class that is crucial for the technique described in this article is now called Sys.Extended.UI.TextBoxWrapper and this is a breaking change. Most if its methods haven't been renamed and this is a good news however the new way of using the wrapper has been introduced.

Below are the code examples demonstrating how to write the code correctly with the new version of the ACT.

First we need to acquire an instance of the Sys.Extended.UI.TextBoxWrapper class for our textbox control and this is the newly introduced technique compared to the previous version of the ACT:
// get the instance of a textbox element
var textBox = $get(textBoxId);
// use the get_Wrapper static method of the TextBoxWrapper class to get the instance of the wrapper for the textbox
var wrapper = Sys.Extended.UI.TextBoxWrapper.get_Wrapper(textBox);

In the code above first I assume that the ACT is present so I don't have to check that Sys.Extended.UI namespace is defined. Secondly the code above is safe even if the textbox is not watermarked: the get_Wrapper static method will always return the instance of the TextBoxWrapper; the new instance will be created if the textbox is not watermarked.

Now we can set or get a value of the textbox using the instance of the TextBoxWrapper:
// get the textbox value
var oldValue = wrapper.get_Value();
// set the textbox value
wrapper.set_Value(newVlaue);

Conclusion

In a nutshell there are two major changes introduced in the new ACT release that affect the coding technique described here: the name of the textbox wrapper class has been changed; and now it's not required to check whether the textbox is watermarked to use the technique above.

Wednesday, May 5, 2010

Leveraging Visual Studio JavaScript IntelliSense. Part 1

One of the most useful features of the Visual Studio 2008 and Visual Studio 2010 is JavaScript IntelliSense that allows developers write JavaScript code faster, with fewer errors and reduce learning time of some JavaScript frameworks. Many developers already enjoy its power when code JavaScript with Microsoft ASP.NET Ajax framework and jQuery. However many developers are still not familiar with that tool and even less developers realize that it can also be used with their own code.

As convenient and powerful the JavaScript IntelliSense is as it is not intuitive to get started with mainly because of its lack of well-organized documentation and non-intuitive error diagnostics. Another obstacle is that it does not support its own XML code comments that makes it hard to use to the full extent without learning and memorizing first.

This article aims to provide with a quick reference of the most useful features of the JavaScript IntelliSense to help make it an every-day tool for the JavaScript developers.

In short words JavaScript IntelliSense provides with two main features:
  1. It enables documentation and syntax support while coding for the core JavaScript elements and third-party JavaScript libraries;
  2. It allows adding documentation and syntax support to the code being developed so other developers can use it.
In this post I cover the first feature.

Enable JavaScript IntelliSense for third party JavaScript libraries

The IntelliSense support for the core JavaScript syntax is enabled by default. In order to enable IntelliSense for third party code one needs to satisfy the following requirements:
  1. Reference a third party JavaScript file in your code, and
  2. Make sure the third party JavaScript includes Visual Studio XML code comments
The second requirement is in fact optional because JavaScript IntelliSense will work even without XML comments but will provide with less information so it actually pays off checking out before choosing a third-party JavaScript library whether it has a VS IntelliSense support. Many of the most popular JavaScript libraries such as ASP.NET Ajax, jQuery, Bing Maps, etc. do support VS IntelliSense.

Referencing another JavaScript library in your JavaScript code

Simply use a reference directive in your JavaScript code. There are a few flavors of that directive depending on the location of a third party JavaScript code. A reference directive supports file-based, assembly-based, service-based, or a page-based script references. Below are the examples illustrating those scenarios:


A -path-to portion above can be both a file path to a local or network location or a web URL to both intranet and Internet resources. In the latter case keep in mind that the Internet resource will be accessed every time Visual Studio opens a JavaScript file with a reference so it is better to cache it locally which is also much safer. In case of a service-based reference the actual URL Visual Studio has to access will be 'service-url/jsdebug' or 'service-url/js' based on the solution configuration therefore make sure that the project a service belongs to compiles without errors.

It is not necessary to reference an original JavaScript code itself (for example if it's hosted somewhere outside of your development environment) if there is a VSDOC file provided as it is with jQuery or Bing Maps libraries for example.

A VSDOC file is a JavaScript file that only includes objects definitions and functions signatures with XML comments without actual code and is a preferred way to add extensive documentation to a JavaScript library without modifying the original JavaScript code. In case there are no XML comments in the code nor VSDOC file is available simply reference an original JavaScript file and Visual Studio will parse it and provide you with the best possible IntelliSense help. If you use Microsoft ASP.NET Ajax framework add the following reference to the top of your JavaScript code:


You may have noticed that this is a reference to an embedded resource but without assembly name. Such a reference only works for so called well-known assemblies that are listed in a web.config file such as in this case a System.Web.Extensions. If you use a JavaScript library that comes in a form of a DLL containing multiple JavaScript you may consider listing it in a web.config file and save on assembly name in multiple reference directives.

IntelliSense Rules

The JavaScript IntelliSense behavior is determined by the following rules:
  1. Private class members defined inside a class constructor are not visible in IntelliSense. If you need to have IntelliSense support for private members define public getter (get_...) and/or setter (set_...) methods for them with XML comments
  2. Class methods with names beginning with underscore are considered private and not visible even if they have XML comments
  3. Public class methods can be defined in a class prototype or in a standalone code.
  4. If XML comments are not provided only a method name and a list of arguments are displayed.

IntelliSense Errors

If you don't see IntelliSense support for a JavaScript library even though you have added all the reference check out the Visual Studio Errors tab. If IntelliSense cannot load a referenced file it will display a message like 'Could not load ...' in the Errors tab. The most common reasons for IntelliSense not being able to a load a referenced file are:
  • File is not found at the location or location/file name is invalid. If the file is located on the Internet or a network share there may be a problem accessing those locations from your machine.
  • A referenced JavaScript file contains errors. If IntelliSense can not successfully parse the file it will not load it.
  • If a referenced JavaScript is an embedded resource from one of the solution's projects the project is not compiled for some reason and the DLL is not found.

This is all for the first part. In the next post I will explain how to use XML comments in your own JavaScript code to IntelliSense-enable it. If you find something missing or incorrect in this post or have suggestions what else to cover please write a comment and I will get back to you ASAP.

More to read