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.

appendTo launched in October of 2009 with Mike Hostetler and myself having the vision of providing enterprise grade services for jQuery. Both of us have a long history of experience in the large enterprise as well as startups. We’ve worked in the trenches and have seen first hand the challenges that organizations face.

appendTo has a diverse set of enterprise experience with the 7 additional employees we’ve hired: Levi DeHaan, Scott González, Elijah Manor, Doug Neiner, Andrew Powell, Leah Silber, and Andrew Wirick. Of which we’ve worked at, contracted for, and consulted with several large organizations such as: AOL, Apple, Blue Cross Blue Shield (NE), BMW, Bureau of Land Management (BLM), Chrysler, CSC (Computer Sciences Corporation), Ford, GM, Guardian Life, IBM, Microsoft, Motorola, National Instruments, National Renewable Energy Lab (NREL), Union Pacific Railroad, Xcel Energy, and Zurich International.

Every organization is different, but core themes naturally emerge. In July of this year, appendTo launched EnterprisejQuery.com to cater to this audience and it has sparked a debate about “what is the enterprise” and “does jQuery fit in the enterprise”.

What is the Enterprise?

So far, there have been a number of definitions of “what the enterprise is” and while they make a good attempt, they’re too focused. The point missing from the discussion thus far is that the enterprise is comprehensive and cross discipline. It’s not solely large applications or large teams, it’s any company that is using it’s resources (people, time and money) to build applications and tools for the desktop, web and/or mobile platforms.

The intended audiences of these applications vary drastically between companies with some corporations developing almost exclusively for an internal audience. These organizations traditionally have multiple stakeholders and development decisions encompass varying agendas and goals. This is why EnterprisejQuery.com covers and will continue to cover basic and advanced jQuery techniques.

Does jQuery have a place in the Enterprise?

A little more background first. jQuery has seen adoption in the enterprise since its first release. Initially it was a grassroots movement with developers adopting jQuery because it solved their problems. It’s important to point out that these problems were (and continue to be) integration focused. Enterprise already had (and has) existing tools and architectures in place. Then starting in 2008, the next change took place in which the jQuery movement shifted from grassroots to corporate policy. jQuery gained critical mass to the point in which management became aware of the need to standardize, as many did and did so with jQuery.

So what about some of the technical challenges presented such as code organization, best practices, and large scale projects? jQuery fits in the enterprise stack well, even in large applications, in that it does not preclude finding the right solutions to these problems. jQuery fits the needs for all of these because it integrates as you see fit. One question was raised as to why you need jQuery with additional components to integrate and saw it as a weakness, making an argument that jQuery should provide the entire “stack”.

It’s a fundamental philosophical difference in that jQuery is focused on doing the best at a core competency. Just like in a *nix environment you can take a series of discrete tools and chain them together via pipes. It integrates however your environment is established. If a library requires too many changes to adopt, it becomes a greater risk than a help to the enterprise. Our vision is to build and endorse tools that are loosely coupled and can be integrated into an existing enterprise solution.

So where is jQuery and the Enterprise at today? jQuery is deeply embedded in projects, applications and the culture of the enterprise. It fills a need and solves the problems that developers face in a non-overbearing way. It provides a consistent goal and approach in leading an organization’s development strategy. It does just enough, and leaves the rest up to the developer.

What to expect from EnterprisejQuery.com

EnterprisejQuery.com seeks to cover enterprise topics comprehensively. Though not all enterprise users have large front-end application concerns, we intend to address those topics. Many have more basic concerns and we mean to address those as well. This is why some posts you’ll walk away saying “I knew that!” and others you’ll have to read multiple times. As the amount of site content grows, we will make it easier for you to discern as an enterprise user which material suits your current needs.

So in summary, jQuery is in the enterprise, it has been and will continue making an impact. Enterprises differ greatly, and cover a wide spectrum of disciplines. We will be addressing this space comprehensively. Is there a topic your facing that you’d like to see covered? Drop us an e-mail at enterprise-jquery@appendto.com.

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

The languages generally used on the server-side of enterprise development have static typing. The number and type of each parameter must be declared. In contrast JavaScript is considered a language with dynamic typing. JavaScript parameters do not have to be tied to a specific type at compile time. Additionally server-side languages do not include any of the ‘free’ parameters we get in JavaScript (more discussion on these parameters below).

A great example of the gap between common server-side languages and JavaScript is the .each method. To use this method you supply a function which will be executed against each element within the jQuery wrapped collection.

My first encounter with .each was similar to this:

//...
// note: this example is archaic as of 1.4 release
// please use function callback with .text instead!
$('.someClass').each(function() {
  var $this = $(this);
  $this.text($this.text() + " some extra text");
});
//...
$('.someClass').each(function(idx,val) {
  if(!(idx % 3)) { //modulus : will be true
                        //on every third element
    $(val).somejQueryMethod();
  }
});
//...

JS Bin demo

In my first encounter with this code I stared with a combination of wonder and horror. How are there two anonymous functions that each have different number of parameters? How could jQuery possibly invoke each of these functions successfully?

The secret isn’t jQuery’s. These snippets work because of the way JavaScript handles parameters.

In this post we are going to take a look at some of the language semantics for functions parameters. We’ll then use that knowledge to come up with a parameter passing pattern that is incredibly useful and expressive.

Javascript Function Parameters

There is an incredible amount of freedom in parameter passing in JavaScript. This flexibility comes from a few key concepts regarding JavaScript function parameters:

Declaring and passing parameters is optional in JavaScript

I could declare a function with five named parameters but the caller of that function does not have to pass in any parameters. Conversely I could declare a function with zero named parameters and the caller could pass in five when invoking the function.

var myFunction1 = function(param1, param2, param3) {
  // ...
};

myFunction1();
// myFunction1 will execute when invoke, even though
// there is a parameter mistmatch

var myFunction2 = function() {
// ...
};

myFunction2("here", "are", "some", "parameters");
// myFunction2 will execute when invoked even though there
// are no named parameters in the function declaration

JS Bin Demo

Every function includes an arguments array-like object as a parameter

You actually never have to declare parameters when declaring a function in JavaScript. Arguments passed in during function invocation will all be stored in a variable with the keyword arguments. arguments is an array-like object which you can use to retrieve and use all parameters in the order they were passed in. You could use this array to utilize an indefinite number of parameters:

var myAdder = function(){
  var i = 0, result = 0;
  //we can check to see if the object in the arguments
  //'array' exists. we also check the type of the input
  while(arguments[i] && typeof arguments[i] === 'number' ) {
    //add it and continue
    result += arguments[i];
    i++;
  }
  return result;
}

myAdder(1,2,3,4,5); //15

JS Bin Demo

Every function also gets a parameter with the keyword ‘this’

We are not going into the details of the this operator in this post. It is sufficient to know that the this operator exists and its meaning depends on how the function is invoked.

Parameters can be any type when passed in to a function

The caller of a function could pass in any type for your parameters. For example, if you have a function which expects a single parameter the caller may choose to pass in: * nothing (would be undefined in your function) * a function object * a string * a number * any other object It is the responsibility of the function to detect and react to these different types. That may seem a bit too loose at first. Yet it opens up incredible expressiveness that allows jQuery to do much of the magic it performs today.

Consider when we use the jQuery (or the alias $) function with one parameter. This core piece of jQuery acts radically different depending on what we specify as the first argument when invoking the function. Here are three examples of passing in different types of objects to the jQuery function and how the function behaves:

$('.myClass li')
// here the jQuery function will determine
// that the first argument is a string.  It will
// use the selector engine (sizzle) to determine
// which DOM elements fit the selector, and
// will return a jQuery object with a collection
// of those dom elements

$(document);
// jQuery recognizes that we have passed
// in a DOM Element.  The library returns
// a jQuery object with the collection of 1
// element - the DOM element.

$(function(){
  //...
});
// jQuery recognizes that we have passed
// in a function.  It binds the function to
// be fired when the DOM is ready
// this code results in the same behavior as
// using $(document).ready(function(){...

This isn’t function overloading. JavaScript has no function overloading in the traditional sense. Yet jQuery radically changes behavior based on the type of our input parameters.

Parameter Strategy: Object Literals

A typical starting point when creating named functions in JavaScript is trying to use a list of parameters. This approach feels familiar to creating functions in statically typed languages. Yet challenges are immediately hit when using a series of named parameters. If the bulk of your arguments are optional you can run into nearly insurmountable issues:

var myUtilityFunction = function(arg1, arg2, arg3) {
  //how do we make argument1 or argument2 optional?
};

This pattern can work for methods were you have a few parameters and all of them are required. Anytime you extend the function though it becomes more difficult to manage optional parameters. If all of the arguments are the same type it may be impossible to have certain arguments be optional.

A much better pattern would be to pass in a single object literal. In that case we can always look for the specific parameters by name within the object passed in and take action if the object property does not exist:

var myUtilityFunction = function(args){
  // this statement is called a ternary statement
  // the first portion is a condition. if the
  // condition evaluates to  true, the next portion (after
  // the question mark) will run.  Otherwise the
  // second statement (after the colon) will run
  var param1 = args && args.param1 !== undefined
    ? args.param1
    : "my default 1";
  var param2 = args && args.param2 !== undefined
    ? args.param2
    : "my default 2";
  // ...
};
//...
//usage
myUtilityFunction({
  param1 : "my first param",
  param2 : "my second param"
});

While this pattern is functional we have repeating checking of each parameter. As this function grows our parameter checking would become even uglier. A better solution would be to have a default object literal to merge with the object literal passed in by the caller.

Using Extend to Merge Object Literals

As usual, jQuery provides a great feature to allow us to take object literals and combine them with our defined inline defaults. jQuery.extend takes in any number of objects and combines them into a single object. In our case we will use jQuery.extend to merge a default object literal with the parameter object:

var myFunction = function(args) {
  var parameters = $.extend(true, {default1: 'hello',
    default2: 'world'},args);
};

JS Bin demo with Usage

In this example the first parameter lets extend know to do a deep copy of all of the objects.

This provides us with a great solution. If your function can run entirely on defaults then the caller doesn’t have to pass in anything. Additionally we can scale our function by adding extra parameters with defaults which will not break any current code or add additional checks!

Allowing Arbitrary Number of Object Literals

There are reasons that the caller of our function may have multiple object literals they would like to pass in to our function. For example the calling function may have defaults and passed in parameters. With our current solution, the caller would need to combine those multiple objects using jQuery.extend, and then call our function, which again uses jQuery.extend.

Recall that JavaScript methods can use any number of parameters. If we use the our arguments variable that we get for free with each function, we should be able to combine many object literals together. But how can we use jQuery.extend and the method our own arguments object? An attempt to use jQuery.extend and just passing in our arguments object will not give us our intended behavior:

var myFunction function(){
  var parameters = $.extend.apply(true, arguments);
  // parameters == ?
  // $.extend with only a single object as in this
  // example has special meaning. I encourage
  // you to investigate. But it is not what we want
  // in our case.
};

JS Bin Demo

JavaScript provides us with a solution. apply is a method that is available on any function. The first parameter of apply is what the keyword this should reference when the function is invoked. The second parameter is an array (or array-like) of the parameters the function will receive in arguments. apply is letting us set up the conditions around which a function is invoked.

In our case we can use apply to set the arguments object of jQuery.extend to be the arguments passed in by our caller:

var myFunc = function() {
  // the apply invocation pattern allows us to
  // pass arguments directly on to the jQuery.extend
  // method.  The first parameter is what the 'this'
  // keyword will be set to in the function
  // the second parameter will set the arguments
  // for the function
var options = $.extend.apply( null, arguments );
  // ..
  }
}

JS Bin Demo with Usage

We are close but we are missing our deep copy for jQuery.extend and our defaults. Since arguments is not a true array we can’t do simple concatenation and add true and our default object as the first two parameters. However we can turn the arguments into an array and then concatenate with our extra parameters:

var myFunc = function() {
  // we can use Array's native slice method to
  // 'convert' the arguments in to a true array
  var args = Array.prototype.slice.call(arguments, 0),
        defaults  = {
          // ...
        },
  // the apply invocation pattern allows us to
  // pass arguments directly on to the jQuery.extend
  // method.  The first parameter is what the 'this'
  // keyword will be set to in the function
  // the second parameter will set the arguments
  // for the function
  options = $.extend.apply( null, [true, defaults].concat(args) );
  // ...
}

JS Bin Demo with Usage

Array.prototype.slice allows us to return a true array from our arguments object. We can then create a new array which only includes true and our defaults and then concatenate our arguments on to that new array. We then pass that array in as the arguments for jQuery.extend.

The idea for this solution came from @scott_gonzalez and the jQuery UI team. You can see their implementation of this solution on this jQuery UI GitHub page. The difference in their solution is that they are accounting for the first parameter possibly being a string and not part of the object literals. jQuery UI’s use of this pattern also means that you can pass in any number of object literals to a jQueryUI method (like draggable() or datePicker() ) and the merging will be completed for you.

We now have a great pattern that is extremely flexible. Any number of object literals can come from the caller and we can easily merge them in one place. We can also merge in our default parameters. New parameters with defaults can be added without breaking any caller code.

It feels good to use the powerful parts of a language.

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.

Much of the development that appendTo does focuses on front-end development tied to RESTFUL web services. As such we’re able to spec out the service contract and data format at the beginning of a project and develop the front-end interface against mock data while the back end team builds the production services.

I originally developed this plugin for appendTo back in March of this year and our team has been using it in all of our projects since. appendTo is committed to sharing our tools and best practices with the community so it’s with much excitement that we’re releasing this plugin. (A sneak peek was available to the Silicon Valley JavaScript Users Group and those that attended our OSCON tutorial)

Plugin Overview

Abstract: The mockjax plugin is a development and testing tool for intercepting and simulating ajax requests made with jQuery with a minimal impact on changes to production code.

• Project Home: http://github.com/appendto/jquery-mockjax
• Raw Source: http://github.com/appendto/jquery-mockjax/raw/master/jquery.mockjax.js
• Issue Tracking: http://github.com/appendto/jquery-mockjax/issues

Overview: Your First Mock

Our first example will be for a simple REST service for a fortune app with the REST endpoint being /restful/fortune which returns the following JSON message:

{ "status": "success",
  "fortune" : "Are you a turtle?"
}

To pull the fortune into our page, we’d use the following HTML & jQuery code:

<!DOCTYPE html>
<html>
  <head>
    <title>Fortune App</title>
    <script src="http://code.jquery.com/jquery-1.4.2.min.js"></script>
  </head>
<body>
  <div id="fortune"></div>
</body>
</html>

$.getJSON('/restful/fortune', function(response) {
  if ( response.status == 'success') {
    $('#fortune').html( 'Your fortune is: ' + response.fortune );
  } else {
    $('#fortune').html( 'Things do not look good, no fortune was told' );
  }
});

At this point if we were to run this code it would fail since the REST service has yet to be implemented. This is where the benefit of the Mockjax Plugin starts to pay off. The first step in using Mockjax is to include the Plugin (you can grab the latest source from github) Once you have that included, you can start intercepting Ajax requests and mocking the responses. So let’s mock out the service by including the following code:

$.mockjax({
  url: '/restful/fortune',
  responseTime: 750,
  responseText: {
    status: 'success',
    fortune: 'Are you a turtle?'
  }
});

Defining a JOSN string inline requires a JSON.stringify method to be available. For some browsers you may need to include json2.js

What the plugin does at this point is replace the $.ajax method with a wrapper that transparently checks the URL being requested. If the URL matches one defined by $.mockjax(), the plugin intercepts the request and sets up a mock XMLHttpRequest object before executing the jQuery.ajax handler. Otherwise, the request is handed back to the native $.ajax method for normal execution. One benefit in this implementation detail is by simulating the XMLHttpRequest object, the plugin continues to make use of jQuery’s native ajax handling.

As you write code to mock responses, there’s great value in there are no modifications required to production code. The mocks can be transparently inserted. This provides easy integration into most frameworks by including the plugin and mock definitions through your build framework. It’s also possible to include it at run time by listening for a flag query string flag and injecting the plugin and definitions.

Mockjax in Depth

Now let’s look at the various approaches to defining mocks as offered by the plugin. The sections below feature an extensive overview of the flexibility in Mockjax and creating responses.

Data Types Available for Mocking

jQuery is able to handle and parse Text, HTML, JSON, JSONP, Script and XML data formats and Mockjax is able to mock any of those formats. Two things to note, depending upon how you Mock out JSON and JSONP you may need to include json2.js for the JSON.stringify() method. Additionally if you mock XML inline, you’ll need to include the xmlDOM plugin that transforms a string of XML into a DOM object. If you use the proxy approach outlined below, there’s no need to include either the JSON or XMLDOM plugins.

Step 1. Define the URL

The first thing you need to do when mocking a request is define the URL end-point to intercept and mock. As with our example above this can be a simple string:

$.mockjax({
  url: '/url/to/rest-service'
});

or contain a * as a wildcard:

$.mockjax({
  // Matches /data/quote, /data/tweet etc.
  url: '/data/*'
});

or a full regular expression:

$.mockjax({
  // Matches /data/quote, /data/tweet but not /data/quotes
  url: /^\/data\/(quote|tweet)$/i
});

Step 2. Define the Response

The second step is to define the type of response. The two main properties you’ll be dealing with are either responseText or responseXML. These properties mirror the native XMLHttpRequest object properties that are set during a live response. There are three different patterns for specifying the responses: Inline, Proxy, and Callback.

Inline Responses

A simple text response would be:

$.mockjax({
  url: '/restful/api',
  responseText: 'A text response from the server'
});

A simple XML response would be:

$.mockjax({
  url: '/restful/api',
  // Need to include the xmlDOM plugin to have this translated into a DOM
  responseXML: '<document><quote>Hello world!</quote></document>'
});

As you can quickly see, if you have a significant amount of data being mocked this becomes unwieldy. So that brings us to the next pattern of proxying.

Proxy

In this example below, the Mockjax plugin will intercept requests for /restful/api and redirect them to /mocks/data.json.

$.mockjax({
  url: '/restful/api',
  proxy: '/mocks/data.json'
});

Callback

In the final response pattern, we can define a callback on the response property and have it set responseText or responseXML as needed.

$.mockjax({
  url: '/restful/api',
  response: function() {
    this.responseText = 'Hello world!';
  }
});

Advanced Mocking Techniques

At this point we’ve looked at a series of basic mocking techniques with Mockjax and will now unpack some of the additional functionality contained in the plugin.

Simulating Response Time and Latency

Simulating network and server latency for a mock is as simple as adding a responseTime property to your mock definition:

$.mockjax({
  url: '/restful/api',
  // Simulate a network latency of 750ms
  responseTime: 750,
  responseText: 'A text response from the server'
});

Simulating HTTP Response Statuses

It’s also possible to simulate response statuses other than 200 (default for Mockjax) by simply adding a status property.

$.mockjax({
  url: '/restful/api',
  // Server 500 error occurred
  status: 500,
  responseTime: 750,
  responseText: 'A text response from the server'
});

Setting the Content-Type

You can set the content type to associate with the mock response, in the example below, we’re setting a json content type.

$.mockjax({
  url: '/restful/api',
  contentType: 'text/json',
  responseText: {
    hello: 'World!'
  }
});

Setting Additional HTTP Response Headers

Additional HTTP Response Headers may be provided by setting a key in the headers object literal:

$.mockjax({
  url: '/restful/api',
  contentType: 'text/json',
  responseText: {
    hello: 'World!'
  },
  headers: {
    etag: 'xyz123'
  }
});

Force Simulation of Server Timeouts

Because of the way Mockjax was implemented, it takes advantage of jQuery’s internal timeout handling for requests. But if you’d like to force a timeout for a request you can do so by setting the isTimeout property to true:

$.mockjax({
  url: '/restful/api',
  isTimeout: true
});

Dynamically Generating Mock Definitions

In some situations, all of your REST calls are based upon a URL schema. Mockjax has the ability for you to specify a callback function that is handed the $.ajax request settings. The callback function may then either return false to allow the request to be handled natively, or return an object literal with relevant Mockjax parameters set. Below is an example that rewrites all Ajax requests to proxy to static mocks:

$.mockjax(function(settings) {
  // settings.url == '/restful/<service>'
  var service = settings.url.match(/\/restful\/(.*)$/);
  if ( service ) {
    return {
      proxy: '/mocks/' + service[1] + '.json'
    };
  }
  return;
});

Dynamically Generating Mock Responses

It’s also possible to dynamically generate the response text upon each request by implementing a callback function on the response parameter:

$.mockjax({
  url: '/restful/webservice',
  dataType: 'json',
  response: function(settings) {
    this.responseText = { say: 'random ' + Math.random() };
  }
});

Globally Defining Mockjax Settings

It’s also possible to define the global defaults for all Mockjax requests by overwriting the $.mockjaxSettings object. By default the settings are as follows:

$.mockjaxSettings = {
  status:        200,
  responseTime:  500,
  isTimeout:     false,
  contentType:   'text/plain',
  response:      '', 
  responseText:  '',
  responseXML:   '',
  proxy:         '',
  lastModified:  null,
  etag:          ''
};

To overwrite a particular settings such as the default content-type, you would do the following:

$.mockjaxSettings.contentType = 'text/json';

Removing Mockjax Handlers

Remove all mockjax handlers:

$.mockjaxClear();

Remove Single Mockjax Handler

var id = $.mockjax({
   ...
});
$.mockjaxClear(id);

Conclusion

So there you have it, Mockjax unpacked! There are a number of additional posts in the pipeline surrounding this topic and how to apply and integrate it with your project. So stay tuned! In the meantime, the plugin code is readily available on github and feel free to report any issues you find in the plugin's github issue tracker. Enjoy!

$(function(){
  $('input.date:text').datepicker();
  //...
});

Just to review, the selector we are using could be translated into words as ‘Select all elements that have a class named date and are also inputs of type text’.

This is functional – except when we get into dynamic additions of elements. As we utilize Ajax to give a richer experience, we run the risk of including a input of type text with the date class on it. This often leads one to start trying to configure UI widgets in the success callback of an Ajax request:

$(function(){
  $('input.date:text').datepicker();
  //...
});

$.get('somePartialServerPage.html', function(data){
  $('#ajaxContainer')
    .html(data)
      .find('input.date:text')
        .datepicker()
        .end()
      .find('.myDraggableClass')
        .draggable({
          // config draggable here
        });
  });
});

This could certainly be refactored to be a better solution. We could use named functions to make sure we are DRY, or we could use .ajaxSuccess() to handle adding the behavior with a single global event handler. Yet still the solution is not elegant and could be prone to many wasteful lookups.

This looks like a job for .live(). Attaching behavior to dynamically added elements is the most direct use case for .live(). But with interactions/widgets, often the widgets must be set up before interaction with the element occurs. Live (just like .bind()) presents us with no ways to do this directly.

However, with a little creativity and a good understanding of UI events we can find interesting ways of using live to attach widgets and interactions dynamically to elements.

Scenario 1: Draggable

Draggable interactions are fairly straightforward and familiar to most. When the users presses the mouse down, the draggable behavior will begin until a point where the user release the element by using a mouse up. Thus we must have the draggable behavior configured before the mousedown occurs. Can we use any events on that element to accomplish this task?

In order to be in a position to mousedown, the mouse will first have to fire a few other events. In particular we know that mouseenter and mouseover must fire previous to any mousedown interaction. If we use that event to configure behavior, we can ensure any element is draggable – even those dynamically added!

$('.myDraggableClass').live('mouseenter',function(){
  $(this).draggable({
    // configure draggable here
  });
});

Now we must consider that multiple mouse enter events could fire as the user’s mouse exits and re-enters the elements. It would be prudent of us to check to see if the draggable interaction is already configured on that element. Looking under the hood, jQuery draggable add metadata to the element using jQuery’s .data() method. We can use this to our advantage to check and see if the behavior is set up:

$('.myDraggableClass').live('mouseenter',function() {
  var $this = $(this);
  if(!$this.is(':data(draggable)')) {
    $this.draggable({
      // configure draggable here
    });
  }
});

Not only does this solution ensure that we will have draggable behavior attached to all elements, but it also scales quite well. If we were to have hundreds of images that were in the dom and supposed to be draggable, sluggish behavior could present itself. Here we only configure draggable interactions on those elements that are realistic candidates for the behavior.

Scenario 2: Datepicker

Datepicker presents a different challenge. While mouseenter will work in some cases, input boxes can gain focus and the datepicker behavior should begin without any mouse interaction. Fortunately we can account for this by adding the datepicker as through the focus in event. On top of that, the datepicker will immediately fire for us.

  $('input.date:text').live('focusin', function() {
    var $this = $(this);
    if(!$this.is(':data(datepicker)')) {
      //this will attach a datepicker control & datepicker will immediately fire
      $this.datepicker();
    }
  });

We now have datepicker functionality on any appropriate input text element whether it is added at the initial page load or dynamically.

Improving performance with delegate

One possible way to improve performance would be to scope the context of the “live listeners” with the use of .delegate(). With .live() events the way they are written above the event propagation will occur up to the document level before the handlers will be called. With delegate (or scoping live) we can catch the event happening lower in the dom tree. For example let us say that the draggable events will all be occurring on the page within a container element. This is a great candidate to use delegate to achieve the same behavior as above but with better performance. This can also be a great solution where different regions on the page have draggable elements, but in each region you want a different configuration of draggable:

$('#myContainer').delegate('.myDraggableClass', 'mouseenter', function() {
  var $this = $(this);
  if(!$this.is(':data(draggable)')) {
    $this.draggable({
      // configure draggable here
    });
  }
});