• Comment as much as needed, but no more: comment what you consider needed, but don’t tell others your life story. Too many comments may make some other developer get distracted from the actual code.
• Javascript is used to define the behaviour, not the look & feel: even though there’s the possibility to set the appearance of your application through JavaScript, you should leave that for CSS. Always follow the “separation of concerns” mantra. A change in the icons or the color of borders shouldn’t require dealing with JavaScript code.
• Modularize: keep your code modularized and specialized. Make sure to write smaller, generic helper functions that fulfill one specific task, rather than catch-all methods.
• Allow for configuration and translation: everything that is likely to change in your code should not be scattered throughout the code, for example, labels, CSS classes and IDs. By putting these into a configuration object and making it public, we make maintenance very easy and allow for customization.
• Access the DOM as little as possible: accessing the DOM in browsers is an expensive thing to do. The DOM is a very complex API and rendering in browsers can take up a lot of time. To make sure that your code is fast and doesn’t slow down the browser to a halt try to keep DOM access to a bare minimum.
• Build on the shoulders of giants: JavaScript libraries are specifically built to make browsers behave as you would expect by plugging browser holes. Therefore, if you want to write code that works without keeping the maintenance overhead of supporting current browsers and those to come, start with a good library.
• Development code is not live code: live code is done for machines, development code is done for humans. Make your code as readable and understandable as possible. Then, before deploying your web application, collate, minify and optimize your code in a build process.

If you follow all these recommendations, you can be sure you’ll have produced a high quality code that will be easy to maintain.

• Always use ‘var’: although it is not compulsory, the use of the ‘var’ keyword is always recommended. By using it, your code will execute faster, and you will avoid some potential problems.
• Feature-detect rather than browser-detect: before using any advanced feature that an older browser may not support, check to see if the function or property exists first, instead of writing code to detect browser versions.
• Avoid ‘eval’: the eval() function in JavaScript allows a programmer to run arbitrary code at run-time, by interpreting a string as if it was code. If it exists in your page, there is almost always a more correct way to accomplish what you are doing. “Eval is evil.” Don’t use it unless you are an experienced developer and know that your case is an exception.
• Use unobstrusive JavaScript: now, this is an important one: HTML and JavaScript code should not be mixed together. You should always follow the “separation of concerns” mantra: HTML defines the structure and content of a web page, and JavaScript defines the behavior. Therefore, do not use inline event handlers. Attach your event-handling code by JavaScript. This way, you’ll improve readability and maintainability.
• Avoid cluttering the global namespace: global variables and functions are rarely required. Using globals may cause naming conflicts between JavaScript source files and cause code to break. You should always use object oriented programming and write all your code in classes when writing JavaScript code.
• Use JSON: when storing data structures as plain text or sending/retrieving data structures via Ajax, use JSON instead of XML when possible. JSON (JavaScript Object Notation) is a more compact and efficient data format, and is language-neutral.
• Make you code understandable: choose easy to understand and short names for variables and functions. Think of your code as a story – a story that should be easy to read and understand, the names you choose shouldn’t make it more complicated.

In my next post I’ll discuss some more recommendations. Stay tuned!

Related posts:

1. JavaScript best practices II
2. Object Oriented JavaScript III: some tips
3. Object Oriented JavaScript I: the basics
4. Javascript frameworks overview
5. Object Oriented JavaScript II: the pattern

The curious case of the mutating scope

Ok, now imagine we have some fancy widget in our class and we want to interact with it. There are many widgets which redefine the this keyword to its instance instead of ours. For this case, we might want to be able to access our instance instead of the widget instance. We’ll need to redefine the scope in which the function is being executed. To do so, we can use the following function:

// Creates a new function and returns a reference. This new function has its scope set to 'newScope'
this.setScope = function (originalFn, newScope) {
   return function () { return originalFn.apply(newScope, arguments); };
};

We could just use the apply method on our original function, but I prefer this way since its more comfortable to work with parameters like this.

Be careful when using this, since this is a double-edged sword. By accessing our class scope we have all our data available. But we won’t have the widget’s scope available anymore. So make sure you don’t need to access the widget’s scope before changing the scope of the event handler.

Accessing your instance from the global scope

When you do something like

var Peter = new Person();

you’re creating a new instance of the class Person. And the variable Peter is just a pointer to the instance, not the instance itself. Peter is the way we have to access that instance from global scope: it’s just a pointer. But we have no way to know the name the pointer to the instance was given from within the instance itself. This means, we have no way to know that Peter is the way we have to access the instance from global scope.

So, if we’re ever in the need of calling a method from a global scope, we’ll need to keep an array of instances ourselves. We could be doing something like:

var Person2 = function (name, surname, age) {
	var _name, _surname, _age;

	this.showData = function () {
		var str = new String();
		str = "Name: " + _name + " - ";
		str += "Surname: " + _surname + " - ";
		str += "Age: " + _age;
		alert(str);
	};	

	// ---- Constructor -----------------------------------------------
	_name = (typeof name === "undefined" ? "John" : name);
	_surname = (typeof surname === "undefined" ? "Smith" : surname);
	_age = (typeof age === "undefined" ? 20 : age);

	// Store pointers to all instances of this class, so we can access their
	// context from global code
	var _instanceIndex = Person2._instances.length;
	Person2._instances[_instanceIndex] = this;
};
Person2._instances = new Array();

So now we have an array containing all the different instances of the object:

var Peter = new Person2();  // Equivalent to Person2._instances[0]
var John = new Person2('John', 'Smith');  // Equivalent to Person2._instances[1]

This is useful if you’re declaring some event handlers in the HTML code. Something like:

<div id="myDiv" onclick="Person2._instances[1].showData();">Hello world!</div>

CAUTION!! This is not something I would recommend. This is not a good practice in JavaScript. Behaviour should be separated from the content, and with this you’re just mixing both together.

I’m just showing this as a possibility, in case you’re in the need of something similar. But be aware that by using onclick event handlers like this, you’re making your code less readable and less maintainable. Be careful!

Well, now you have to start practicing all these concepts you’ve just read. Start doing some JavaScript programming. The more you do it, the better programmer you’ll become.

Related posts:

1. Object Oriented JavaScript II: the pattern
2. Object Oriented JavaScript I: the basics
3. JavaScript best practices I

The first feature we need to implement is private and public members. Using closures, this is easy to achieve:

var Person = function () {
	// Private elements
	var _name, _surname, _age;

	// Public elements
	this.getName = function () {
		return _name;
	};
	this.setName = function (newName) {
		_name = newName;
	};
	this.getSurname = function () {
		return _surname;
	};
	this.setSurname = function (newSurname) {
		_surname = newSurname;
	};
	this.getAge = function () {
		return _age;
	};
	this.setAge = function (newAge) {
		_age = newAge;
	};
};

By declaring functions inside the outer function Person, we’re creating a closure which makes the elements _name, _surname and _age inaccessible by members which are not inside the Person function. On the contrary, all elements declared with the this keyword will be accessible from outside of the Person function.

If we want to set some code to be executed when this class is instantiated, we can do so anywhere inside the Person function:

var Person = function (name, surname, age) {
	// Private elements
	var _name, _surname, _age;

	// Public elements
	this.getName = function () {
		return _name;
	};
	this.setName = function (newName) {
		_name = newName;
	};
	this.getSurname = function () {
		return _surname;
	};
	this.setSurname = function (newSurname) {
		_surname = newSurname;
	};
	this.getAge = function () {
		return _age;
	};
	this.setAge = function (newAge) {
		_age = newAge;
	};

	// Default constructor
	this.setName(typeof name === "undefined" ? "John" : name);
	this.setSurname(typeof surname === "undefined" ? "Smith" : surname);
	this.setAge(typeof age === "undefined" ? 20 : age);
};

This way, we’re creating constructors.  If the name, surname and age variables are given a value when this class is instantiated, that value will be assigned to the private properties; if not, then default values will be used. So we can now check how what we’ve written behaves so far. I’ll use the Firebug console to check what our JavaScript does:

>>> var John = new Person()
>>> John.getName()
"John"
>>> John.getSurname()
"Smith"
>>> John.getAge()
20
>>> var Peter = new Person("Peter", "Jackson")
>>> Peter.getName()
"Peter"
>>> Peter.getSurname()
"Jackson"
>>> Peter.getAge()
20

Notice how private properties get the the default values if we instantiate the class with no values for the constructor.

So we now have private and public elements, the most basic features of object oriented techniques. But there’s actually different kinds of public properties. Depending on how you declare them, some public elements will actually behave slightly different:

var Person = function (name, surname, age) {
	// ---- Private members ------------------------
	var _name, _surname, _age;

	// ---- Public, privileged members ------------------------
	// Privileged members are exposed through the API and have access to
	// private members

	this.getName = function () {
		return _name;
	};
	this.setName = function (newName) {
		_name = newName;
	};
	this.getSurname = function () {
		return _surname;
	};
	this.setSurname = function (newSurname) {
		_surname = newSurname;
	};
	this.getAge = function () {
		return _age;
	};
	this.setAge = function (newAge) {
		_age = newAge;
	};

	// ---- Default constructor ------------------------
	this.setName(typeof name === "undefined" ? "John" : name);
	this.setSurname(typeof surname === "undefined" ? "Smith" : surname);
	this.setAge(typeof age === "undefined" ? 20 : age);
};

// ---- Public, non-privileged members ------------------------
// All elements included in the prototype are exposed through the API and
// do not have access to private members.
// All instances of this class will have these members available.
Person.prototype.getPersonData = function () {
	var str = new String();
	str = "Name: " + this.getName() + " - ";
	str += "Surname: " + this.getSurname() + " - ";
	str += "Age: " + this.getAge();
	return str;
};

// ---- Public, static member for current instance ------------------------
// Members defined like this are related to the object itself, not to instances.
// These members have no means of accessing instance or private data.  They can't
// access instance data because they don't have the "this" operator set to any
// particular instance.
// These members relate to the instance in which they are defined. Since we're defining
// them for the class definition, instances of this class will not have these members
// available.
Person.AreEqual = function (p1, p2) {
	return p1.getName() === p2.getName() &&
			p1.getSurname() === p2.getSurname() &&
			p1.getAge() === p2.getAge();
};

Notice how depending on how you declare your public members, they will have different access level to the information within your instance:

• Members declared inside the closure with the this keyword are privileged: they have access to private members.
• Members declared with the prototype keyword are non-privileged: they do not have access to private members. These members will be available in all instances of this class.
• Members declared like “class name” + “.” + “member name” are public static members for the current instance. They don’t have the “this” operator available, and other instances of this class will not have these members available.

So, here’s how our class behaves:

>>> var John = new Person()
>>> John.getPersonData()
"Name: John - Surname: Smith - Age: 20"
>>> Person.AreEqual(new Person(), John)
true
>>> var Peter = new Person("Peter")
>>> Person.AreEqual(John, Peter)
false
>>> John.AreEqual(John, Peter)
TypeError: John.AreEqual is not a function { message="John.AreEqual is not a function", more...}

Notice how the AreEqual method is only available for the object Person, not for its instances.

Ok, now we’ve covered public and private elements, constructors and the different access levels public members may have. We’ve gone through all we need to write object oriented code. But keep on reading to see some tips about OO code in JavaScript.

Stay tuned for my next post!

Related posts:

1. Object Oriented JavaScript III: some tips
2. Object Oriented JavaScript I: the basics

Until AJAX techniques emerged, JavaScript was not seen as an application development platform. It was treated merely as a scripting language to implement minimal dynamic web page behavior. Up till not too long ago, all the JavaScript I needed to write was just a few lines of code to make some validations, a few animations and some AJAX calls… but this has definitely changed today. The number of JavaScript lines I am writing nowadays for the web apps I’m developing are counted in the thousands. Heck, the last module I developed at work contained more than 12000 lines of JavaScript code! This means that I can no longer just write code without order. I need to have some logic behind the process of writing code. And this is when object oriented techniques come into play.

Much has been written about JavaScript and how to use its object oriented features. The thing is, although JavaScript has some object oriented (OO) features, how to use them is not a trivial matter. JavaScript (JS) is quite different from other OO languages like C# or Java, so if you’re coming from these types of languages, after some while you’ll realize that JS behaves differently in a few ways. It’s not that it’s better or worse, it’s just different. And if you ever want to get to master JS, you’ll need to be aware of them.

There’s a bunch of different approaches on how to use OO features and techniques. The most widely spread methodology for writing classes is the module pattern, made popular by the YUI JavaScript library.

I’ve spent some time digging through the internet trying to find what the best pattern for OO JavaScript is. Unfortunately, there doesn’t seem to be any kind of standard, and people just implement whatever better suits their needs. So, looking around, I came up with my own pattern for writing classes and object oriented JavaScript. It is somehow derived from stuff that I’ve seen throughout the web, and with some additional features I consider useful.

But before explaining this pattern, you first need to understand some basics about JavaScript:

JavaScript has loose typing. At any given time, the type of a variable is the type of whatever is assigned to it. I could perfectly do something like:

var myVariable = 34;
myVariable = "Hi there!";

And no error would be thrown.

JavaScript has anonymous functions. To show this concept I’ll use the function setTimeout, which is used for executing some code after some specified amount of time:

function sayHi() {
   alert("Hi!");
};
setTimeout(sayHi, 1000);

This shows a message with the text “Hi!” after 1000 ms. The same thing can be achieved by an anonymous function:

setTimeout(function () { alert("Hi!"); }, 1000);

JavaScript has function pointers. The previous function can be expressed as:

var sayHi = function () {
   alert("Hi!");
};

And it would still be called in the same way, sayHi().

JavaScript has closures. Now, this is a little bit tricky. Closures are something which is not fully understood by all programmers. But they really aren’t all that complicated. Let’s take a look at them:

A “closure” is an expression (usually a function) that has variables together inside an environment that binds those variables. In other languages, when a function is called, a new stack frame is created and then destroyed when the function completes. So, if a function is called 3 times, 3 different stack frames are created with 3 different set of local variables. JavaScript behaves differently. In JS, it is as if the stack frame for the closure was not deallocated from memory when the function returns. It’s as if it was given a static piece of memory and always stayed there. So if you call the closure 3 times, the same set of local variables are accessed, having the same value. That means, having the last value they had the last time that closure was called.

An example to clarify things a little. Take a look at this piece of code:

function initGlobalVariables {
   var someNumber = 123;
   var someString = "Hello World!";
   var someFunction = function () { alert(someString); };
};

By writing a function inside some other function, we’re creating a closure. The scope of the inner function is the outer function: this means that the function assigned to someFunction can access the variables someNumber and someString. And every time we call the function assigned to someFunction, the variables will not be created and destroyed: they will remain there with the last value they had.

Just remember these key facts for closures:

• A closure is the local variables for a function – kept alive after the function has returned.
• Whenever you use a function inside another function, a closure is used.
• Whenever you call the outer function, a new closure is created.
• Whenever you call an inner function of the closure, no new closure is created: you access the existing closure with the last values they had the last time you exited an inner function of the closure.

The this keyword refers to the closure within it is located. The value of the this keyword refers to the scope of the function. That is, the closure within it exists.

Ok, with this we’ve covered the very basics of JavaScript we need to understand object oriented techniques. In my next post I’ll start covering the pattern, so stay tuned!

Related posts:

1. Object Oriented JavaScript II: the pattern
2. Object Oriented JavaScript III: some tips
3. JavaScript best practices I
4. Persistance layer: object-relational mapping tools
5. JavaScript best practices II

I’ve developed a very basic Web Socket server implementation in C# just as a proof of concept. It handles the most basic operations you would expect from a server: start a new connection, disconnect, and send and receive data. Besides, I’ve developed the client part as well using regular ASP.NET. Actually it’s just plain HTML and JavaScript being served from an ASP.NET server – this example doesn’t use any fancy runat=server controls or anything of the like. The functionality is achieved with very simple and easy to understand JavaScript.

So what does this example do? It provides two projects: a Web Socket server and a Web Socket client. The server is a windows console application that once executed just sits there waiting for a connection request. When a client connects, the server sends its date and time to the client every 10 seconds. The client is a web page with some controls to connect/disconnect and to send data to the server, as well as a log window to see what’s going on. Take a look at the example at the bottom of the page.

Here’s a description of the public members of the Web Socket Server:

// Possible status of the server
enum ServerStatusLevel { Off, WaitingConnection, ConnectionEstablished };
// Constructor of the server with default values
WebSocketServer();
// Constructor of the server with the specified values
WebSocketServer (int serverPort, string serverLocation, string connectionOrigin);
// Close the server and release all resources
void Dispose();
// Start the server and make it listen for connection requests
void StartServer();
// Send data to the connected client
void Send (string message);
// Whether events should be logged or not
bool LogEvents;
// Origin of the connection
string ConnectionOrigin;
// Location of the server
string ServerLocation;
// Port of the server
int ServerPort;
// Current status of the server
ServerStatusLevel Status;
// Fired when data is received from the client
event DataReceivedEventHandler DataReceived;
// Fired when client is disconnected
event DisconnectedEventHandler Disconnected;
// Fired when a new connection is established
event NewConnectionEventHandler NewConnection;

Note how I provide two constructors for the Web Socket Server class: one with default parameters (if you want to keep it as simple as possible), and another one to specify the values you want. Anyways, you can still change them after creating the new instance, as the properties are public. You can also specify whether you want the server to log out the events to the console with the LogEvents property.

In order to get the data being sent from the client, you must attach your own function to the DataReceived event, which will then receive the message as a parameter.

So here’s how you would use this Web Socket Server:

public void Test()
{
    WebSocketServer WSServer = new WebSocketServer();  // Default values
    WSServer.NewConnection += new NewConnectionEventHandler(WSServer_NewConnection);
    WSServer.Disconnected += new DisconnectedEventHandler(WSServer_Disconnected);
    WSServer.DataReceived += new DataReceivedEventHandler(WSServer_DataReceived);
    WSServer.StartServer();
}

void WSServer_DataReceived(string message, EventArgs e)
{
    Console.WriteLine("Data received from the client: " + message);
}

void WSServer_Disconnected(EventArgs e)
{
    Console.WriteLine("Server disconnected");
}

void WSServer_NewConnection(EventArgs e)
{
    Console.WriteLine("New connection established");
    WSServer.Send("Hello new client! I hope you enjoy your visit!");
}

It’s a very simple Web Socket server, so it’s very easy to use. You shouldn’t have much problem understanding it.

Go ahead and download the Visual Studio solution and give it a try!

UPDATE (October 12th, 2010):

The Web Socket protocol is not closed yet, so it is being constantly updated. This means that previous Web Socket server implementations might stop working after an update has been made to the API. The original version of the code I released here complied with version 75 of the Web Socket draft. The current version is 76, so I updated my code and released a second project.

No idea of what I’m talking about? I’ll make it easy for you… download the v76 implementation first, and if it doesn’t work then check out the v75 implementation. If you’re using one of the latest browsers, you should have no trouble.

WebSocketsTest (draft 75).zip (Older browsers)

WebSocketsTest (draft 76).zip (Latest browsers)

Related posts:

1. HTML 5 Web Sockets
2. AJAX call using an ASP.NET web page
3. AJAX call using an ASP.NET HTTP Handler
4. AJAX call using an ASP.NET Page Method
5. AJAX call using ASP.NET Web Services

The history: the beginning of AJAX

The world wide web and the Internet started as a stateless content delivery mechanism, taking a step backwards compared to traditional desktop applications. Early Internet applications needed to explicitly request every piece of information, and the server sent only the requested data.

Then came what we now call “Web 2.0 application development”: Dynamic HTML, heavy usage of JavaScript, AJAX, and various plugins (Adobe Flash and Microsoft Silverlight). These applications were dynamic and responsive, and they brought much of that rich interactive experience users enjoyed in desktop client/server applications to the Internet. However, due to the request and response architecture that these applications are based on, the latest Rich Internet Applications still cannot match the connectivity and the capability to get real-time data that client/server applications had more than a decade ago.

The reason is that these applications still need to initiate the communication from the web browser to get some data from the server: that is, the client part of the application running in the web browser has no way to know whether the server has some data for it.

The next logical step: polling and Comet programming techniques

Thus, software engineers started working in solving this problem. The client needed to be conscious of any request the server might have for it. But how to achieve this? Well, if communication can only be started by the client, then let’s just make it that way. We’ll make the client constantly ask the server whether there’s some data ready for it. This is what is called polling.

By using this technique, the web application essentially polls the server on a regular basis, based on a timer, using a simple HTTP request each time the timer expires. However, the cost of polling frequently is very high – both in terms of network bandwidth as well as server infrastructure needed to support a huge number of polling requests. The server must have the capability to buffer the data that it needs to send to the client until the next request comes from the client.

After a short while, this technique was seen totally unusable due to its great resource requirements. Then came the Comet programming techniques – long polling and streaming:

In long polling, also known as asynchronous polling, the browser sends a request to the server and the server keeps the request open for a set period. If a notification is received within that period, a response containing the message is sent to the client. If a notification is not received within the set time period, the server sends a response to terminate the open request and the browser resends the request to the server.

When streaming is used, the browser sends a complete request, but the server sends and maintains an open response that is continuously updated. A request is sent and kept open indefinitely (or for a set period of time) and the response is updated whenever a message is ready to be sent, but the server never signals to complete the response, thus keeping the connection open to deliver future messages.

But if you think about it, these techniques are just hacks, tricks used to simulate a technology that doesn’t exist: server-sent events. If the server could actually start the communication, none of these ugly tricks would be needed.

The evolution: server-sent events & Web Sockets

We had to wait until HTML 5 came to solve this problem. The Communication section in the HTML 5 specification section introduces server-sent events and Web Sockets. These new features enable a new paradigm of web application programming that will revolutionize the way to develop and deploy web applications.

Server-sent events are not quite the solution, but a formalization of Comet programming techniques. The server-sent event HTML 5 specification introduces a new DOM element called eventsource.

But the guy we must pay all our attention to is the HTML 5 Web Socket specification: the Web Socket interface defines a full duplex communications channel that is exposed via a JavaScript interface in HTML 5 compliant browsers.

When a new Web Socket connection is established, the browser opens an HTTP connection to the server first and then negotiates with the server to upgrade the connection to a dedicated and persistent Web Socket connection. This process automatically sets up a tunnel through to the server, solving numerous issues that the various Comet programming techniques encountered. Once established the Web Socket is a full duplex channel between the client and the server.

I’ve developed a Web Socket server and client implementation. Check it out for yourself and see what I’m talking about!

Related posts:

1. HTML 5 C# Web Sockets server and ASP.NET client implementation
2. Different ways to use AJAX in ASP.NET
3. AJAX call using an ASP.NET web page
4. AJAX call using ASP.NET Web Services

Web Services are a very general model for building applications, and can be implemented for any operation system that supports communication over the Internet. A Web Service is some programmable application logic accessible via standard Web protocols. It is often referred to as Web APIs as well, since they are a set of methods that provide some functionality through remote method calls. It is a way of offering some of your functionality to all of the internet. But, of course, some kind of restrictions and security can be built into your web services, if that’s what you wish.

As it turns out, the previous article I posted showing how to use Page Methods was also a Web Service: Web Methods are the building blocks of Web Services (a Web Service has many different Web Methods). But it was a very small and simple implementation, intended to return simple data to a small script placed in that same web page. The example we’re going to see follows the same concept, but in a larger way. We’re going to see the basics of how to implement a full-blown Web Service that can be accessed from anywhere on the internet.

This is very handful if you want to develop a collection of methods to be called from anywhere in your application. Imagine you’d like to know in which moment the user logged in to the system: you could write this server method and then make it public as a web service. This way, you’ll have this server functionality available through an AJAX call from anywhere in the application.

Ok, enough theory, now let’s get our hands dirty. Get to the .aspx part of the web page in which you wish to implement your ajax call, and write the HTML code we’ve been using in all our examples:

<body>
    <form id="form1" runat="server">
      <h2>AJAX call test page</h2>
      <button type="button" onclick='ExecuteAJAXCall()'>Get server time</button>
      <br /><br />
      <div id="DataContainer" ></div>
    </form>
</body>

We need a button to perform the AJAX call, and an empty DIV to hold the data retrieved from the server. Now, the Javascript code:

<script type="text/javascript">
    function ExecuteAJAXCall() {
        $.ajax({
            type: "POST",
            url: "AJAXCalls.asmx/GetServerTime",
            data: "{}",
            contentType: "application/json; charset=utf-8",
            dataType: 'json',
            success: Callback_AJAXCall
        });
    };

    function Callback_AJAXCall(data) {
        document.getElementById("DataContainer").innerHTML = "The time at the server is: " + data.d;
    };
</script>

Note that the first function is invoked when the button is pressed. This function is in charge of performing the AJAX call by using the jQuery framework. This time, this function has changed a bit from other examples. Web Services calls require more parameters to set the communication between client and server up. The content type must be declared as “application/json; charset=utf-8”. And, as with the previous Page Method example, server procedures are called using the syntax [page name] + “/” + [method name].

When the AJAX call returns, we have the usual function that takes care of painting the result on the screen. Note how we need to use the d property to access the data this time.

Now, we need to write the Web Service. The easiest way is to right-click on your project and add a new item from there. Select Web Service, and you’ll get a skeleton from which you can implement the functionality you wish in your web service. For our example, we’ll write this piece of code:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Services;

namespace WebServiceAJAXCall
{
    /// <summary>
    /// Summary description for AJAXCalls
    /// </summary>
    [WebService(Namespace = "http://www.undisciplinedbytes.com/")]
    [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
    [System.ComponentModel.ToolboxItem(false)]
    [System.Web.Script.Services.ScriptService]
    public class AJAXCalls : System.Web.Services.WebService
    {

        [WebMethod] public string GetServerTime()
        {
            return DateTime.Now.ToString();
        }
    }
}

As you can see, we’ve only written the code required to return the server date and time. If you compare this example to the previous one where I explained how to implement AJAX calls with page methods, you can see that this is essentially the same thing. It all comes down to using the WebMethod attribute from the System.Web.Services library. However, this example that we’re seeing today is more complete, as it is implemented using a full-blown web service. The objective of this article is not to fully explain ASP.NET Web Services (I’ll leave that to some other post I have in mind), but to explain the very basics to be able to implement and AJAX call using them, so I won’t bother about diving into the details. But keep in mind that Web Services are much more powerful than this, and that their intention aim much higher than simple AJAX calls.

Here’s the Visual Studio project for you to play with:

WebServiceAJAXCall.zip

Related posts:

1. AJAX call using an ASP.NET Page Method
2. AJAX call using an ASP.NET web page
3. AJAX call using an ASP.NET HTTP Handler
4. Different ways to use AJAX in ASP.NET
5. HTML 5 C# Web Sockets server and ASP.NET client implementation

ASP.NET allows you to define methods in the code-behind of an ASPX page. This is very helpful in situations where you want to expose some specific server side functionality such as data retrieval for a specific page. If you need to make the operation available to multiple different .aspx pages it’s a better idea to use a web service so your pages can share the functionality. We’ll see how to use web services in the next post.

Please note that page methods must be declared as static, meaning a page method is completely self-contained, and no page controls are accessible through the page method. For example, if you have a textbox on the web form, there is no way the page method can get or set its value. Consequently any changes with regards to the controls have no affect on the page method. It is stateless and it does not carry any of the view-state data typically carried around by an ASP.NET page.

Ok, so we’ll set up the HTML we need to run this test. We’ll use the same one we’ve been using in all our examples:

<body>
    <form id="form1" runat="server">
      <h2>AJAX call test page</h2>
      <button type="button" onclick='ExecuteAJAXCall()'>Get server time</button>
      <br /><br />
      <div id="DataContainer" ></div>
    </form>
</body>

As usual, we’ll draw a button to perform the AJAX call, and an empty DIV to hold the data retrieved from the server. Now, the Javascript call:

<script type="text/javascript">
    function ExecuteAJAXCall() {
        $.ajax({
            type: "POST",
            url: "default.aspx/GetServerTime",
            contentType: "application/json; charset=utf-8",
            data: "{}",
            dataType: 'json',
            success: Callback_AJAXCall
        });
    };

    function Callback_AJAXCall(data) {
        document.getElementById("DataContainer").innerHTML = "The time at the server is: " + data.d;
    };
</script>

Note that the first function is invoked when the button is pressed. This function is in charge of performing the AJAX call by using the jQuery framework. This time, this function has changed a bit from other examples. Page method AJAX calls require more parameters to set up the communication between client and server. We need to set the content type, and send the parameters to the method, even if it is a parameter-less method. Note how we’re calling the method by using the syntax [page name] + “/” + [method name].

When the AJAX call returns, we have the usual function that takes care of painting the result on the screen. Note how we need to use the d property to access the data this time.

Now comes the interesting part. As we saw before, we’re programming a serverside method in the same web page to return the data from the server, so we don’t need any more web pages in our project. To implement this functionality, get to the codebehind part of the web page and write this code:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.Services;

namespace PageMethodAJAXCall
{
    public partial class _Default : System.Web.UI.Page
    {
        protected void Page_Load(object sender, EventArgs e)
        {

        }

        [WebMethod] public static string GetServerTime()
        {
            return DateTime.Now.ToString();
        }
    }
}

The secret behind this magic is just the System.Web.Services library we’re importing. This library provides the WebMethod attribute, which can be used in public static methods to indicate they’re to be accessed by remote client calls. Whatever the function returns will be sent to the client. Note how this time we don’t need to serialize the data nor we need to deactivate the cache: everything is taken care of by the Web Services library. You just need to set the WebMethod attribute and return the data you want. Nothing more is required.

I would say this way of performing AJAX calls is the easiest of all. It requires almost no more concepts than what a developer will have from regular programming, and hides much of the complexity. However, it is not the standard way of communicating with the server for controls, plugins and widgets out there, so it is not always possible to use it. But if you’re developing your own web control from scratch or you can tweak the way some other web control requests data, you should consider using this technique. Remember: keep it simple!

As usual, you can take the Visual Studio project from here and take a look at it:

PageMethodAJAXCall.zip

Related posts:

1. AJAX call using ASP.NET Web Services
2. AJAX call using an ASP.NET web page
3. AJAX call using an ASP.NET HTTP Handler
4. Different ways to use AJAX in ASP.NET
5. HTML 5 C# Web Sockets server and ASP.NET client implementation

But, what is an HTTP handler? Well, as its names suggests, it is an element that handles HTTP requests. Well, but that’s what an .aspx web page does, right? Sure, but in a lengthier, slower and resource-hungrier way. Regular web pages inherit from the System.Web.UI.Page class, which contains a lot of overhead and pre and post-processing in order to make it easier for the programmer to return HTML code to the client performing a request. In other words, the web page class has stuff to make it easier to develop a web page. It’s got some logic, doesn’t it?

But, what if we don’t want to return a web page? Then we’re just wasting resources in our server, since we’re not to going to use any of the facilities the web page class provides. If what we want to return is not an actual web page, then you should avoid using the System.Web.UI.Page class.

We’ll take a closer look at HTTP handlers in some other post I’m preparing, but for now you should know that they’re more adequate for processing AJAX requests.

This example is quite similar to the previous one: the only difference is that the HTTP handler replaces the web page. Except for that, we’ll be doing the same call and using the same javascript code. However, just for clarity’s shake, I’ll be posting all the code involved here.

Ok, so now we’ll get our hands dirty and start doing some work! First, we’ll need some HTML code to draw a simple test page. Start a new Visual Studio Project and get to the newly created page. On the C# codebehind of the new page we won’t be changing anything. Leave everything by default. We’ll be doing our work in the .aspx part. This HTML code should be sufficient for our needs:

<body>
    <form id="form1" runat="server">
      <h2>jQuery AJAX call test page</h2>
      <button type="button" onclick='ExecuteAJAXCall()'>Get server time</button>
      <br /><br />
      <div id="DataContainer" ></div>
    </form>
</body>

This is a very simple page. We’ll just have a heading, a button to perform the AJAX call, and an empty DIV to hold the data retrieved from the server. Now we need some actual code to make the AJAX call:

<script type="text/javascript">
   function ExecuteAJAXCall() {
         $.ajax({
             url: "AJAXRequest.ashx",
             dataType: 'json',
             success: Callback_AJAXCall
         });
   };

   function Callback_AJAXCall(data) {
         document.getElementById("DataContainer").innerHTML = "The time at the server is: " + data;
   };
</script>

Note that the first function is invoked when the button is pressed. This function is in charge of performing the AJAX call by using the jQuery framework. We’re passing three parameters to the function: the URL of the element that will get called, they type of data we’re expecting back (JSON in this case) and the javascript function to execute once the data gets back to the client. The jQuery ajax function has many more parameters, but we didn’t need them this time since the example is not very complicated.

The function called when the data is returned is very simple: its only purpose is to take the string returned from the server and write it in the container we previously created for this purpose. Note that the parameter it receives, data, is already a javascript object. The AJAX call returns a simple string from the server, but the jQuery function is smart enough to convert that string to a javascript object and pass it to the function we indicated.

Ok, now we’re getting to the interesting point. Now that we have the test page in place, let’s deal with the AJAX call server-side. The AJAXRequest.ashx HTTP handler is the link between the client web browser and the server. Here we’ll process everything we need and we’ll return a string to the client with the data requested.

So here’s how we program an HTTP handler:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Script.Serialization;

namespace WebApplication1
{
    ///
    /// Processes AJAX requests
    ///
    public class AJAXRequest : IHttpHandler
    {

        public void ProcessRequest(HttpContext context)
        {
            JavaScriptSerializer JSSerializer = new JavaScriptSerializer();
            string CurrentDate = DateTime.Now.ToString();

            context.Response.CacheControl = "no-cache";
            context.Response.ContentType = "text/plain";
            context.Response.Write(JSSerializer.Serialize(CurrentDate));
        }

        public bool IsReusable
        {
            get
            {
                return false;
            }
        }
    }
}

To implement an HTTP handler you just need to implement the System.Web.IHttpHandler interface. You need to provide the desired behaviour to the ProcessRequest method and the  IsReusable property. The first method is the one which actually takes care of processing the HTTP requests and returning the data. The IsReusable property determines whether this instance of HTTP handler can be reused for fulfilling another request of the same type.

This implementation is very simple: it just takes the current date and time from the server, converts it to JSON format and returns it. Note the System.Web.Script.Serialization class we’re importing. This class takes care of converting the object we want to return to JSON format. Note the line in which we deactivate the cache as well. If you don’t do this, the AJAX call will always seem to return the same data, as the web browser will have kept a copy of it the first time it was executed. Most AJAX calls need the cache disabled in order to work properly.

You can download a copy of the Visual Studio project and do some tests to check how it works:

jQueryAJAXHTTPHandlerCall.zip

Related posts:

1. AJAX call using an ASP.NET web page
2. AJAX call using an ASP.NET Page Method
3. AJAX call using ASP.NET Web Services
4. Different ways to use AJAX in ASP.NET
5. HTML 5 C# Web Sockets server and ASP.NET client implementation