Blog: Archive for June, 2007

Global variables are evil. Within YUI, we use only two globals: YAHOO and YAHOO_config. Everthing in YUI makes use of members within the YAHOO object hierarchy or variables that are scoped to such a member. We advise that you exercise similar discipline in your own applications, too.

Douglas Crockford has been teaching a useful singleton pattern for achieving this discipline, and I thought his pattern might be of interest to those of you building on top of YUI. Douglas calls this the “module pattern.” Here’s how it works:

1. Create a namespace object: If you’re using YUI, you can use the YAHOO.namespace() method:

YAHOO.namespace("myProject");

This assigns an empty object myProject as a member of YAHOO (but doesn’t overwrite myProject if it already exists). Now we can begin adding members to YAHOO.myProject.

2. Assign the return value of an anonymous function to your namespace object:

YAHOO.myProject.myModule = function () {

	return  {
		myPublicProperty: "I'm accessible as YAHOO.myProject.myModule.myPublicProperty.",
		myPublicMethod: function () {
			YAHOO.log("I'm accessible as YAHOO.myProject.myModule.myPublicMethod.");
		}
	};

}(); // the parens here cause the anonymous function to execute and return

Note the very last line with the closing curly brace and then the parentheses () — this notation causes the anonymous function to execute immediately, returning the object containing myPublicProperty and myPublicMethod. As soon as the anonymous function returns, that returned object is addressable as YAHOO.myProject.myModule.

3. Add “private” methods and variables in the anonymous function prior to the return statement. So far, the above code hasn’t bought us any more than we could have gotten by assigning myPublicProperty and myPublicMethod directly to YAHOO.myProject.myModule. But the pattern does provide added utility when we place code before the return statement:

YAHOO.myProject.myModule = function () {


	//"private" variables:
	var myPrivateVar = "I can be accessed only from within YAHOO.myProject.myModule.";
	
	//"private" method:
	var myPrivateMethod = function () {
		YAHOO.log("I can be accessed only from within YAHOO.myProject.myModule");
	}


	return  {
		myPublicProperty: "I'm accessible as YAHOO.myProject.myModule.myPublicProperty.",
		myPublicMethod: function () {
			YAHOO.log("I'm accessible as YAHOO.myProject.myModule.myPublicMethod.");

			//Within myProject, I can access "private" vars and methods:
			YAHOO.log(myPrivateVar);
			YAHOO.log(myPrivateMethod());

			//The native scope of myPublicMethod is myProject; we can
			//access public members using "this":
			YAHOO.log(this.myPublicProperty);
		}
	};

}(); // the parens here cause the anonymous function to execute and return

In the codeblock above, we’re returning from an anonymous function an object with two members. These members are addressable from within YAHOO.myProject.myModule as this.myPublicProperty and this.myPublicMethod respectively. From outside of YAHOO.myProject.myModule, these public members are addressable as YAHOO.myProject.myModule.myPublicProperty and YAHOO.myProject.myModule.myPublicMethod.

The private variables myPrivateProperty and myPrivateMethod can only be accessed from within the anonymous function itself or from within a member of the returned object. They are preserved, despite the immediate execution and termination of the anonymous function, through the power of closure — the principle by which variables local to a function are retained after the function has returned. As long as YAHOO.myProject.myModule needs them, our two private variables will not be destroyed.

4. Do something useful with the pattern. Let’s look at a common use case for the module pattern. Suppose you have a list, some of whose list items should be draggable. The draggable items have the CSS class draggable applied to them.

<!--This script file includes all of the YUI utilities:-->
<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/utilities/utilities.js"></script>

<ul id="myList">
	<li class="draggable">Item one.</li>
	<li>Item two.</li> <!--item two won't be draggable-->
	<li class="draggable">Item three.</li>
</ul>

<script>
YAHOO.namespace("myProject");
YAHOO.myProject.myModule = function () {

	//private shorthand references to YUI utilities:
	var yue = YAHOO.util.Event,
		yud = YAHOO.util.Dom;

	//private method:
	var getListItems = function () {
		
		//note that we can use other private variables here, including
		//our "yud" shorthand to YAHOO.util.Dom:
		var elList = yud.get("myList");
		var aListItems = yud.getElementsByClassName(
			"draggable", //get only items with css class "draggable"
			"li", //only return list items
			elList //restrict search to children of this element
		);
		return aListItems;
	};
	
	//the returned object here will become YAHOO.myProject.myModule:
	return  {

		aDragObjects: [], //a publicly accessible place to store our DD objects
		
		init: function () {
			//we'll defer making list items draggable until the DOM is fully loaded:
			yue.onDOMReady(this.makeLIsDraggable, this, true);
		},
		
		makeLIsDraggable: function () {
			var aListItems = getListItems(); //these are the elements we'll make draggable
			for (var i=0, j=aListItems.length; i<j; i++) {
				this.aDragObjects.push(new YAHOO.util.DD(aListItems[i]));
			}
		}

	};
}(); // the parens here cause the anonymous function to execute and return

//The above code has already executed, so we can access the init
//method immediately:
YAHOO.myProject.myModule.init();
</script>

This example is a simple one, and it’s deliberately verbose — if this was all we were doing, we could doubtless write it in a more compact way. However, this pattern scales well as the project becomes more complex and as its API grows. It stays out of the global namespace, provides publicly addressable API methods, and supports protected or “private” data and methods along the way.

With DOM support across all A-grade browsers, many basic (and some complex) interactions can be accomplished with relative ease. Things like adding and removing elements, inserting HTML text, and working with events are now reasonably manageable on a cross-browser basis. There are, of course, some quirks that have to be accounted for, but generally speaking, most things work as you would expect them to. Except for dynamically inserting CSS into your page.

When writing HTML, CSS can be embedded in the page using the <style> element, like this:

<style type="text/css">

  a {
    color: red;

  }

</style>

This block of code can be placed anywhere in a page and its rules will be applied to the entire page. Since we have the DOM API, which gives us the ability to dynamically create elements, attributes, and text nodes with a document, one would assume that some very basic JavaScript code could be used to mimic this HTML code. Logically, it would work like this:

var styleElement = document.createElement("style");

styleElement.type = "text/css";

styleElement.appendChild(document.createTextNode("a { color: red; }"));

document.body.appendChild(styleElement);

It should be just that easy…but it’s not. For Opera and Firefox, browsers that purport to have great standards support, this works perfectly well. In Safari and Internet Explorer it fails, though not for the same reason.

Safari requires dynamically created <style> elements to be inserted into the <head> for the rules to be applied, which is a fairly easy change to the previous code:

var styleElement = document.createElement("style");

styleElement.type = "text/css";

styleElement.appendChild(document.createTextNode("a { color: red; }"));

document.getElementsByTagName("head")[0].appendChild(styleElement);

This code now works in Opera, Firefox, and Safari. But what about IE? When IE encounters style.appendChild() it throws the rather obtuse and not-very-helpful error message, “unexpected call to method or property access”. Try replacing that with a call to set innerHTML, and you’ll get an equally useless error message of “unknown runtime error”. What’s going on here?

It turns out that IE won’t let you manipulate <style> elements in this way. There is, however, a different way to do the same thing. IE supports a styleSheet property on each style element that allows for the manipulation of the style sheet and the rules contained within. The styleSheet property has a property called cssText, which can be used to set and retrieve the CSS text for the style sheet. So, the code can be modified to work in IE by doing this:

var styleElement = document.createElement("style");

styleElement.type = "text/css";

if (styleElement.styleSheet) {

  styleElement.styleSheet.cssText = "a { color: red }";

} else {

  styleElement.appendChild(document.createTextNode("a { color: red; }"));

}

document.getElementsByTagName("head")[0].appendChild(styleElement);

This code now works in all A-grade browsers and can be genericized into a function like this:

function addCss(cssCode) {

var styleElement = document.createElement("style");

  styleElement.type = "text/css";

  if (styleElement.styleSheet) {

    styleElement.styleSheet.cssText = cssCode;

  } else {

    styleElement.appendChild(document.createTextNode(cssCode));

  }

  document.getElementsByTagName("head")[0].appendChild(styleElement);

}

Using this function, you can add as many new blocks of CSS code to your page as you would like.

A warning: IE only allows writing to styleSheet.cssText one time per <style> element. If you try to do it more than one time, it can crash the browser. For this reason, it’s best not to reuse <style> elements on your page. Instead, remove them or just add new ones.