This is the third post in a multi-part series covering common mistakes C# developers tend to make when they first start writing JavaScript.

The first post covered the following topics:

• 1. Having Variables & Functions in Global Scope
• 2. Not Declaring Arrays & Objects Correctly

The second post covered the following topics:

• 3. Not Understanding False-y Values
• 4. Not Testing & Setting Default Values Correctly
• 5. Using the Wrong Comparison Operators
• 6. Not Using the for…in Statement Correctly

Introduction

This post continues to focus on areas where C# developers tend to make bad JavaScript decisions based on their previous training. The languages are similar enough syntactically that C# developers tend to not invest the time to learn JavaScript’s differences.

The following post points out several misunderstandings that can get you into some confusing situations.

More Bad Practices

7. Misunderstanding Scope in JavaScript

Understanding the different between Block Scope (what C# uses) and Function Scope (what JavaScript uses) is one of the most important things you should know when moving from C# to JavaScript. If you don’t understand this concept then things can get confusing real quick.

In C#, if you declare a variable inside of a set of brackets then the lifetime of the variable only lives inside that scope. However, in JavaScript, the variables you declare inside a function are available to any other code within that function scope.

Let’s look at the following code and see what concepts we can learn.

// Code written thinking that JavaScript has block scope
function eat() {
    var food = "bacon",
        isHungry = true;

    if ( isHungry ) {
        //A C# developer might think that timeToWait is
        //only accessible from within this if statement,
        //but that is not the case
        var timeToWait = 10;

        console.log( "Waiting " + timeToWait + " minutes" );

        chew();
    }

    function chew() {
        var bodyPart = "mouth";

        //The chew function also has access to the
        //timeToWait variable because it is part of the
        //eat function's scope
        console.log( "After waiting " + timeToWait +
            " minutes, " + "I am eating " + food +
            " with my " + bodyPart );
    }
}

eat();
//Waiting 10 minutes
//After waiting 10 minutes, I am eating bacon with my mouth

You can execute and modify the above code from jsFiddle.

A C# developer might look at the above code and think that the timeToWait variable is only accessible by the if statement, but that isn’t true. The timeToWait variable is accessible anywhere within the eat function. So, that means the chew method can use the timeToWait variable as well.

Instead of declaring your variables throughout the eat function, they should have all been declared at the top. By doing so, it would be more obvious that the scope is on the function and not the block level as a C# developer might expect. I have rearranged the variable declaration to make more sense below.

// Code written understanding JavaScript has function scope
function eat() {
    //Declare all your variables at the top so that it is
    //obvious you are using function scope and not block
    //scope
    var food = "bacon",
        isHungry = true,
        timeToWait, bodyPart;

    if ( isHungry ) {
        timeToWait = 10;

        console.log( "Waiting " + timeToWait + " minutes" );

        chew();
    }

    function chew() {
        bodyPart = "mouth";

        console.log( "After waiting " + timeToWait +
            " minutes. " + "I am eating " + food +
            " with my " + bodyPart );
    }
}

eat();
//Waiting 10 minutes
//After waiting 10 minutes, I am eating bacon with my mouth

You can execute and modify the above code from jsFiddle.

Best Practice

It is considered best practice to declare all of your variables at the top of your function. By declaring your variables at the top of your function, you are sending a message to yourself and anyone else that those variables are available to anything inside of the function.

It turns out there is an even more compelling reason to declare your variables at the top of your function.

8. Not Knowing Variable and Function Hoisting

As we examined in the above section, JavaScript uses Function Scope instead of Block Scope. How exactly does that work? Behind the scenes JavaScript does something called variable and function hoisting.

Variable Hoisting

In JavaScript all the variables inside of a function share the same scope. Inside of a function, JavaScript first looks for all the variable declarations, hoists their declarations to the top of the function, and then initializes them to undefined. Their assignments still remain on the same line where you originally declared them. This is known as ‘variable hoisting’.

For example let’s say that we wrote the following piece of JavaScript code

//Code You Might Write
function sayHello( firstName, middleName, lastName ) {
    var fullName = firstName + " " + middleName + " " +
        lastName;

    if ( fullName === "Carlos Rey Norris" ) {
        var nickName = "Chuck";

        console.log( "Hello " + nickName + " " +
            fullName.split(" ")[2] );
    }
}

sayHello( "Carlos", "Rey", "Norris" ); //Hello Chuck Norris

You can execute and modify the above code from jsFiddle.

Behind the scenes JavaScript takes the fullName and nickName variables and declares them all at the top of the function. Their assignments remain in the same place, but their declaration location changed.

//How JavaScript Interprets It
function sayHello( firstName, middleName, lastName ) {
    //Hoists all the variable declarations to the top
    //of the function and sets to undefined
    var fullName = undefined,
        nickName = undefined;

    //fullName assignment remains in original position
    fullName = firstName + " " + middleName + " " + lastName;

    if ( fullName === "Carlos Rey Norris" ) {
        //nickName assigned remains in original position
        nickName = "Chuck";

        console.log( "Hello " + nickName + " " +
            fullName.split(" ")[2] );
    }
}

sayHello( "Carlos", "Rey", "Norris" ); //Hello Chuck Norris

You can execute and modify the above code from jsFiddle.

Where Things Can Get Confusing: Part 1

Not knowing this can lead you into some pretty confusing situations. For example, take a look at the following example.

//Where You Can Get Into Trouble
for ( var i = 0; i < 10; ++i ) {
    for ( var i = 0; i < 5; ++i ) {
        console.log( "Hello" );
    }
}

Do you see what is wrong in the above code? The intent of the developer was to print out “Hello” 50 times, but the result is an infinite loop that prints out “Hello” continuously! A C# developer might think that each i variable is in it’s own scope, but not in JavaScript. JavaScript hoisted the i variable to the top of the function and both loops are updating the same variable. The effect is that the inner loop is never letting the outter loop’s i variable reach 10, which is why the code never exits the loop.

Where Things Can Get Confusing: Part 2

Here is another example of where you might get confused about scope. The following code declares someVariable outside of the function and then the someVariable variable is written to the console immediately inside the function. At first glance, that seems like it should work, but in the following example it does not!

//Where You Can Get Into Trouble

console.log( someVariable ); //undefined
var someVariable = 42; //Global variable
console.log( someVariable ); // 42

function doSomething() {
    console.log( someVariable ); // undefined
    //Why is someVariable undefined?
    //Developer expected to see 42 from global variable

    someVariable = 1
    console.log( someVariable ); // 1

    console.log( window.someVariable ); // 42
    //Why is window.someVariable 42?
    //Developer thought he just set global variable to 1

    if ( false ) {
        var someVariable = 0;
    }
}

doSomething();

console.log( someVariable ); // 42
//Why is someVariable is 42?
//Developer expected to see 1 from global variable

You can execute and modify the above code from jsFiddle.

Let’s rewrite the same code above, but this time as JavaScript would interpret it with variable hoisting.

//How JavaScript Interprets It

var someVariable = undefined;
console.log( someVariable ); //undefined
someVariable = 42; //Global variable
console.log( someVariable ); // 42

function doSomething() {
    //Because of variable hoisting var is
    //moved to the top of the function and set to undefined
    var someVariable = undefined;
    console.log( someVariable ); // undefined

    someVariable = 1
    console.log( someVariable ); // 1
    //This above line of code didn't set the global
    //instance, but the local one that was hoisted

    console.log( window.someVariable ); // 42

    if ( false ) {
        someVariable = 0;
    }
}

doSomething();

console.log( someVariable ); // 42
//Because of variable hoisting in
//doSomething the code inside never updated
//the global variable

You can execute and modify the above code from jsFiddle.

When you understand how hoisting works it is easier to understand why the someVariable variable was undefined immediately inside the function. Since there was a var someVariable = 0; inside the if statement, that variable got hoisted to the top of the function. So, instead of “someVariable” referencing the global instance, it is referencing the local someVariable variable declared in the function scope.

As you can tell, if you don’t have a good understanding on how function scope works, then you can get into some trouble real fast.

And Then There Was Function Hoisting

Now that you have a good grasp on variable hoisting, let’s change our focus somewhat to function statements and function expressions. The hoisting rules for functions aren’t exactly the same as they are for variables. First, we need to understand the difference between a function statement and a function expression. The easiest way to tell them apart is, if it starts with the function keyword, then it is a function statement. See the following examples comparing the two function declarations.

//Example with various function declarations 

try {
    sayHello(); //Error because not defined
} catch (e) {
    //Property 'sayHello' of object [object DOMWindow]
    //is not a function
    console.log(e.message);
}
sayGoodbye(); //Goodbye

//Function Expression
var sayHello = function() {
    console.log("Hello");
};

sayHello(); //Hello
sayGoodbye(); //Goodbye

//Function Statement
function sayGoodbye() {
    console.log("Goodbye");
}

sayHello(); //Hello
sayGoodbye(); //Goodbye

You can execute and modify the above code from jsFiddle.

The above function statement is transformed behind the scenes into a function expression and then both the variable and the assignment are hoisted to the top of the function scope.

For example, let me rewrite the above code snippet as JavaScript would interpret it.

//How JavaScript Interprets It

var sayHello = undefined,
    sayGoodbye = undefined;

//Function Statement was converted to a
//function expression and both the variable
//and assignment were hoisted to the top of
//the function
sayGoodbye = function() {
    console.log("Goodbye");
};

try {
    sayHello(); //error
} catch(e) {
    //Property 'sayHello' of object [object DOMWindow]
    //is not a function
    console.log(e.message);
}
sayGoodbye(); //Goodbye

//The declaration of the Function Expression was
//hoisted to the top of the function, but the
//assignment stayed in the original location
sayHello = function() {
    console.log("Hello");
};

sayHello(); //Hello
sayGoodbye(); //Goodbye

//sayGoodbye Function statement was here, but got
//completely hoisted to the top of the function

sayHello(); //Hello
sayGoodbye(); //Goodbye

You can execute and modify the above code from jsFiddle.

As you can see from the above example, function expressions follow the same rules as variable hoisting, but function statements vary slightly. A function statement is first converted to a function expression and instead of just hoisting the declaration, it hoists both the declaration and the assignment of the function as well.

Best Practice

Since JavaScript uses Function Scope and hoists it’s variable declarations, it is considered best practice to declare all of your variables at the top of your function.

9. Not Using Closures Correctly Or At All

Using a closure is a way to keep variables alive after a function has returned. The Mozilla Developer Network has a great page explaining closures. In it they provide a core definition:

“A closure is a special kind of object that combines two things: a function, and the environment in which that function was created. The environment consists of any local variables that were in-scope at the time that the closure was created.”

A closure can be very helpful when needing to enclose certain variables to a particular scope or when we need to maintain state inside an object. We will examine a common code scenario and examine what is going on and how we might be able to fix it using a closure.

Looping Without A Closure

The intent of the following code snippet is to add an event handler to 10 different DOM elements and each one should alert it’s ID attribute (e.g. “You’ve clicked 3″). You should know that if this was your actual intent, then there is a much easier way to do this, but for academic reasons let’s stick with this implementation.

//broken
var unorderedList = $( "ul" );
for (var i = 0; i < 10; i++) {
    $("<li />", {
        id: i,
        text: "Link " + i,
        click: function() {
            console.log("You've clicked " + i);
        }
    }).appendTo( unorderedList );
}

You can execute and modify the above code from jsFiddle.

The output of the above code may not be what you first expect. The result of every click handler will be “You’ve clicked 9″ because the value of i at the point the event handler was fired is “9″. What the developer really wanted is for the value of i to be displayed at the point in time the event handler was defined.

Looping With A Closure: Part 1

In order to fix the above bug we can introduce a closure.

//working
var unorderedList = $( "ul" ), i;

for (i = 0; i < 10; i++) {
    $("<li />", {
        id: i,
        text: "Link " + i,
        click: function(index) {
            return function() {
                console.log("You've clicked " + index);
            }
        }(i)
    }).appendTo( unorderedList );
}

You can execute and modify the above code from jsFiddle.

One way to fix the above code is to utilize a self-executing anonymous function. That is a fancy term that means we are going to create a nameless function and then immediately call it. The value of this technique is that the scope of the variable stays within the function. So, first we will surround the event handler content in a function and then immediately call the function and pass in the value of i. By doing that, when the event handler is triggered it will contain the value of i that existed when the event handler was defined.

Looping With A Closure: Part 2

If the above syntax is new to you, then you might consider the following code snippet, which is essentially the same thing, but split out a little more. Instead of using an anonymous function, we are defining a named function and passing the value of i into it so the scope will remain in the function.

var unorderedList = $( "ul" ), i;

for (i = 0; i < 10; i++) {
    $("<li />", {
        id: i,
        text: "Link " + i,
        click: clickEventHandler(i)
    }).appendTo( unorderedList );
}

function clickEventHandler( index ) {
    return function() {
        console.log("You've clicked " + index);
    }
}

You can execute and modify the above code from jsFiddle.

Best Practice

As seen in the above examples, a closure can be very helpful when trying to persist certain variable states. There are actually several other really good uses for closures as well. A pattern that I use frequently is called the Revealing Module Pattern, which uses the concept of closures to simulate private methods and properties as you might expect from C#.

For more examples of when to use closures appropriately in your code there is a great post by Juriy Zaytsev on Script Junkie entitled Use Cases for JavaScript Closures

So What Now?

Tools To Help You

Many of the above issues we’ve addressed can be found during development by running your code through JSLint, which is a JavaScript code analyzer that Douglas Crockford developed. It takes many of the concepts from his experience and boils them down into a set of rules you can execute against your code.

You might also consider running your code through another tools called DoctorJS. This tool builds on the concepts taught by Douglas Crockford and extends them somewhat with their own best practices.

A combination of these two tools should help pinpoint some obvious practices that you should change in your code. Passing these tools does not mean you have good code, but it can help you identify areas that need some attention.

Sources for Additional Learning

As you’ve probably noticed I’ve mentioned Douglas Crockford a lot in this article. A lot of his work identifies areas where classical languages such as C# vary from JavaScript. He has a great book entitled JavaScript: The Good Parts that I highly suggest you reading. You can also check out his phenomenal Crockford on JavaScript video series on Yahoo! that covers much of the content of the previously mentioned book.

In addition, the JavaScript articles on the Microsoft Script Junkie website are top notch. I highly recommend checking them out. The authors on the site are top notch experts from the field. Here is a small taste of some of the great article you can find:

• Prototypes and Inheritance in JavaScript by Scott Allen
• Style in jQuery Plugins and Why it Matters by Ben Alman
• Intro to Error Handling in Ajax Apps by Me
• Use Cases for JavaScript Closures by Juriy Zaytsev
• Introduction to the Reactive Extensions to JavaScript by Matt Podwysocki
• Many more…

There is also a great blog post series by Julian Bucknall entitled JavaScript for C# Programmers. The posts were from some time ago, but their content is still timely and very much top notch.

Conclusion

The intent of these articles was to shed some light on practices that a C# already does that might become an immediate issue in JavaScript development.

In addition to the bad practices that I’ve mentioned in this series, there are many more things that a C# developer should know. JavaScript is a very powerful language and has unfortunately received a bad wrap primarily because of the painful nature of the DOM.

JavaScript is similar enough to C# that you feel comfortable, but different enough that is worth diving into it deeper. You can actually do some pretty cool things that you can’t do in C#. I hope you find these tips helpful.

This is the second post in a multi-part series covering common mistakes C# developers tend to make when they first start writing JavaScript.

The first post covered the following topics:

• 1. Having Variables & Functions in Global Scope
• 2. Not Declaring Arrays & Objects Correctly

Introduction

This post continues to focus on areas where C# developers tend to make poor decisions when writing JavaScript based on their previous training. The languages are syntactically similar enough that C# developers tend to not invest the time to learn JavaScript’s differences.

The following post points out several misunderstandings that can get you into some confusing situations.

More Bad Practices

3. Not Understanding False-y Values

Unlike C# there are many values that JavaScript has that act false-y. Inside an if statement truth-y values will proceed into the then branch and false-y values will drop into the else branch. It is important to understand these special false-y values not only when writing your code, but when trying to understand other people’s code.

The False-y values are:

false
null
undefined
"" (empty string)
0
NaN (not a number)

All other values that aren’t listed in the above list will be considered truth-y (including all objects, the strings “0″, “false”, and many other strange combinations).

Best Practice

When it comes to understanding the outcome of a logical statement, you should know the false-y values in JavaScript. Since these rules are considerably different than C#, you should take the time to understand them.

We will examine the implications of knowing these false-y values a little further in the next few sections.

4. Not Testing & Setting Default Values Correctly

You can easily spot a C# developer if you see them checking for null inside of an if statement or when setting a default value.

Checking for Null

It is common and considered a best practice in C# to check for null before using a variable. If you don’t, then you might fall victim to the dreaded “Object reference not set to an instance of an object” exception. Also, when dealing with strings you’ll also want to test if it is empty or not. The following code snippet is a typical way to do this in C#.

// C# example. Don't do this in JavaScript
if ( someString != null &&
    someString.length > 0 ) {
    //Do something here...
}

In fact, the above code snippet is such a common practice that there is a special IsNullOrEmpty method in the .NET framework to help simplify this case.

// C# code to simplify checking for null and empty string
if ( !string.IsNullOrEmpty(someString) ) {
    //Do something here...
}

As it turns out, when considering the JavaScript false-y values, you can shorten all this logic to the following code snippet. The following code snippets checks to see if the variable is not undefined, not null, and is not empty.

// Simplified JavaScript syntax to check for
// undefined, null, & empty string values
if ( someString ) {
    //Do something here...
}

As a side note, the above someString variable is more likely to be undefined than it is null due to variable hoisting, but thanks to false-y values that is being checked.

Setting A Default Value

Another common scenario you’ll run into is setting a default value to a variable. In C#, you might be be tempted to write some code like the following.

// C# example. Don't do this in JavaScript
if ( someString == null ) {
   someString = "default Value";
}

// Slightly better, but don't do this either
someString = someString ? someString : "default value";

Instead, there is a much simpler way to perform this in JavaScript that uses the logic or operator.

// JavaScript syntax to set a default value
someString = someString || "default value";

Best Practice

Based on the false-y rules we learned earlier, if we want to check if a variable is undefined, not null, and has a value then all we need to do is check the object itself.

5. Using the Wrong Comparison Operators

Knowing that JavaScript is loosely typed and having the False-y values fresh in our mind from the previous section, let’s focus now on common mistakes when using the comparison operator.

Coming from C# you will intuitively use the == and != in your if statements, however, this may yield some results that you didn’t expect.

Problems When Using == or != Comparison Operators

When using the == and != comparison operators, JavaScript tries to help you by coercing the two values into the same type so that it can compare them. This sounds like a good idea, but in the end it can lead to some very confusing results. Check out the following for some of these unexpected results.

// Unexpected Comparisons using the == Operator
0          ==  ''        //true
0          ==  '0'       //true
false      ==  '0'       //true
null       ==  undefined //true
' \t\r\n ' ==  0         //true

You Should Use the === or !== Instead

A better way to compare is to use the === and !== operators (also known at the identify operators), which are much more rigorous. They will not only check the value, but also check the type as well. The results of these comparisons are probably more what you would expect in a strongly typed language. The following code uses the same comparison as the above example, but uses the identify operator instead.

// Expected Comparisons using the === Operator
0          === ''        //false
0          === '0'       //false
false      === '0'       //false
null       === undefined //false
' \t\r\n ' === 0         //false

Best Practice

When you are comparing two values in JavaScript you should use the Identify Comparison Operators (=== & !==).

6. Not Using the for…in Statement Correctly

For those of you who regularly write C#, you probably don’t use the classic for loop much, but use the for…in loop instead. If you aren’t careful this can byte you in several different ways.

Using the for…in Statement on Arrays

You may see the for…in statement used to iterate over arrays, but don’t! You can get into some weird issues. You should instead use the for statement when looping over arrays.

The for…in statement does not guarantee the order of the items that are going to be retrieved, plus you can get into some interesting problems.

In the following example we are creating an array and then setting the 5th index with a value of “test”. Since we have an item at the 5th index, the array is marked as having a length of 6 items. So far, there shouldn’t be any surprises here.

var myArray = [], name;
myArray[5] = "test";
console.log( myArray.length ); //6

However, if you used the for..in statement on this array, you would only see the one item that you inserted in the array, which is probably not what you intended. If this is what you intended, then you should probably not be using an array and should be using an object instead.

var myArray = [], name;
myArray[5] = "test";
console.log( myArray.length ); //6

for ( name in myArray ) {
    console.log( name, myArray[name] );
    //Outputs...
    //   5, test
}

You can execute and modify the above code from jsFiddle.

You should use the standard for loop when iterating over an array. The following example does loop over the entire range of indexes, although most of them are undefined since we didn’t set their values.

var myArray = [], name;
myArray[5] = "test";
console.log( myArray.length ); //6

for ( var i = 0, length = myArray.length; i < length; i++ ) {
    console.log( i, myArray[i] );
    //Outputs...
    //   0, undefined
    //   1, undefined
    //   2, undefined
    //   3, undefined
    //   4, undefined
    //   5, test
}

You can execute and modify the above code from jsFiddle.

If you are not convinced, there is another problem that you can run into when using the for…in statement on an array. Now just suppose that you or some other library changed the prototype of the Array object? If someone where to add a property to the Array.prototype it would also show up as one of the keys in the for…in.

var myArray = [], name;
myArray[5] = "test";
console.log( myArray.length ); //6

Array.prototype.someVariable = "Where did this come from?";
for ( name in myArray ) {
    console.log( name, myArray[name] );
    //Outputs...
    //   5, test
    //   someVariable, Where did this come from?
}

You can execute and modify the above code from jsFiddle.

This actually brings up our next subtopic about using the for…in statement correctly when using an object.

Using the For…In Statement Incorrectly with Objects

As we discussed briefly in the above section, hopefully you are only using the for…in statement with objects and not arrays. You might have seen the for…in used like the following

for ( var name in object ) {
    //Your code here
}

That seems harmless, right? And in many cases it does exactly what you want it to. As it turns out, you should be careful using the above syntax. The for…in statement will actually iterate through all the properties of the object and also the properties that are inherited from the prototype! Since you probably don’t want to iterate over your inherited prototype properties, you should check the object you are enumerating to see if it contains the property before proceeding.

Your modified code snippet should look something like the following instead.

/* Check if object has property before
iterating, because functions inherited
from prototype are also included */
for ( var name in object ) {
   if ( object.hasOwnProperty(name) ) {
      //Your code here
   }
}

The following code snippet shows an example of when the for…in statement might show some undesired results.

var Person = function( firstName, lastName ) {
  this.firstName = firstName;
  this.lastName = lastName;
  return this;
};

Person.prototype = {
  isMarried : false,
  hasKids: false
};

var john = new Person( "John", "Smith" ),
  linda = new Person( "Linda", "Davis" ),
  name;

john.isMarried = true;

console.log( "Not Checking hasOwnProperty" );
for ( name in john ) {
  console.log( name + ": " + john[name] );
  //Outputs
  //  firstName: John
  //  lastName: Smith
  //  isMarried: true
  //  hasKids: false
}

console.log( "Checking hasOwnProperty" );
for ( name in linda ) {
  if ( linda.hasOwnProperty(name) ) {
    console.log( name + ": " + linda[name] );
    //Outputs
    //  firstName: Linda
    //  lastName: Davis
  }
}

You can execute and modify the above code from jsFiddle.

In the above code we created two Person objects and set it’s prototype to include two new properties (“isMarried” and “hasKids”). We then loop over the properties of the “john” person, you will see that not only are his firstName and lastName displayed, but also the inherited “isMarried” and “hasKids” prototype values! In contrast, by checking .hasOwnProperty() when looping over linda’s properties, we only see that her immediate properties are displayed, instead of displaying her inherited properties as well.

Best Practice

The take aways for this point are: * Use the for statement for arrays * Use the for…in statement when iterating over objects and check the hasOwnProperty method

Conclusion

This article has covered some of the common issues you might address coming from C# to JavaScript. I have committed just about everyone of the above Bad Practices myself when I starting to code in JavaScript heavily.

With the recent serge of jQuery hitting the market and other great JavaScript libraries, it is important that we as developers understand the language instead of just thinking that our previous language knowledge will get us by.

This article only covers some of the things you should know. The next post in the series will be published next week. In the meantime please feel free to add comments of any other gotchas that you’ve experience coming from a C# background. I would love to hear about it.

Introduction

Many people come to jQuery and believe that their knowledge of a previous classical language (C#, Java, etc) will help them be successful at client-side scripting. You can use your classical language skills to accomplish a large amount of functionality with jQuery. However, the more client-side code you write you will find yourself uncovering strange bugs because you didn’t take adequate time to learn JavaScript properly.

“…it turns out that if you have absolutely no idea what you’re doing in the language you can still generally make things work.” –Douglas Crockford, Yahoo!’s JavaScript Architect, Douglas on JavaScript -- Chapter 2: And Then There Was JavaScript

This article is targeted for developers that use jQuery but haven’t invested the time necessary to learn JavaScript. The intent is to help you avoid some common mistakes when moving from a classical language (Java, C#, etc) to JavaScript.

jQuery is a library that is written in JavaScript. It is important to remember that you will always be writing in JavaScript when using jQuery. It is inevitable that you will run into native JavaScript concepts that are foreign to the classical language proficient developer. Taking the time now to be proficient in JavaScript will increase your client-side code quality, efficiency, and decrease code maintenance.

Bad Practices

1. Having Variables & Functions in Global Scope

A best practice in C# is to limit the use of global variables. This doesn’t necessarily translate into a bad practice in JavaScript, but most C# developers are not aware of how easily it is to pollute the global namespace with needless variables and functions.

One way you can pollute the global namespace is to not declare your variables. In JavaScript, if you don’t declare your variables then they become globally available to the rest of the program, which is probably not what you wanted and generally a bad idea.

Coming from a C# background, you are most likely used to the concept of namespacing your classes so they won’t clash with other libraries. In the same way you should be mindful to not declare variables or functions in the global namespace to prevent clashing with other libraries, browser extensions, and also your own code.

Bad Practice

The following code shows some bad examples of how to declare variables and functions.

var iAmGlobal = "Keep these to a minimum";

iAmGlobalToo = "Bad";

function oldSchoolWay() {
    //Placed in global scope when executed
    iAmGlobalNooo = "Really Bad"; 

    console.log( "Bad oldSchoolWay Function" );
}

//Bad way to prevent namespace clashing
function namespace_oldSchoolWay() {
    console.log( "Worse oldSchoolWay Function" );
}

//Functions 
window.oldSchoolWay();
window.namespace_oldSchoolWay();

//Global variables are available off window object
console.log( window.iAmGlobal );
console.log( window.iAmGlobalToo );
console.log( window.iAmGlobalNooo );

You can execute and modify the above code from jsFiddle.

In the above code snippet you’ll see that the iAmGlobal, iAmGlobalToo, and iAmGlobalNooo are all global variables. You would expect iAmGlobal and probably iAmGlobalToo to be global variables, but the variable inside the oldSchoolWay function is also global because it was never declared! The best way to stay out of this trouble is to be disciplined and declare all of your variables and not let JavaScript do it for you.

Klaus Komenda actually refers to the function statement as the Old School Way of function declaration. I’ve even seen C# developers trying to prefix their function names (as shown above by namespace_oldSchoolWay) to minimize collisions with other libraries, but you should not do this. That technique still clutters the global namespace.

There are many options to fix this problem, but the simplest is to create a namespace object and then declare all your functions and properties within it. See the following code snippet for a slightly better approach.

Object Literal (All Public)

An Object Literal is a convenient way to create new objects. The syntax looks very similar to what you might expect to see in JSON (JavaScript Object Notation), but they are actually quite different. For more information about this you can check out an in-depth discussion on it by Ben Alman entitled There's no such thing as a "JSON Object".

When you create an Object Literal you can provide properties and methods and they can refer to each other. You can also add additional methods and properties to the object after it has been defined. All the properties and methods that you declare in the Object Literal are publicly accessible to the rest of your JavaScript code.

//Object Literal declaring properties and methods
var skillet = {
    //public property
    ingredient: "Bacon Strips",
    
    //public method
    fry: function() {
        console.log( "Frying " + this.ingredient );
    }
};
console.log( skillet.ingredient ); //Bacon Strips
skillet.fry(); //Frying Bacon Strips

//Adding a public property to an Object Literal
skillet.quantity = "12";
console.log( skillet.quantity ); //12

//Adding a public method to an Object Literal
skillet.toString = function() {
    console.log( this.quantity + " " + 
                 this.ingredient );
};
skillet.toString(); //12 Bacon Strips​

You can execute and modify the above code from jsFiddle.

The above code declares a skillet variable and sets it to an Object Literal with one property (ingredient) and one method (fry) that are both publicly accessible off of the object. You can also add additional public methods and properties to the object after the initial declaration as shown above when adding the quantity property and the toString method. The toString method is able to access the properties of the skillet object since all of it’s parts are public.

Pros

• Cleans up the global namespace by adding a namespace to your properties and methods
• You can add functionality to the object literal at a later point
• All the properties and methods are public

Cons

• Uses the Object Literal syntax to define your properties and methods that some may find cumbersome
• There isn’t the ability to have private properties or methods

Self-Executing Anonymous Function: Part 1 (All Private)

Another common technique that you can use to protect the global namespace is to use a Self-Executing Anonymous Function. This is just a fancy term to refer to a function with no name that is immediately executed after it’s defined. The value of this technique is that you can create a wrapper around your code that protects it from the global namespace. By using the most simple version of the Self-Executing Anonymous Function you can create code that is exclusively private.

//Self-Executing Anonymous Function: Part 1 (All Private)
(function() {
    //private variable
    var ingredient = "Bacon Strips";

    //private function
    function fry() {
        console.log( "Frying " + ingredient );
    }
    
    fry();
}());

//Variables not accessible
console.log( window.ingredient ); //Undefined

//Functions not accessible
try {
    window.fry(); //Throws Exception
} catch( e ) {
    //Object [object DOMWindow] has no method 'fry'
    console.log( e.message ); 
}

//Can't add additional functionality

You can execute and modify the above code from jsFiddle.

The above code snippet wraps the ingredient variable and fry function with a Self-Executing Anonymous Function and right before the function ends it executes the fry method. After the Self-Executing Anonymous Function finishes executing there is no way to run the function again or reference any of the internals of the wrapped code.

Pros

• Hides all your implementation from external code
• The function runs once and only once
• The code inside doesn’t use the Object Literal notation

Cons

• All information is hidden, which may not be what you want
• Slightly more complicated technique, but not really

Revealing Module Pattern (Public & Private)

The Revealing Module Pattern actually uses the concept of the Self-Executing Anonymous Function as well, but in this case we save the result into a variable. This pattern introduces the concept of a Closure. A closure is a way to keep variables alive after a function has returned. The Mozilla Developer Network has a great page explaining closures. In it they provide a core definition:

“A closure is a special kind of object that combines two things: a function, and the environment in which that function was created. The environment consists of any local variables that were in-scope at the time that the closure was created.”

In the following example we will declare private properties and methods as well as public properties and methods.

//Revealing Module Pattern (Public & Private)
var skillet = (function() {
    var pub = {},
        //Private property
        amountOfGrease = "1 Cup";

    //Public property    
    pub.ingredient = "Bacon Strips";

    //Public method
    pub.fry = function() {
        console.log( "Frying " + pub.ingredient );
    };

    //Private method
    function privateWay() {
        //Do something...
    }

    //Return just the public parts
    return pub;
}());

//Public Properties
console.log( skillet.ingredient ); //Bacon Strips

//Public Methods
skillet.fry();

//Adding a public property to a Module
skillet.quantity = 12;
console.log( skillet.quantity ); //12

//Adding a public method to a Module
skillet.toString = function() {
    console.log( skillet.quantity + " " + 
                 skillet.ingredient + " & " + 
                 amountOfGrease + " of Grease" );
};

try {
    //Would have been successful, 
    //but can't access private variable
    skillet.toString();
} catch( e ) {
    console.log( e.message ); //amountOfGrease is not defined
}

You can execute and modify the above code from jsFiddle.

Inside of the Revealing Module Pattern we declared a pub object that will keep all the public properties and methods that you want to be exposed. At the end of the Module the pub object is returned, which is what causes the them to be public outside of the Self-Executing Anonymous Function. All the parts that were not added to the pub object remain private to the outside world; however, the public methods that were exposed have access to the private parts because of the Closure that was created.

Pros

• Allows for public and private properties and methods
• The Technique is Easy to understand
• The code inside doesn’t use the Object Literal notation

Cons

• Doesn’t allow for a way to add private properties to be used in new public methods

Self-Executing Anonymous Function: Part 2 (Public & Private)

We looked at the Self-Executing Anonymous Function earlier as a pattern you could use to keep all your code private. As it turns out, you can actually modify the pattern somewhat so that you can achieve the same benefits of the Revealing Module Pattern. Not only can we achieve public and private properties and methods, but we can also provide an easy way to extend the namespace while keeping the content protected from the global namespace. In addition, the following pattern can protect the $ from conflicting with other JavaScript libraries and also protect undefined from being redefined.

Take a look at the following example, and we will walk through the code explaining the key changes to the pattern.

//Self-Executing Anonymous Func: Part 2 (Public & Private)
(function( skillet, $, undefined ) {
    //Private Property
    var isHot = true;

    //Public Property
    skillet.ingredient = "Bacon Strips";
    
    //Public Method
    skillet.fry = function() {
        var oliveOil;
        
        addItem( "\t\n Butter \n\t" );
        addItem( oliveOil );
        console.log( "Frying " + skillet.ingredient );
    };
    
    //Private Method
    function addItem( item ) {
        if ( item !== undefined ) {
            console.log( "Adding " + $.trim(item) );
        }
    }    
}( window.skillet = window.skillet || {}, jQuery ));

//Public Properties
console.log( skillet.ingredient ); //Bacon Strips

//Public Methods
skillet.fry(); //Adding Butter & Fraying Bacon Strips

//Adding a Public Property
skillet.quantity = "12";
console.log( skillet.quantity ); //12

//Adding New Functionality to the Skillet
(function( skillet, $, undefined ) {
    //Private Property
    var amountOfGrease = "1 Cup";
    
    //Public Method
    skillet.toString = function() {
        console.log( skillet.quantity + " " + 
                     skillet.ingredient + " & " + 
                     amountOfGrease + " of Grease" );
        console.log( isHot ? "Hot" : "Cold" );
    };    
}( window.skillet = window.skillet || {}, jQuery ));

try {
    //12 Bacon Strips & 1 Cup of Grease
    skillet.toString(); //Throws Exception
} catch( e ) {
    console.log( e.message ); //isHot is not defined
}

You can execute and modify the above code from jsFiddle.

First, since we have a Self-Executing Anonymous Function, we can actually provide some parameters to pass to it when it executes. In this case we are passing 2 arguments to the anonymous function.

The first argument looks quite strange. What is window.skillet = window.skillet || {} doing? The code checks to see if skillet exists in the global namespace (window). If it does not exist, then window.skillet is assigned an empty object literal. Using this approach we can build a library across JavaScript files. If another script uses the same technique, then it will pass in the existing instance and append logic to it. Inside the Anonymous Function, if we want something to be public, then we append it to the skillet object. Any other properties or methods will be considered private.

The second argument passed in jQuery. The benefit of this is that the named parameter is referenced as $, which allows us to refer to jQuery as $ within the Anonymous Function without having to worry that it will conflict with the $ declared in other JavaScript libraries. This is a common practice that you will most likely run across when looking at well written jQuery code.

You might notice a 3rd parameter to the Anonymous Function called undefined. Why did we add that parameter and why didn’t we pass an argument to it? In JavaScript, you can unfortunately redefine what undefined means. Imagine that some code somewhere deep in one of your 3rd party libraries redefines undefined to something strange like true. If anywhere in your code you test against undefined, then you code will most likely not behave like you intended. In JavaScript, if you have a parameter that doesn’t have a matching argument, then it’s value is set as undefined. By using this trick, it can save us from the bad code someone wrote to redefine undefined.

Pros

• Gives you the ability to have public and private properties and methods
• The code inside doesn’t use the Object Literal notation
• Keeps undefined’s value as undefined in case someone overrode the value
• Allows you to use $ inside your code without worrying about clashing with other libraries
• Allows your library to grow across files using the “window.namespace = window.namespace || {}” technique
• A common pattern that you will see in many libraries, widgets, and plugins

Cons

• Slightly more complicated pattern, but not overly difficult to understand

If you are interested in digging deeper into some of the patterns I mentioned above then I encourage you to check out Klaus Komenda’s post entitled JavaScript Programming Patterns. The article provides an insightful view of how JavaScript patterns have changed over the years.

Best Practice

In JavaScript it is very important to declare all of your variables and it is considered a best practice to limit the number of objects in the global namespace. Depending on the situation you are developing you may need one or more of the concepts listed above to organize your code and keep it from colliding with other libraries. There is no pattern that is a Silver Bullet, but rather you should assess where you are at and examine the pros and cons of each pattern to address your situation.

2. Not Declaring Arrays & Objects Correctly

JavaScript is a prototypal language and not a classical language like C#. Although JavaScript does have a new operator which looks a lot like C#, you should not use it for creating new objects or arrays.

What Not To Do

You might be tempted to use the new keyword to create your objects in JavaScript.

//Bad way to declare objects and arrays
var person = new Object(), 
    keys = new Array();

The new keyword was added to the language partially to appease classical languages, but in reality it tends to confuse developers more than help them. Instead, there are native ways in JavaScript to declare objects and arrays and you should use those instead.

Preferred Way

Instead of using the previous syntax, you should instead declare your objects and arrays using their literal notation.

       
//Preferred way to declare objects and arrays
var person = {}, 
    keys = [];

Using this pattern you actually have a lot of expressive power using Object Literals and array initializer syntax. As we mentioned earlier, you should be careful to know that Object Literals are not JSON.

//Preferred way to declare complex objects and arrays
var person = {
        firstName: "Elijah",
        lastName: "Manor",
        sayFullName: function() {
            console.log( this.firstName + " " + 
                this.lastName );
        }
    }, 
    keys = ["123", "676", "242", "4e3"];

Best Practice

You should declare all of your variables using their literal notation instead of using the new operation. In a similar fashion you shouldn’t use the new keyword for Boolean, Number, String, or Function. All they do is add additional bloat and slow things down.

The only real reason why you would use the new keyword is if you are creating a new object and you want it to use a constructor that you defined. For more information on this topic you can check out Douglas Crockford's post entitled JavaScript, We Hardly new Ya.

Conclusion

This article has covered some of the common issues you might address coming from C# to JavaScript. I have committed just about everyone of the above Bad Practices myself when I starting to code in JavaScript heavily.

With the recent serge of jQuery hitting the market and other great JavaScript libraries, it is important that we as developers understand the language instead of just thinking that our previous language knowledge will get us by.

This article only covers some of the things you should know. The next post in the series will be published next week. In the meantime please feel free to add comments of any other gotchas that you’ve experience coming from a C# background. I would love to hear about it.

• Post 1: From Enterprise Beginnings

In the last post we covered some introductory topics for creating your own JavaScript utility library, which wraps functionality for Ajax. We’ll start where we left off. Our first step will be to add a few tweaks to our library to make it more usable:

var mySiteAjax = ( function( $ ) {
  return (
     function( params ){
      var settings = $.extend({
        url: "", 
        spinner:  undefined, 
        dataType: "html",
        data: "",
        type: "GET",
        cache:  false,
        success:  function() { }
      }, params );

      $.ajax({
          beforeSend: function() { 
            $( settings.spinner ).show();
          },
          url: settings.url,
          dataType: settings.dataType,
          type: settings.type,
          data: setting.data,
          success: settings.success,
          complete: function() {
              $( settings.spinner ).hide();
            }      
        });
    } 
  );
})(jQuery);

We’ve done two things to our old example. We’ve added new parameters for type and data that could be passed in. Additionally, we’ve removed a named function and returned an object literal. This enables easier usage:

mySiteAjax({
  url: "myUrl",
  success: function( data ) {
    //do something with the data here
  }
});

Although a good start, this solution is not yet satisfactory as we are not yet handling errors in any capacity. How do we handle errors and display messages to the user? Additionally showing and hiding of loading notification images is present but not customizable. What if a page doesn’t want to do a simple showing and hiding of load images? How can we decouple the notifications from our Ajax component library?

Handling and Displaying Errors

When dealing with Ajax errors there are typically two concerns – handling the error in code and displaying an error message to the user.

Handling the Ajax Error

A popular technique for “handling” Ajax errors is to either never add an error callback for the Ajax request, or to end up with code like this (including the todo comment):

$.ajax({
  //...
  error: function() {
    // todo: handle error here.
  },
  //...
});

Most of us have been there. It is often a struggle to determine what reasonable actions can be done with an Ajax error. Yet there are some options. A few pragmatic actions we could take upon Ajax error:

• Try again (especially for GETs).
• Have debug code for non-production code which logs the error details to the console.
• Have an error specific Ajax request URL (either global for all sites or specific to your application). This activity is typically a request in which data is sent to the server and the client does not care about the response. This is typically used to log the issue to a server-side resource.
• Automatically take action based on HTTP Status Code. We can detect certain error codes from the server response and take action. For example a 401 or 403 error may be an indication of expired client credentials. In this case we could redirect the user to a login page to establish new credentials.
• Suggest to the user next steps as part of the error message.

It would be prudent for our utility library to take some actions based upon HTTP status code. If the user request comes in as unauthorized we will redirect to a new page. If there is a server timeout we will try the Ajax request a second time.

To accomplish this we need to add an error callback function to .ajax(). We are also going to add another programming technique to repeatedly call .ajax(). First the code:

var mySiteAjax = ( function( $ ) {
  return (
    function( params ) {
      //...
      var retries = 0;
      function ajaxRequest ( ) {
        $.ajax({
          beforeSend: function(){ 
            $(settings.spinner).show();
          },
          url: settings.url,
          dataType: settings.dataType,
          success: settings.success,
          complete: function(){
            $( settings.spinner ).hide();
          },
          error: function( xhr, tStatus, err ) {
            if( xhr.status === 401 || xhr.status === 403 ) {
              //redirect action here
            } else if ( xhr.status === 504 && !retries++ ) {
              ajaxRequest();
            }
          } // end error handler
        }); // end $.ajax()
      }; // end ajaxRequest() 
      ajaxRequest();
    } // end getViaAjax()
  ); // end return statement
})(jQuery);

We’re using the status property of the XmlHttpRequest object to determine the type of error encountered. With our authorization issues we can detect an authorization error status code and redirect to our authorization page. Handling retries requires us to call the original Ajax call again. To do that we can use recursion.

In our case of recursion we are setting up a retries variable to determine the number of Ajax requests we setup. retries is declared outside of the recursive function. We can use and increment the retries variable inside of our function because of lexical scoping. If retries is 0 and a timeout error code occurs, we increment retries and recursively call ajaxRequest. The ajaxRequest function then sets up a another ajax request. If another timeout occurs retries is now set to 1 which will keep another recursive call from happening.

After we’ve created our ajaxRequest function we then execute it to kick off an initial Ajax request.

We’re not using the global event handler, .ajaxError(). This is because we only want our error handling to affect those calls which come through our component. If we attach a handler globally using .ajaxError() then all ajax errors will result in the execution of our callback. While you may want that behavior in your application, it’s generally considered bad practice to introduce code with side effects.

Displaying Error Messages to the User

Notifying the user of the error involves interaction with another component on the page (you can find an example of creating such a component with our message center plugin blog posts 1 and 2). We could set up another parameter to be passed as an error callback function. However, it seems like we’re quickly going parameter-happy.

We’re already expecting the calling code of our utility function to know about the load notifications (spinners) that may be on the page. We’d be adding yet another responsibility of the callee to know which and how many messaging components may be on the page and would need to be notified of an Ajax error. This puts pressure on the code calling our Ajax library to be edited every time any messaging or loading notification widgets are added, edited, or removed from the page.

Paradigm Shift – Communicating Between Components with Publish/Subscribe

In our case we have three separate components that are trying to interact on the page:

• An Ajax system
• A ‘loading’ notification system
• A flash message or message center

We need an effective way to communicate between components. In the case of our Ajax library, we need to notify any components that an error message is available to be displayed or that a load notification needs to start or end.

Introducing Publish/Subscribe

A great solution would be to broadcast over a channel that an error occurred or that loading has started. Consumers could register a callback to run when a message was broadcast over a specific channel.

One way to accomplish this is the publish/subscribe pattern. With this pattern a publish function typically exists which broadcasts using a message topic. A subscribe function is used to bind a callback function which will be executed when a message topic is broadcast. Data can be passed to the subscriber through an additional parameter.

If we compare a typical publish/subscribe system to a radio broadcast, the “message topic” would be the selected AM, FM, or Satellite station. The data being passed to the subscriber would be analogous to the audio coming through the radio.

Using Custom jQuery Events for Publish and Subscribe

We can illustrate publishing and subscribing by using jQuery custom events names. We can use the event name as our message topic and pass data using the additional parameters.

Lets add a mechanism to publish error messages as well a standard error message:

var mySiteAjax = ( function( $ ) {
  var standardError = "Oops. Sorry about that.";
  return (
    function( params ) {
      var settings = $.extend({
        url:      '', 
        spinner:  undefined, 
        dataType: 'html',
        cache:    false,
        success:  function(){}
      }, params);

      var retries = 0;
      function ajaxRequest ( ) {
        $.ajax({
          beforeSend: function(){ 
            $(settings.spinner).show();
          },
          url: settings.url,
          dataType: settings.dataType,
          success: settings.success,
          complete: function(){
            $( settings.spinner ).hide();
          },
          error: function( xhr, tStatus, err ) {
            if( xhr.status === 401 || xhr.status === 403 ) {
              //redirect action here
            } else if ( xhr.status === 504 && !retries++ ) {
              ajaxRequest();
            }
            $(document).trigger( "ui-flash-message", 
              [{ message: standardError }] );
          } // end error handler
        }); // end $.ajax()
      }; // end ajaxRequest() 
      ajaxRequest();
    } // end getViaAjax()
  ); // end return statement
})(jQuery);

We’re publishing with a custom event named “ui-flash-message”. The .trigger() method takes in an array of parameters as a second argument. We chose to pass in a single hash (object literal) with our message attached.

Now that we’ve covered publishing, lets take a look at how a subscribe might be set up:

  // ... somewhere in a component that displays messages
  $(document).bind( "ui-flash-message",
    function(evt, data) {
      if(data.message) {
        showMessage(data.message);
      }
    };
   // ... 

Our subscriber must be set up before a message is published. In this case as long as our message component has already been loaded and the above code has been executed, then the component is waiting for a message to be published.

Load Notifications

Our old implementation of load notification was for a selector to be passed in and our Ajax component would handle the showing and hiding of a ‘spinner’. This technique is not ideal. The Ajax component has no business implementing specific behavior for spinners (such as using .show() and .hide()). It would be much better to use our publish/subscribe methodology to allow other components to handle the behavior.

// we 'define' undefined to alleviate concerns
// that someone may have done something stupid
// like this in code before this code executes:
// undefined = "Im now defined.";
// credit: Ben Alman (see comments)
var mySiteAjax = ( function( $, undefined ) {
  return (
    function( params ) {

      // use extend to merge our defaults with parameters
      // passed by function caller
      var settings = $.extend({
        url: "",
        spinner:  {}, 
          // use empty object if version 1.3.2-
          // credit: Ben Alman (see comments)
        dataType: "html",
        cache:    false,
        success:  function(){},
        errorMsg: "Oops. Sorry about that." 
          // credit: rmurphey (see comment below)
      }, params),
          retries = 0; // setting up retries variable
     // setting up a function that we can call recursively
     // to retry ajax calls 
     function ajaxRequest ( ) {
        alert("here");
        $.ajax({
          beforeSend: function() { 
            $( settings.spinner ).show();
          },
          url: settings.url,
          dataType: settings.dataType,
          success: settings.success,
          complete: function() {
            $( settings.spinner ).hide();
          },
          error: function( xhr, tStatus, err ) {
            if( xhr.status === 401 || xhr.status === 403 ) {
              //redirect action here
            } else if ( xhr.status === 504 && !retries++ ) {
              //make our recursive request
              ajaxRequest();
            } else {
              $(document).trigger( "ui-flash-message", 
                [{ message: settings.errorMsg }] );
            }
          } // end error handler
        }); // end $.ajax()
      }; // end ajaxRequest() 
      
      // call our ajax request function. notice above
      // that we only define the function. here we make
      // the original call.
      ajaxRequest();
        
    } // end getViaAjax()
  ); // end return statement
})(jQuery);

Now we can add a load notification component to our application, where we can handle showing and hiding spinners:

  // ... somewhere in a load component
  $(document).bind( "ui-load-start-message",
    function(evt, data) {
      $(data.spinner).show();
    });

  $(document).bind( "ui-load-end-message",
    function(evt, data) {
      $(data.spinner).hide();
    });
   // ... 

We now have much better separation of concerns. The Ajax component only publishes messages and isn’t concerned with implementation of a loading notification system.

I’ve set an example of this solution on a jsFiddle with a few use cases. Take a look at the example and feel free to play with the functionality on your own. Post in the comments if you find anything interesting!

Although you can create a message bus with jQuery custom events, there’s overhead and DOM interaction that isn’t necessary. Components exist today that allow for publish/subscribe to occur using only JavaScript. I encourage you to look for those components and use them for publish and subscribe interactions.

PostScript / Errata : There have been some good comments below, so we’ve made a few changes:

• The last full Ajax solution has been updated with suggestions and appropriate credit given.
• The jsFiddle has been updated to reflect those changes.
• Rebecca Murphey correctly pointed out that we are adding a variable to the global scope and that is something that should be minimized. A good approach would be to create a simple namespace (object) and add this utility library to that namespace. So the assignment at the top statement wouldn’t be mySiteAjax, but rather myCompanyNS.siteAjax or something similar. Note that you’ll need to ensure myCompanyNS exists and created an empty object if it does not already. We are still adding to the global scope, but one is better than many possible editions.

This is the first post of a multi-part series covering strategies that you might use to adopt HTML5 in your current or future corporate websites.

Introduction

HTML5 has many features which you’ve likely heard about or seen in various blog posts. With all of the publicity HTML5 has begun to hold weight as a marketing term and businesses are paying attention. In the near future we’ll see businesses want to leverage HTML5 to send a message that they are innovative and competitive.

Unfortunately many of the HTML5 features are not fully implemented in the newest versions of modern browsers. Older browsers lack any HTML5 support. This leaves us with a key question: “To what extent can I use HTML5 inside my enterprise application?”

In this blog series we will deliver a strategy you can use to start adopting HTML5 today. We’ll break down the strategy into the following posts:

• Part 1: Simplified Syntax & Semantic Elements
• Part 2: Form Enhancements
• Part 3: Local & Session Storage:

Client storage is no longer part of the HTML5 specification. Nevertheless we’ve decided to cover client storage as it is still popular as a topic in HTML5 discussions and is implemented in many of the modern browsers.

• Part 4: Video & Audio Elements

Simplified Syntax

Simplified DOCTYPE

Selecting a DOCTYPE is a necessary part of building a web page. There are many to choose from depending on how you compose your markup. Here is a list of several common DOCTYPEs you may have seen.

Old Way

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd">

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN"
  "http://www.w3.org/TR/html4/frameset.dtd">

Some developers and designers know what all of those DOCTYPEs mean, but I would guess that many don’t. Even if they knew what they meant it can even more difficult to understand which situations warrant each DOCTYPE. I’ve seen many situations in corporations where a developer copies and pastes a DOCTYPE from another document or will use a template and never think about it.

You can find more information about all of these DOCTYPEs and browser modes in an interesting write up from Henri Sivonen entitled Activating Browser Modes with Doctype.

New HTML5 Way

<!DOCTYPE html>

Thankfully this is a much simpler way to declare the DOCTYPE. We now have one DOCTYPE to chose from and it is short and sweet.

I’ve already mentioned that we can use this new DOCTYPE today. But what about older browsers? If clients use a browser that doesn’t recognize the HTML5 DOCTYPE then it will switch the content into standards mode and not quirks mode. Unless you have a specific reason to cater to browser modes, start using the new DOCTYPE declaration and take advantage of all the HTML5 goodness in your web application.

Simplified Encoding

HTML5 has also provided a simplified approach in the the way we indicate the character encoding used for the document.

Old Way

<meta http-equiv="Content-Type" 
  content="text/html; charset=utf-8">

New HTML5 Way

<meta charset="utf-8">

Interestingly current and older browsers already support this shortened syntax and we can use it right away in web applications. You can read more about this and other interesting details from Mark Pilgrim’s detailed explanation in Dive into HTML 5: What Does It All Mean?.

Simplified Script, Style, and Link elements

Another simplification in HTML5 is to make the type parameter optional on the script, style, and link elements. If we don’t provide the type attribute, then their defaults will be “text/javascript” for script tags and “text/css” for style and link tags. That means that we can leave out the type attribute in the majority of our uses of these elements. The great thing is that we can also use these techniques today in our web site and it will be supported in older browsers as well.

Old Way

<link rel="stylesheet" href="site.css" type="text/css" />
<style type="text/css">
  h1 { color: red; }
</style>
<script type="text/javascript" src="common.js"></script>

New HTML5 Way

<link rel="stylesheet" href="site.css" />
<style>
  h1 { color: red; }
</style>
<script src="common.js"></script>

Semantic Elements

There was a time when websites were commonly designed by using table element after table element to create complex layouts. Recently most designers heavily use the div element to float their way to equally complex and versatile layouts. HTML5 continues to transition web design by introducing new elements that make layouts more explicit.

New HTML5 Elements

Instead of overly using divs across our web application we can use the new HTML5 header, footer, article, section, nav, menu, and hgroup elements. These additions are more semantics than anything else. We could just as easily keep them as divs, but by using the new elements it makes your markup much more recognizable and easier to navigate.

Let’s take a simple scenario and see how it changes our markup. A common thing to include in a website is a header section. Normally we just use a div element and give it an id of “header”. However, we can just use the new semantic HTML5 element header instead.

Old Way

<div id="header">
  <h1>Welcome to My Blog</h1>
  <h2>Random Thoughts of a Programmer</h2>
</div>

JS Bin demo

New HTML5 Way

<header>
  <hgroup>
    <h1>Welcome to My Blog</h1>
    <h2>Random Thoughts of a Programmer</h2>
  </hgroup>
</header>

JS Bin demo

Other than simply just replacing the div element with a HTML5 header element, you might also notice that I introduced the idea of using a hgroup element. This is another new HTML5 element that is meant to group section headings (i.e. h1, h2, h3, etc…). The benefit of this is that the items in the hgroup don’t affect the overall outline of the document. This means that we can have a heading and sub-heading without changing the outline layout of the document.

Support for Older Browsers

As long as a client is using a browser that can understand HTML5 our page will render properly. When someone renders our updated website with a non-HTML5 complaint browser (such as Internet Explorer), there are some things that we’ll need to consider.

Current released versions of Internet Explorer can’t understand the new HTML5 elements, so we’ll need to add some additional JavaScript code to help. We can either create the HTML5 elements manually, use the HTML5 Shiv library, or use the jQuery Modernizr Plugin. Let’s cover each of these in more detail.

Creating HTML5 Elements Manually

We can always create the HTML5 elements manually. It isn’t difficult to do. We just need to call the createElement method off the of the document and pass the new element’s name. At that point, the browser will recognize the new element and be able to apply styles to it.

document.createElement("header");  
document.createElement("footer");  
//etc...

Creating HTML5 Elements with HTML5 Shiv

Why do something by hand when someone has already done it for us? Remy Sharp has created a library called HTML5 Shiv that already does the manual creation of HTML5 elements for us. The library is hosted on Google Code and we can integrate it in our project by including the following lines in the head section of the document.

<!--[if lt IE 9]>
<script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script> 
<![endif]-->

Creating HTML5 Elements with Modernizr

Another way that we can create the new HTML5 elements is to use the Modernizr JavaScript Library that Paul Irish and Faruk Ateş developed. The library creates all the new HTML5 elements we need while it is loading on the page. All we need to do is to include the script tag inside of the head element before we style our HTML5 elements.

<script src="modernizr-1.5.min.js"></script>

The library really does much more than just create the new HTML5 elements. Its purpose is to detect which features a client browser supports and allows us to develop your web application using progressive enhancement techniques. The scope of the plugin is much too large for this particular blog post, but I encourage you to check it out.

If you plan to use some of the advanced features of Modernizr, then it will already create the new HTML5 elements for you. If you don’t plan on customizing the experience based on the features of the current browser, then your best bet is to use the HTML5 Shiv or manually create the HTML5 elements yourself in code.

Styling the HTML5 Elements

Now that we’ve managed to make older browsers understand the HTML5 elements we need to focus on styling them correctly.

On creation the elements will have a default display style of “inline”. In order to style them correctly we’ll likely need to change their style to “block” instead. This can be done very easily with the following section of code.

header, footer, article, section, nav, menu, hgroup {  
  display: block;  
}  

Dynamic Insertion of HTML5 Elements

As, it turns out there is another caveat that we need to account for when using HTML5 elements in Internet Explorer. If we try to add HTML5 elements to the DOM dynamically it will not recognize the new element and therefore won’t style it appropriately.

Thanks to Joe Bartlett, there is a script called HTML5 innerShiv that will resolve this issue. You can find more information about usage of this script on Chris Coyier’s blog post entitled Fix Inserted HTML5 Content with HTML5 innerShiv.

For example, instead of just appending a new HTML5 element to the DOM, we would first wrap it in the innerShiv method.  

$('header').append(innerShiv("<nav><ul><li><a href="index.html">Home</a></li><li><a href="archives.html">Archives</a></li></ul></nav>"));

A Larger Before vs After Example using HTML5 Semantic Elements

To give you an idea of how the format of your page layout might change, I’ve included the following markup snippets. The first code snippet shows how you might organize the markup with HTML 4 and the following snippet shows how you might organize it with the new HTML5 semantic elements.

Old Way

<div id="header">
  <h1>Welcome to My Blog</h1>
  <h2>Random Thoughts of a Programmer</h2>
  <div id="navigation">
    <ul>
      <li><a href="index.html">Home</a></li>
      <li><a href="archives.html">Archives</a></li>
    </ul>
  </div>
</div>
<div id="sidebar">
  <h1>Twitter</h1>
  <blockquote cite="http://twitter.com/elijahmanor/status/20313555458">
  1st day at @appendTo I wrote Aug Tips for @ejquery website. Let me know if you found helpful, thnx http://j.mp/ejquery
  </blockquote>
</div>
<div id="posts">
  <div class="post">
    <div class="header">
      <h3>I'm looking for a Job</h3>
    </div>
    <div class="content">
      <p>Well, it's a funny story involving the FBI and IRS raiding...</p>
    </div>
    <div class="footer">
      <p>Published <time pubdate datetime="2010-07-08T12:21-07:00">8, July 2010</time>.</p>
    </div>
  </div>
</div>
<div class="footer">
  <ul>
    <li><a href="index.html">Home</a></li>
    <li><a href="archives.html">Archives</a></li>
  </ul>
</div>

New HTML5 Way

<header>
  <hgroup>
    <h1>Welcome to My Blog</h1>
    <h2>Random Thoughts of a Programmer</h2>
  </hgroup>
  <nav>
    <ul>
      <li><a href="index.html">Home</a></li>
      <li><a href="archives.html">Archives</a></li>
    </ul>
  </nav>
</header>
<aside>
  <h1>Twitter</h1>
  <blockquote cite="http://twitter.com/elijahmanor/status/20313555458">
  1st day at @appendTo I wrote Aug Tips for @ejquery website. Let me know if you found helpful, thnx http://j.mp/ejquery
  </blockquote>
</aside>
<section>
  <article>
    <header>
      <h3>I'm looking for a Job</h3>
    </header>
    <content>
      <p>Well, it's a funny story involving the FBI and IRS raiding...</p>
    </content>
    <footer>
      <p>Published <time pubdate datetime="2010-07-08T12:21-07:00">8, July 2010</time>.</p>
    </footer>
  </article>
</section>
<footer>
  <ul>
    <li><a href="index.html">Home</a></li>
    <li><a href="archives.html">Archives</a></li>
  </ul>
</footer>

Templates to Get You Started

Recently three separate projects have formed to help you get quickly started with HTML5 development in your next project. These projects address many of the concerns we’ve addressed above, but also touch on topics that we haven’t yet addressed.

• HTML5 Boilerplate by Paul Irish and Divya Manian – This template is probably the most comprehensive I’ve seen. It includes a host of features that you’ll need to start a new HTML5 web application. It addresses the concerns we’ve mentioned in this article, but it also handles mobile optimizations, optimal caching rules, progressive enhancement using Modernizr, CDN hosted jQuery with local failsafe, plus much more. You’ll most likely use this template as a starting point and then delete the things that may not be pertinent to your web application.
• HTML5 Reset – This template is slightly less comprehensive as the Boilerplate, but still provides a great amount of features that you’ll most likely need in your next HTML5 web application. Some of these features include cross-browser concerns, progressive enhancement using Modernizr, and many others.
• HTML5 Site Template by Doug Neiner – This template is the most simple alternative to the above two templates. It includes the concerns we’ve addressed in this article, but leaves out some of the extra stuff that you may not need in your web application. If you are overwhelmed with the amount of options from the first two templates, this might be a good place for you to start. Then, if you find yourself in need some of additional features, you can reference the above templates for their implementation.

Conclusion

Although not all browsers have the same level of support for HTML5, you can still start using many of the syntactical and semantic features that it provides. With a few considerations you can use these features without worrying about backwards compatibility.

As for future blog posts we will look at the following topics:

• Part 2: Form Enhancements
• Part 3: Local & Session Storage
• Part 4: Video & Audio Elements

Note: This is part two in a two part series on creating your first plugin. You can find part one here. In the series we’re creating a plugin to handle displaying, and also queuing a series of a messages.

Plugin Enhancements

The plugin we worked on in Part 1 focused on getting from a simple jQuery snippet to a reusable and scalable plugin. This post will give us an opportunity to look at two popular techniques that can be used in a variety of situations. We’ll introduce these techniques by adding two enhancements to our code. We will enable the queueing of messages for the message center, and will add features to automatically close the message after a certain time period.

Utilizing jQuery Queues

jQuery queues provide an explicit mechanism for running synchronous operations anywhere they might be necessary. Our current plugin is a great fit for queues. If a previous message is being displayed we would prefer that the new message be queued and displayed synchronously afterwards.

The queue portion of the API contains two methods that are used most of the time. .queue is utilized to add items to the queue. It can also be used to determine the number of items currently in a given queue. .dequeue is used to kick off our queue, or at any point move to the next callback in the queue.

DOM elements can have an arbitrary number of queues attached to them. Each queue can be identified by using a queue name when using the .queue and .dequeue methods. Internally, jQuery uses a queue on each element with a key fx for animations. You can attach callback functions to this queue as well.

These two JS Bin links (one and two) provide an introduction to queues and an example of queueing your own custom callbacks in the animation queue. The first example provides proof of the queueing functionality and shows a typical mistake that is made when combining queued and non-queued operations. Example two shows leveraging the animation queue with a custom callback to provide more desirable behavior.

It is important to recognize that the developer is directly responsible for controlling the dequeueing of callbacks. When dealing with a custom queue (a queue that is not the fx queue) you must explicitly move the queue to the next callback through the use of .dequeue or another mechanism that we will see in the example.

jQuery uses queueing internally to accomplish animations in a synchronous fashion.

So here’s what our new code looks like, enhanced with queueing:

function ($, undefined) {
  $.fn.myFlashMessage = function (params) {
    // Queue the message for view
    this.queue("myFlashMessage", function (next) {
      // Use extend to merge input parameters and defaults.
      // Use an empty object literal first as it is augmented
      // by the extend method.
      var settings = $.extend(
          {},
          {
            levelClass : 'info',
            animationSpeed : 1000
          },
          params);

      if (typeof(settings.message) === 'string') {
        // Now that we are using the jQuery queue method
        // the `this` keyword refers to a single DOM element.
        $(this)
          // Replace html with the message
          .html(settings.message)

          // Add the  appropriate class for the message level
          .addClass(settings.levelClass)

          // Click to close the message.
          // remove the handler once it has run.
          .one("click", function () {
            $(this)
              .slideUp(settings.animationSpeed, function(){
                // This will remove the class once slideUp is complete
                $(this).removeClass(settings.levelClass);

                // Next is a function passed in as a parameter
                // to our callback for queue. We can use it to move
                // to the next item in the queue if there is a
                // next function to execute.
                next();
              });
          })
          .slideDown(settings.animationSpeed);
      }
    });

    // Check the length of the queue
    // if the queue length is 1 and the queue
    // is hidden, we need to kick off the queue
    if (this.queue("myFlashMessage").length == 1 && this.is(":hidden")) {
      this.dequeue("myFlashMessage");
    }
  }
})(jQuery);

Live JS Bin Demo

A few important features to note in the enhancement:

• We’ve put all of our functionality for showing the message inside of a .queue method call. Because our functionality resides within a jQuery method callback function, the value of the keyword ‘this’ has changed in our next context. The .queue method will implicitly iterate over our jQuery collection, and the keyword this will now be set to a single DOM element for each function callback.
• With .queue the first argument passed in is a function. This function can be used to move to the next callback in the queue by executing the function. It is conventional to call the function next. Using this function to move to the next callback in the queue is an alternative to explicitly using .dequeue. This function also has the distinct advantage of the fact that that we don’t need to know the queue name. In certain cases you may create a callback function that doesn’t know the name of the queue it will be utilizing. In this case, using the first argument to move to the next callback in the queue might be your only option.
• We have some logic to determine whether we need to jump start the queue. In this case, we can look to see if the message center is hidden and there is only one callback in the queue (the one we just added), then we will need to start (or restart) dequeueing callbacks.

There are a few refactors/enhancements that would be good for the example. I encourage you to take the JS Bin example and try the following:

• Make the plugin more DRY by moving the queue name into a single spot. You could use an explicit variable, or perhaps add on the queue name as a parameter.
• This one’s a bit more challenging: if the queue is already showing, don’t slide up and then down as a transition. Instead do a quick fade out/fade transition.

Keep a queue pattern in mind when looking for solutions to your client-side problems. Other situations may crop up where synchronous operations are paramount. One great example seen in enterprise situations is the need to queue multiple Ajax requests in a certain order to perform a single operation; queues handle this task gracefully.

Automatically Closing the Message After a Timeout

A common scenario in client-side development when you want to force an event to fire even if the user has not triggered the event yet. In our case, we want to hide the message after a timeout period even if the user has not clicked on the message. JavaScript provides us with a setTimeout function, which will allow us to run a callback after an interval of of time. jQuery provides us with the awesome power of .trigger, which we can use to force our click event to fire.

One extra thing to consider: when our callback fires after the timeout, the user may have already progressed to a new message. We don’t want our callback triggering that message to close. We can solve this problem by storing a unique message id when we go to display our message. We can then look at this message id in our setTimeout callback function to determine if the user is still on the same message.

Our solution:

(function ($, undefined) {
  var queueName = 'myFlashMessage';

  $.fn.myFlashMessage = function (params) {
    // Queue the message for view
    this.queue(queueName, function (next) {
      // Use extend to merge input parameters and defaults.
      // Use an empty object literal first as it is augmented
      // by the extend method.
      var settings = $.extend(
          {},
          {
            levelClass : 'info',
            animationSpeed : 1000,
            timeout : 3000
          },
          params),
          messageId = String(+new Date);

      if (typeof(settings.message) === 'string') {
        // Don't repeat initializing a jQuery object
        // we can initialize once since in all methods below
        // the keyword 'this' refers to the same
        // DOM element
        var $this = $(this);

        // Set function to run and close on setTimeout if not already
        setTimeout(function () {
          // We need to make sure that the animation hasn't started,
          // the message isn't hidden, and that the message shown
          // is still the message we intend to close.
          if (!$this.is(":animated,:hidden") &&
            $this.data("messageId") == messageId) {
            // Now this is just cool.
            $this.trigger("click");
          }
        }, settings.timeout);

        $this
          // Add a messageId as metadata on the element
          .data("messageId",messageId)
          // Replace html with the message
          .html(settings.message)
          // Add the  appropriate class for the message level
          .addClass(settings.levelClass)
          // Click to close the message.  remove the handler once it has run.
          .one("click", function () {
            $this
              .slideUp(settings.animationSpeed, function () {
                // This will remove the class once slideUp is complete
                $this.removeClass(settings.levelClass);

                // Next is a function passed in as a parameter to
                // our callback for queue. We can use it to move to
                // the next item in the queue if there is a next
                // function to execute.
                next();
              });
         })
        .slideDown(settings.animationSpeed);
      }
    });
    // If there are no other messages and the message center
    // is hidden, then we need to kick off the queue.
    if (this.queue(queueName).length === 1 && this.is(":hidden")) {
      this.dequeue(queueName);
    }
  }
})(jQuery);

Live JS Bin Demo

Two important points to make in this example:

jQuery’s .trigger method is just cool

It is common to see a pattern of setting a callback to run after an interval, and then triggering an event. Since we’re dealing with the client-side, triggering an event in code is possible. jQuery makes it dead simple.

Using .data for item metadata

In our example we store each message id to messageId, passing in a new timestamp as our unique id. If you look into the documentation for .data you’ll notice that by using the same key every time of messageId, we’re overwriting the previous messageId stored by the last queued callback.

This snippet from line thirty-two is huge for understanding a key concept in JavaScript: $this.data('messageId') == messageId

In JavaScript functions have access to the context in which they were created. In our case, when we created our setTimeout callback, the context included access to messageId, which is the message identifier for the message we were currently queueing up. When the setTimeout callback is executed, we compare that value against $this.data('messageId') which is the currently displayed message identifier.

If you find yourself using setTimeout in bunches, consider using a plugin such as Ben Alman’s doTimeout.

And there we have it! A modified and scalable plugin. Feel free to extend the plugin as you please, and comment with some JS Bin examples if you find anything interesting or have questions.

Plugin prerequisites: overcoming myths and challenges

As a enterprise web developer I often found it challenging to shift my mindset from JavaScript coder towards plugin creator. Not that those opportunities weren’t there. Rather, I was stifled by a few factors that many enterprise developers face:

Code ownership and licensing concerns

Writing software that you are planning to release as open source can often conflict with corporate policies. Given that you are already using jQuery, the organization should already have some understanding of licensing policies. Or, at the very least, the organization has some trust in their developers understanding licensing policies.

Publishing plugins under open source licensing is something that most enterprises today should accept. However be sure to do due diligence with your superiors. Some points I would recommend making:

• Explain to them the power of the open source community. Developers giving back to the community is part of its strength.
• jQuery is making you a lot more productive. Giving back should be part of paying it forward.
• Point to plugins you have been able to use in your own development.
• Point out that you can garner feedback for your plugin which can help identify bugs and create a better solution for the enterprise.

As a worst case, plugins can be used as a pattern and not released as open source.

The “plugins are complex” myth

> Plugin developers are senior front-end web developers. Any typical plugin is without a doubt something I can never write. Additionally the most useful plugins must be quite complex.

My naivete was quickly broken when I did a little investigation.

Plugins are written by people who want to give back to the community. Newer developers are included in that group. Many useful plugins are not that complex in code. Some are fairly complex. Here are a few examples from the same developer. These are plugins I have used in code:

• Replace Text Plugin – not terribly complicated.
• Do Timeout Plugin – still not complicated.
• jQuery BBQ Plugin – you’re probably not going to write this one overnight.

I’d assert that all three of these plugins are incredibly useful. Yet only one has a high level of complexity.

Lack of ability to recognize code that could be a candidate for a plugin

On your path from a enterprise web coder to developer, this should be one of your goals. Identifying patterns that can be abstracted into plugins are a key to your journey to that ‘senior’ level. We’ll see utility libraries as another possibility for code reuse. But in both cases identifying a pattern is key.

Starter Code

Lets get rolling. Here is code I’ve seen in enterprise code used today. This is an implementation of the incredibly popular “flash message” or “message center” you see on sites like twitter and stack overflow:

$('#flashMessageCenter')
  .html('message for the user')
  .addClass('info')
  .click(function(){
    $(this)
      .slideUp(1000,function(){
        $(this).removeClass('info');
      });
  })
  .slideDown(1000);

Live jsbin demo

Super. This code seems to work pretty well, and took almost no time to write. The power of the jQuery side of the force…

This is where the light bulb needs to start going on. What are we doing here? We are displaying messages via some sort of message center for the user. Why not make this into something repeatable?

Generalizing the Code

We are going to travel a road to get to the plugin in order to bridge some common knowledge gaps. Lets start with a function that can take in some parameters.

var flashMessage = function(message, levelClass, animationSpeed) {
  if(message && levelClass && animationSpeed) {
    $('#flashMessageCenter')
      .html(message)
      .addClass(levelClass)
      .click(function(){
        $(this)
          .slideUp(animationSpeed,function(){
            $(this).removeClass(levelClass);
          });
      })
      .slideDown(animationSpeed);
  }
}

It would be better if we had defaults :

var flashMessage = function(message, levelClass, animationSpeed) {
  levelClass = typeof(levelClass) === 'string'
    ? levelClass
    : 'info';
  animationSpeed = typeof(animationSpeed) === 'number'
    ? animationSpeed
    : 1000;
  if(message) {
    $('#flashMessageCenter')
      .html(message)
      .addClass(levelClass)
      .click(function(){
        $(this)
          .slideUp(animationSpeed,function(){
            $(this).removeClass(levelClass);
          });
      })
      .slideDown(animationSpeed);
  }
}

Live jsbin demo

But wait, a bug already! Pay close attention to the .slideUp animation in the demo page. It’s always fast? Why?

We are attaching a new click handler each time this method is called. What we really want to happen is to attached the handler, let it run once, and then remove it. The next time the flashMessage is called a new handler will be attached with the new set of parameters. Fortunately jQuery gives us a shortcut to do exactly that:

var flashMessage = function(message, levelClass, animationSpeed) {
  levelClass = typeof(levelClass) === 'string'
    ? levelClass
    : 'info';
  var animationSpeed = typeof(animationSpeed) === 'number'
    ? animationSpeed
    : 1000;
  if(message) {
    //our message center div id
    $('#flashMessageCenter')
      //replace html with the message
      .html(message)
      //add the appropriate class for the message level
      .addClass(levelClass)
      //click to close the message.
      //remove the handler once it has run.
      .one('click',function(){
        $(this)
          .slideUp(animationSpeed,function(){
          //this will remove the Class
          //once slideUp is complete
            $(this).removeClass(levelClass);
          });
      })
      .slideDown(animationSpeed);
  }
}

We have a function that we can use to flash messages. But we can spruce this up even more.

I’m a huge fan of using object literals for parameter inputs. It will allow you to scale out your plugin in the future as thousands of people beg you to expand its functionality.

Again jQuery comes through. This time a utility function is our helper $.extend(). We can use $.extend() to merge an input object literal with a set of default object literals. Awesome!

var flashMessage = function(params) {
  //use extend to merge input parameters and defaults.
  //use an empty object literal first as it
  //is overwritten by the extend method.
  var settings = $.extend(
    {},
    {
      levelClass : 'info',
      animationSpeed : 1000
    },
    params);
  if(settings.message) {
    //our message center div id
    $('#flashMessageCenter')
      //replace html with the message
      .html(settings.message)
      //add the appropriate class for the message level
      .addClass(settings.levelClass)
      //click to close the message.
      //remove the handler once it has run.
      .one('click',function(){
        $(this)
          .slideUp(settings.animationSpeed, function(){
            //this will remove the Class
            //once slideUp is complete
            $(this).removeClass(settings.levelClass);
          });
      })
      .slideDown(settings.animationSpeed);
  }
}

Live jsbin demo

Notice that we don’t specify a message in our default object literal. We expect the user to pass in the message to the function.

Time for a plugin!

We are so close. We have a function that can be used. It takes in a sweet object literal. It also does two things that aren’t so nice:

• We are polluting the global namespace
• We are hard coding our selector for the flash message

Lets eliminate both at the same time. And produce our first plugin:

(function($,undefined){
  $.fn.myFlashMessage = function(params) {
    //use extend to merge input parameters and defaults.
    //use an empty object literal first as it is
    //overwritten by the extend method.
    var settings = $.extend(
      {},
      {
        levelClass : 'info',
        animationSpeed : 1000
      },
      params);
    if(typeof(settings.message) === 'string') {
      //our jQuery object
      this
        //replace html with the message
        .html(settings.message)
        //add the appropriate class for the message level
        .addClass(settings.levelClass)
        //click to close the message.
        //remove the handler once it has run.
        .one('click',function(){
          $(this)
            .slideUp(settings.animationSpeed, function(){
              //this will remove the Class once
              //slideUp is complete
              $(this).removeClass(settings.levelClass);
            });
        })
       .slideDown(settings.animationSpeed);
    }
  }
})(jQuery);

Live jsbin demo

A few more topics we just introduced:

We are using a self invoking anonymous function to create a plugin. That’s this pattern:

(function($, undefined){
...
})(jQuery);

The code creates a function without a name (not polluting the global space), and then immediately executes it. There are a few reasons to use this pattern. In our case, we use the function so the we can use the ‘$’ to mean ‘jQuery’, even if the ‘$’ variable is assigned to something else outside of this function. We also have a parameter ‘undefined’. Although we aren’t yet using ‘undefined’ in code yet I’ve added it for future revisions. Adding ‘undefined’ (yet passing in nothing as the parameter when executing the function) allows us to make sure someone didn’t do this sort of funny business in javascript previous to our function execution:

undefined = "I'm defined now!!!"; //legal

Next we have the actual assignment of the jQuery plugin:

$.fn.myFlashMessage = function(params)

This line assures that any future instance of the jQuery object will have access to that method. It’s a plugin. Nice!

Also looking at the code again I realized I could make a better comparison of the message by making sure it is of a type string.

And there we have it! A complete plugin.

In the next in the plugin post series we are going to continue to expand our plugin, including:

• Utilize queuing to retrieve and show multiple messages
• Automatically close the message center if not clicked in a certain time period
• Fix a few quirks we find in the current plugin

However, enterprises today require scalable solutions that gracefully handle errors, messages to the user, spinners, and other aspects of a rich user experience. In these series of posts we are going to step beyond the basic Ajax functionality and build a scalable library solution. In order to create a functional library you’ll need to understand the .ajax method and the parameters allowed. If you don’t already have a handle on .ajax, please visit the extremely useful api site for a quick primer.

For the purpose of these posts we are going to start with a pattern that is often seen in enterprise situations for ajax calls. In the below example we will attempt to retrieve data from the server with a GET http action via the jQuery.ajax method. The example will show an animated gif to identify loading (hereafter referred to as a spinner). We will retrieve HTML from the server, and apply that HTML to the DOM using jQuery’s .html() function. Finally we will hide our spinner on success or failure of the call by using the complete callback.

$('#mySpinnerId').show(); //show my spinner
$.ajax({
    url: 'myUrl',
    dataType: 'html',
    cache: false,
    success: function(myHtml) {
        $('#myHtmlContainer').html(myHtml);
      },
    complete: function() {
        $('#mySpinnerId').hide(); //hide the spinner
      }
  });

This functions great for our site, and we decide to move on to another Ajax request. Our second request:

$('#mySpinnerId2').show(); //show my spinner
$.ajax({
    url:      'myOtherUrl',
    cache:    false,
    dataType: 'json',
    success:  function(myJson) {
        // assumes a JSON structure that at least
        // includes {"value":"someValue"}
        $('#someId').text(myJson.value);  
      },
    complete: function() {
        // hide the spinner
        $('#mySpinnerId2').hide();
      }       
  });

Wonderful. This works as well. But it is not elegant code. How do we keep from repeating ourselves? Is there a better way to set up the loading animations? How do we handle errors?

Taking a Step Back

Before DRYing out this code, lets review the series of callbacks and functionality available to us with jQuery Ajax.

Ajax Settings (In API)

.ajaxSetup allow us to set up defaults for any of the parameters available in $.ajax. In our case, it would make sense to set up caching settings to be default

Ajax Event Broadcasting

A somewhat obscure documentation page lists out some incredibly important information. A quick summary:

Local vs Global Events

There are some events that are broadcasted for the specific ajax call, and other that are broadcast for any ajax call. Global event names always have the “ajax” prefix on the name. Local events do not.

Order of event broadcasting

There is a rich set of events that we can tap into for any of our ajax needs. In particular, we have events that will fire on any error, as well as firing on the completion of code.

Given that information, lets create an object that will handle a few things: 1) showing/hiding spinners 2) setting up defaults that are specific to our website.

var mySiteAjax = (function($){
  return {
    getViaAjax: function(params){
      var settings = $.extend({
        url:      '', 
        spinner:  undefined, 
        dataType: 'html',
        cache:    false,
        success:  function(){}
      }, params);

      $.ajax({
          beforeSend: function(){ 
            $(settings.spinner).show();
          },
          url:        settings.url,
          dataType:   settings.dataType,
          success:    settings.success,
          complete:   function(){
              $(settings.spinner).hide();
            }      
        });
    } 
  };
})(jQuery);

Your response might be “I thought you were creating an object? What is all of this?” Lets cover it in pieces:

Self executing (invoking) anonymous functions

function($){
  ...
})(jQuery);

This pattern is a well known one in javascript. This pattern allows us to create a function without a name (anonymously so that we don’t pollute the global scope), and then immediately execute it. Specifically we are using the pattern so that we can accept jQuery as a parameter to a function, but use the variable ‘$’ internally in the function. This allows us to ensure that if any third party library were attached and this code was in a library attached afterwards, it would still behave as expected.

jQuery.extend()

$.extend is another piece of jQuery beauty that allows us to set up default parameters very easily.

return object literal

Note that we are creating an function and then immediately executing that function. Thus whatever is returned by the function will be assigned to mySiteAjax. In this case, it is an object literal which includes a single function – getViaAjax.

Usage

Given our two example above, here is the usage:

Example 1:

mySiteAjax.getViaAjax({
  spinner : '#mySpinnerId',
  url : 'myUrl',
  success : function(myHtml){
      $('#myHtmlContainer').html(myHtml);
    }
});

Example 2:

mySiteAjax.getViaAjax({
  spinner : '#mySpinnerId',
  url : 'myUrl',
  dataType: 'json',
  success : function(myJson){
      $('#someId').text(myJson.value);  
    }
});

We’ve saved ourselves some code. But more importantly, we’ve started down the path of creating a library that can handle all of our site’s ajax needs in an elegant manner.

Over this series, we will continue to expand our mySiteAjax object to include more behavior. Next up, we’ll cover a error handling strategy.

• Part 2: Handling errors and global loading animations
• Part 3: JSON wrapper
• Part 4: Putting it all together