Code Conventions for the JavaScript Programming Language from Crockford. The man, the myth, the legend. Everything he’s written about JavaScript should be read, but this article in particular offers a good starting point.

The Elements of JavaScript Style Part One, and Part Two, again from Crockford. Together with the aforementioned Code Conventions article, they make a pretty good basis for writing clean, efficient code.

Best Practices for Speeding Up Your Web Site from Yahoo. The JavaScript advice is invaluable. It talks about the big stuff that will actually make a noticeable difference to your users.

The JavaScript Reference Series by Pat Hunlock. Much more comprehensive and useful than similar, more common references (I’m looking at you w3Schools).

Syntax

Douglas Crockford’s (extremely detailed) JavaScript code conventions article should be gospel. Also, use his JSLint to “validate” code. Warnings can actually cause errors, especially if the code becomes minified.

General Tenets

• Put all scripts at the bottom of the page, directly before the closing body tag, unless it’s absolutely necessary to put them in the head tag.
• jQuery (or other JavaScript framework) should be included by default on any new site build.
• JavaScript should not be required for pages to function as intended.
• Keep your global JavaScript in a .js file or files. Even if it’s not a ton of code. A site’s main global JavaScript file should follow the convention: [client abbreviation].js. Additional files should follow a similar convention [client abbreviation]-[reason/location].js.
• When using third-party plugins/scripts, make every attempt to find something that fits only what you want to accomplish. Keep file size as small as possible.
• Strive for reusable code, which should be namespaced, or written in the form of a jQuery plugin.
• Minify general/reusable JavaScript components that you don’t plan on editing often. http://www.refresh-sf.com/yui/ or http://yui.2clics.net/ both work.

Firebug

Simply put, get and use Firebug. Specifically for JavaScript purposes, you’ll want to use the Console and Script features.

Console

Very similar to Firefox’s built-in JavaScript error console, but gives you the ability to log things to it and test out basically any JavaScript. Use it for the following:

• Validation: Like Firefox’s built in “script debugger”… it will tell you if there are JavaScript errors on the page.
• Logging Test Values: Use “console.log()” whenever you would typically “alert” a value for testing purposes. You get much more useful information. See Firebug and logging.
• AJAX Request Tracking: Spits out extremely important request/response info.

More:

• Firebug’s Console Overview
• Documentation

Script

Mainly for more in depth applications, but still invaluable for troubleshooting. More info:

• Firebug’s Debugger Overview
• Tutorial

JavaScript Frameworks

Make use of a JavaScript framework for DOM manipulation, AJAX utilities, animation, etc. It’s outside the scope of this standard to argue which framework to use, but we’ll be assuming the use of jQuery.

Incorporating jQuery

Given this argument, jQuery should be included as such:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>

Before including jQuery in a new site build, check to make sure you’re using the most recent version.

Advanced Topics

Object Literal Notation and Namespacing

The general concept is to mimic a more object-oriented approach to programming, with the added benefits of simplified code and removing the potential for conflicts. Simple examples:

• http://www.lixo.org/archives/2007/09/14/javascript-put-everything-in-a-namespace/
• http://www.brainonfire.net/blog/javascript-object-literal-namespace/

jQuery Plugins

Writing your own jQuery plugins is good motivation to maintain generalized, reusable, object-oriented code. If there isn’t an existing plugin, or if the existing plugins are unnecessary complex, then it’s recommended to roll your own.

Creating a XMLHttp Object

The first thing you’ll notice when using the aid of a JavaScript framework AJAX library is that you don’t have to bother creating a XMLHttp object. That means right off the bat you’ll save yourself some (often painful) cross-browser scripting. You can also be assured that any future improvements to this object implementation will be delivered to your code as long as you keep the framework updated. Thank you JavaScript frameworks!

Setting Up and Sending the Request

Here’s the code I wrote earlier to perform both get and post requests without the help of a framework:

// Create and send an XMLHttp request
function doRequest(url, postVars) {
	// Get the request object (see previous function)
	req = getReqObject()
	// Make sure we have a XMLHttp object created
	if (req) {
		// If it's a post, we have to create and send the request slightly differently.
		if (postVars) {
			req.open('POST', url, true);
			req.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
			req.send(postVars);
		} else {
			req.open('GET', url, true);
			req.send(null);
		}
		// Set the function that handles the results
		req.onreadystatechange = function () { displayContents(req) };
	}
}

// Request via GET
doRequest('test.php?var=1', null);

// Request via POST
doRequest('test.php', 'var=1');

With DOMAssistant, you have to decide before your call what you are going to do with the data. For simple calls where you just need to return the text, you can use the library’s get or post methods:

// Request via GET
DOMAssistant.AJAX.get('test.php?var=1', displayContents);

// Request via POST
DOMAssistant.AJAX.post('test.php?var=1', displayContents);

However, if you need an XML result that you can parse (like in our working example), you’ll need to make more complex calls:

// Create and send an XMLHttp request
function doRequest(url, postVars) {
	// If it's a post, we have to create and send the request slightly differently.
	if (postVars) {
		DOMAssistant.AJAX.ajax({
			url: url,
			method: "POST",
			params : postVars,
			callback: displayContents,
			responseType: "xml",
			headers : {
				"Content-type" : "application/x-www-form-urlencoded"
			}
		});
	} else {
		DOMAssistant.AJAX.ajax({
			url: url,
			method: "GET,
			callback: displayContents,
			responseType: "xml"
		});
	}
	// Set the function that handles the results
	req.onreadystatechange = function () { displayContents(req) };
}

// Request via GET
doRequest('test.php?var=1', null);

// Request via POST
doRequest('test.php', 'var=1');

As you can see, if you need an XML document for additional post-processing, you’ll end up with almost as much code with DOMAssistant!

Handling the Result

Here’s the function I wrote to alert specific data from the response content:

// Display resulting content from req
function displayContents(req) {
	// Only do something when the request is done
	if (req.readyState == 4) {
		// Make sure it was a success
		if (req.status == 200) {
			// Traverse the resulting XML, alerting titles of items
			var xml = req.responseXML;
			var items = xml.getElementsByTagName("item");
			for (var i = 0; i < items.length; i++) {
				alert(items[i].getElementsByTagName('title').item(0).firstChild.nodeValue);
			}
		} else {
			alert('Problem with the request.');
		}
	}
}

An odd thing about DOMAssistant is that your specified callback function is hardcoded in the framework to be executed after the request is complete. This means you won’t be able to troubleshoot based on the ready state of the request. I also found that the callback function doesn’t have access to the status of the completed request, meaning you won’t know if your request was successful or not. I’m sure there were logical reasons by the developers for this, but in the meantime all you can do is work with the response text.

If you used the get or post methods, you’ll be provided the text of the response:

// Display resulting content from responseText
function displayContents(rText) {
	alert(rText);
}

For our example, we needed an XML document, and as such we need to loop through and extract the information in much the same manner as we did before:

// Display resulting content from req
function displayContents(rXML) {
	var items = rXML.getElementsByTagName("item");
	for (var i = 0; i < items.length; i++) {
		alert(items[i].getElementsByTagName('title').item(0).firstChild.nodeValue);
	}
}

As you can see there really isn’t any difference here except that DOMAssistant actually limits our troubleshooting capabilities.

Cross-Domain Requests

JavaScript frameworks don’t provide a built-in solution for addressing cross-domain request security issues. In fact, the Prototype documentation makes this extremely prominent at the top of their documentation:

Remember that for security reasons (that is preventing cross-site scripting attacks) Ajax requests can only be made to URLs of the same protocol, host and port of the page containing the Ajax request. Some browsers might allow arbitrary URLs, but you shouldn’t rely on support for this.

Conclusion

All in all I’m rather disappointed with DOMAssistant’s AJAX library. For very simple tasks like grabbing, posting and printing text it works great. But for complicated cases, it offers little to no benefit. It could be effective if used in conjunction with a more complex server-side proxy, so that the proxy could handle parsing and the DOMAssistant would just have to retrieve and display text. Next time I’ll take a look at Prototype, and see if it offers more flexible and comprehensive functionality.

A co-worker recommended FCKeditor, so I implemented it in a recent administration interface to control text for a few pages. So far it’s worked extremely well, and was a breeze to implement. Here’s a summary of my implementation:

• Downloaded, unzipped, and stored the FCKeditor files
• Created a custom editor style file (myeditorstyles.css), and put the site’s content styling rules in it so the editor would mimic the site’s style
• Created a custom configuration file (myconfig-default.js), which serves to remove a bunch of the unnecessary functionality, and reference the style:

FCKConfig.FontFormats = 'h1;h2;h3;p';
FCKConfig.ToolbarCanCollapse = false;
FCKConfig.EditorAreaCSS = '/lib/includes/FCKeditor/myeditorstyles.css';
FCKConfig.ToolbarSets["Default"] = [
	['Save'],
	['Undo','Redo'],
	['Bold','Italic','Underline'],
	['OrderedList','UnorderedList','-','Outdent','Indent'],
	['JustifyLeft','JustifyCenter','JustifyRight','JustifyFull'],
	['Link','Unlink'],
	['FontFormat'],
	['About', 'Source']
];

• Included the initialization files on the pages I put the editor:

<?php
include_once("[myeditorpath]/fckeditor.php") ;
?>

• Then referenced the editor where I wanted to add it in my code:

$oFCKeditor = new FCKeditor([myeditorid]);
$oFCKeditor->BasePath = '/[myeditorpath]/';
$oFCKeditor->Config["CustomConfigurationsPath"] = "/[myeditorpath]/myconfig-default.js";
$oFCKeditor->Height = '500';
$oFCKeditor->Create();

That’s it! There’s a ton of other customization options, help with implementation, and general resources in the documentation.

Other Options

I highly recommend FCKeditor, but if it doesn’t work for some reason you can always try TinyMCE or openwysiwyg. Both seem full-featured and easy to implement, and both have significant recent activity.

If you think content won’t require any additional HTML formatting, you could always just programmatically replace line breaks in text areas with HTML line breaks and vice versa. This would allow the administrator to use carriage returns to separate text, but would require some HTML knowledge for additional formatting.

The Code

First you’ll have to set up your Flash with two functions, one which will return the “ready state” of the element (just return true when you have loaded sufficiently), and another which will start the action. Then you just have to reference the functions in the following code:

// Given an array of flash element references,
// these functions will ensure they are ready,
// then launch them more or less simultaneously
var flashLoader = flashLoader ? flashLoader : {
	flash: new Array(),
	checkInterval: 1000,

	// Get references to flash elements
	init: function(elms) {
		for (var i = 0; i < elms.length; i++) {
			flashLoader.flash[i] = document.getElementById(elms[i]);
		}
		flashLoader.checkReady();
	},

	// Make sure they are both ready
	checkReady: function() {
		// Bail if an element is not ready
		for (var i = 0; i < flashLoader.flash.length; i++) {
			if (!flashLoader.flash[i].ready || !flashLoader.flash[i].ready()) {
				setTimeout(flashLoader.checkReady,flashLoader.checkInterval);
				return false
			}
		}
		// If we got this far, launch the elements!
		flashLoader.startThem();
	}, 

	// Start the flash elements
	startThem: function() {
		for (var i = 0; i < flashLoader.flash.length; i++) {
			flashLoader.flash[i].commence();
		}
	}
}

// Load the init without screwing anything up
loadLoader = function () {
	flashLoader.init( ['yourFlash1', 'yourFlash2'] );
}
var oldonload = window.onload;
if (typeof window.onload != 'function') {
	window.onload = loadLoader;
} else {
	window.onload = function() {
		oldonload();
		loadLoader();
	}
}

Notice the two Flash function calls:

if (!flashLoader.flash[i].ready || !flashLoader.flash[i].ready()) {

…and:

flashLoader.flash[i].commence();

In some cases you don’t have to perform the ready check, because calling the function on load of the page means it waits until after the Flash is completely loaded. But in other browsers (Safari), the JavaScript is executed earlier, and as such needs the ready check.