DevArchive.net Blog: JavaScript Enumerations in ASP.NET AJAX Framework

With AJAX "revolution" last years we write more and more complicated javascript code. Using enumerations can significantly improve the quality of client-side code and make it more readable. In this post I will show some code samples describing how to create and use enumerations in ASP.NET AJAX framework.

So how can we create and use enumerations in ASP.NET AJAX framework.

The simplest enumeration looks like this:

// Register new Namespace, we will create enumeration inside it
Type.registerNamespace('MyNamespace');

// Define an enumeration type.
MyNamespace.MyEnum = function(){};
MyNamespace.MyEnum.prototype = 
{
        Value1  : 1, 
        Value2  : 2,
        Value3  : 4,
        Value4  : 8
}
// Register type as enumeration
// Syntax
//     ANamespace.AnEnum.registerEnum(name, flags);
// Arguments
//     name 
//     A string that represents the fully qualified name of the enumeration.
//     flags 
//     true to indicate that the enumeration is a bit field; otherwise, false.
MyNamespace.MyEnum.registerEnum("MyNamespace.MyEnum", false);

Now lets assign enumeration value to some variable:

// assign some value from enumeration to variable
var value = MyNamespace.MyEnum.Value1;

Now it's interesting to see that in javascript the variable "value" will have different type then we expect, it's simply "Long" value. This is how it differs from using enums in C#:

Also note that Value1, Value2 and another members of enum are also of type "Long".

Ok, next let's use switch statement for our enumeration to find out which value is assigned to it:

// we can use switch statement to find which value is assigned to variable

switch(value) {
    case MyNamespace.MyEnum.Value1:
        alert("MyNamespace.MyEnum.Value1");
    break;
    case MyNamespace.MyEnum.Value2:
        alert("MyNamespace.MyEnum.Value2");
    break;
    case MyNamespace.MyEnum.Value3:
        alert("MyNamespace.MyEnum.Value3");
    break;
    case MyNamespace.MyEnum.Value4:
        alert("MyNamespace.MyEnum.Value4");
    break;
}

And here is the result:

As you can see the code is clean - we can see definitely what values are standing for and what is the processing logic for each of them. Of course it's better than using cryptic numbers like 1,2,3,4 etc. (In real application you will assign more descriptive names to enumeration members then they are in the sample).

Let's move next.

Enumerations, when registered with line of code in the first block above are automatically supplemented with two useful functions. These are "parse" and "toString" functions.

For example the following code at this point:

// we can get string representation of variable containing some value
// that enumeration contains
var valueStr = MyNamespace.MyEnum.toString(value);
alert(valueStr);

And the result of executing the code is:

By using parse function of enumeration we can get Long value by specifying the string value:

// we can get Long type value by specifying string for enumeration member:
var valueFromStr = MyNamespace.MyEnum.parse(valueStr);
alert(valueFromStr);

And the result:

Ok, now what if we want to use enumeration as a set of flags? Can we do this with AJAX, - answer - yes. But first look at the first block of code above. We must specify this when registering the enumeration:

// Arguments
//     name 
//     A string that represents the fully qualified name of the enumeration.
//     flags 
//     true to indicate that the enumeration is a bit field; otherwise, false.
MyNamespace.MyEnum.registerEnum("MyNamespace.MyEnum", false);

In this code the second parameter is telling the AJAX framework, that the enumeration we are registering can not be used as flags. So If for example I will try to run the following code:

// use enumeration as a set of flags and try to show string representation
var values = MyNamespace.MyEnum.Value1 | MyNamespace.MyEnum.Value1;
alert(MyNamespace.MyEnum.toString(values));

Immediately the following exception is shown:

So why is this happening? And what "3" stands for?

When we assign several values to some variable using "|" operator - this performs simple bitwise "OR" operation, and therefore for values 1 and 2 - the result of the operation will be 3, so this line of code goes without exception, but when we try to return string representation of that value - the framework throws an error.

Let's try to change the line of code where we will register enumeration as flags:

MyNamespace.MyEnum.registerEnum("MyNamespace.MyEnum", true);

After running the code everything works now:

Let's try to do reverse thing - turn the string "Value1, Value2" into Long value and see what will it be:

// Assign several flags to Long value by using String representation
var valuesFromStr = MyNamespace.MyEnum.parse("Value1, Value2");
alert(valuesFromStr);

Here is the result:

Ok, now how we check if a long value with flags contains some specific flag:

// check if values var containing flags includes separate flag 
if(values & MyNamespace.MyEnum.Value1) {
    alert("values flags includes Value1 flag");
}

if(values & MyNamespace.MyEnum.Value2) {
    alert("values flags includes Value2 flag");
}

if(values & MyNamespace.MyEnum.Value3) {
    alert("values flags includes Value3 flag");
}

if(values & MyNamespace.MyEnum.Value4) {
    alert("values flags includes Value4 flag");
}

Result: