One of the challenges with user interface development – and all software development, for that matter – is that the further down the line in development something goes, the harder it is to change. Once a developer spends days or weeks working on something the resistance becomes huge as people are attached to their work – regardless of whether it is a good fit for the customer. To counter these problems, I’m a big advocate of building mockups in order to sort out the key design issues before significant development happens.

Over the years, I’ve used the following types of tools to do this:

• Whiteboards with digital camera snapshots
• Pen and paper sketches scanned
• Photoshop / image mockups
• HTML mockups
• PHP prototypes

I use these various tools to build mockups for a variety of applications including native windows applications, classical web applications, and dynamic ajax applications. The more complex applications become, with complex widgets such as data grids, trees, and tabs, the tougher the hurdles are to crank out a quick mockup. The other problem I’ve seen is that the closer to ‘real’ a mockup looks, the more people are going to comment on the nitty gritty details instead of focusing on the key issues of workflow and usability – just like the problem of developers getting attached to something they’ve worked on, reviewers of super realistic models seem to often just assume that they can’t question the general structure and end up commenting on alignment issues, colors, etc.

I’m always on the prowl for new tools to use in this design phase, and have recently come across a product that is becoming a great addition to my arsenal of tools: Balsamiq Mockups. Balsamiq is a lightweight tool for building wireframes/mockups that look like sketches. The focus is on rapid creation of screen mockups that are easy to make and easy to change, encouraging feedback and rapid iteration. The product is available in a desktop version and also version integrated with Wiki software like Confluence. For the past few weeks I’ve been playing around with the desktop version – their website said that they’d give a free license of the desktop version if you promised to write a review, so here I am! Here I’d like to point out some of my likes, some annoyances, some features I’d like to see, and a weird little bug I came across.

First off, here’s a sample of what a mockup looks like for a fictional, non-sense product:

In a way, Balsamiq seems to be very much inspired by Microsoft PowerPoint…but in a good way. You drag shapes from a list of about 75 widgets onto a page and then rearrange, align, and change properties for the items. The big difference is in the different types of widgets that are available. There are some basic shapes, but most of the widgets are things you would see in applications, like text inputs, dropdowns, radio/checkboxes, and then some more complex widgets like tabs, trees, data grids, and iPhone widgets. The result is that you can build things fast – the mockup above took about 5 minutes to put together.

What I like

• Easy to use – the number one feature. As mentioned, the application uses many known paradigms from existing applications such as PowerPoint and other design apps. I was able to get going without reading the manual, going through a tutorial, or getting a lesson – the application explains itself.
• Fast – ok, this is tied for the number one feature. Because of its ease of use, it is possible to create and iterate on designs very quickly. The ‘Quick Add’ feature really speeds things up by letting you type in the name of a widget without having to find it in the mix of 75 widgets – conveniences like this can make a massive difference in productivity.
• Just the right level of realism – the mockups definitely would never be confused with a real application, but they are clean enough that they can convey to point very well and get people to focus on the key design and workflow issues early on in product design and development
• Advanced widgets such as tree and data table – these advanced widgets are some of the items that make it tough to build mockups for advanced apps in languages like HTML without investing a lot of effort to use libraries like extjs, jquery, or YUI.
• Easy to export to PNG – mockups can easily be exported out to the PNG format for posting on a wiki or emailing.
• Editable – as compared to paper mockups, these have the major advantage of being editable, so you don’t have to break out the eraser or start over from scratch.
• Translates well to traditional webapps, ajax webapps, and desktop applications – because the application

Annoyances…or things that aren’t necessarily bugs, but would make the application easier to use if they were addressed

• After ‘Quick Add’ clicking f2 doesn’t go into edit mode – you have to click the widget first. If you drag items from the strip they automatically go into edit mode, it would be nice to have that for the quick add as well.
• Dragging items from the strip doesn’t show the guides unless you place the widget then drag again, whereas normally when you are dragging you see guides to help you line up widgets
• It would be nice if there were a better way to select a set of items without moving the item beneath it. If you have 20 widgets on a dialog box and you need to shift them over to make space, in order to select them all you have to first lock the dialog box, select the items by click dragging, drag, release, and unlock the dialog. If you don’t do this then the dialog box will just be moved. This gets more confusing if you have multiple boxes on top of each other. It would be nice if there were a way to move into selection mode which would allow you to select any elements that are entirely enclosed by a bounding box.
• Related to the previous entry, you unlock items through a right-click menu (the only usage of right-click in the app?), but if multiple items are locked in the clicked area it just shows the item type in the context menu. In some scenarios I had 3 or 4 items showing up, some of which were of the same type. It would be nice to highlight the item when hovering over it in the context menu to let you know you’ve got the right one.
• It would be nice if the tree could user smaller fonts – some of the other widgets allow for choosing smaller fonts to fit more text, but the tree uses a very large font, making it tough to represent even remotely realistic data.

Features I’d like to see

• Ability to click through from one mockup to another to create workflow – while I don’t need to create an entire flow for an application, if I’m mocking up a particular feature it would be useful to show 3 or 4 screens that are linked together maybe with a generated HTML files or something of the sort.
• Ability to regroup after ungrouping items – you can group items, but you need to ungroup to make any edits (unlike PowerPoint which allows you to change text or even move sub-items), but then you don’t have an option to regroup…meaning you have to go through the same fun of locking outer elements, and reselecting.
• Radio and Check Box controls should allow adding multiple at once similar to Dropdown – since these fields usually come with multiple entries it would be nice to have the widgets allow for adding multiple ‘rows’ of data similar to dropdowns
• It would be nice to have right-click context menus for some operations like grouping or ungrouping
• Layers – it might be nice to have layers (like Photoshop) to help avoid some of the issues with moving items…this would add a lot of utility but it would come with the negative impact on ease of use and ramp up time.
• Ability to add custom widgets – it would be nice to be able to add custom widgets…now if you create a widget by composing the built in widgets you have to save it as another mockup and then select-all and copy/paste into the destination mockup – it would be nice to be able to save the widget to the strip and give it a name.
• Favorites bar in addition to the current ‘All’, ‘Big’, ‘Buttons’ – for many projects only a small number of the widgets are necessary. In my applications I have no need for things like the iPhone widgets so they just get in the way.
• Maybe a way to switch from click mode to select mode for selecting multiple items

Bug

• This was a weird one. If you type ’scro’ into the Quick Add box and click the entry for the ‘vertical scrollbar’, the horizontal scrollbar is actually added. Surprisingly, if you type in ’scrol’ or ’scr’ it works just fine!

Conclusion

Overall I really like this application – I’ve found myself evangelizing to colleagues and used it for some real feature design and have gotten good feedback from all who have seen the results. Like all software, there are many things that could be improved and there likely always will be, but it seems that the application is in active development and the focus on usability and user productivity look like they’ll keep the product on the right trajectory. At $79 I think it is a bargain and justifies its cost in hours or days of use. It doesn’t necessarily replace all of the other tools in my mockup toolbox – to get to the finer level of detail I still need to break out the HTML occasionally – but this is now usually something that happens only after I’ve validated the basic design with Balsamiq.

Rating: 8/10

I wanted to be able to build a simple page with regular links to the mp3 files and for JavaScript to do the magic of making the songs playable in the browser – this post explains how I made it happen. SoundManager 2 is a JavaScript library built on top of Flash – the music plays through Flash (which has much better audio support than browsers), but everything is controlled via JavaScript. I also used Prototype as a framework to build out the functionality.

Here’s what I did:

1. Created a simple page with links to mp3 files
2. Added a SoundManager handler so that as soon as it loads it instantiates PagePlayer, a JavaScript class I created
3. PagePlayer takes a CSS selector as input (and optionally an options object) and identifies all of the links that match the selector – ‘a.mp3Link’ in this case (all links with the class ‘mp3Link’).
4. For each of the identified links, PagePlayer creates a SoundManager sound object using the link to the mp3, adds a play button just prior to the song link, creates event handlers for the play button and sound object, and stores the song in a hash
5. The event handlers take care of all of the logic: playing songs, making sure that only a single song is playing, changing the state of the button from play to stop

Here’s a current snapshot of the script:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

PagePlayer = Class.create({
	songCount: 0,
	songs: new Hash(),
	nowPlaying: null,
	options: null,
 
	initialize: function(selector, options) {
		this.options = {
			imgPath: 'images/',
			imgPlay: 'control_play.png',
			imgStop: 'control_stop.png',
			mp3LinkTitle: 'Download song'
		};
		Object.extend(this.options, options || {});
		$$(selector).each(this.addSong,this);
	},
 
	addSong: function(mp3Link) {
		mp3Link.title = this.options.mp3LinkTitle;
		var songId = mp3Link.identify();
		var soundObj = soundManager.createSound({
			id: songId,
			url: mp3Link.href,
			onfinish: this.finishHandler.bind(this,songId)
		});
		var controlBtn = new Element('img',{
			src: this.options.imgPath + this.options.imgPlay,
			className: 'audioControl'
		});
		mp3Link.insert({before: controlBtn});
		controlBtn.observe('click', this.toggleHandler.bind(this,songId));
 
		this.songs.set(songId, {
			controlBtn: controlBtn,
			soundObj: soundObj
		});
 
		this.songCount++;
	},
 
	toggleHandler: function(songId) {
		var oldSong = this.nowPlaying;
		var newSong = this.songs.get(songId);
 
		if(oldSong) {
			oldSong.soundObj.stop();
			oldSong.controlBtn.src = this.options.imgPath + this.options.imgPlay;
			if(oldSong === newSong) {
				this.nowPlaying = null;
				return;
			}
		}
 
		newSong.controlBtn.src = this.options.imgPath + this.options.imgStop;
		newSong.soundObj.play();
		this.nowPlaying = newSong;
	},
 
	finishHandler: function() {
		this.nowPlaying.controlBtn.src = this.options.imgPath + this.options.imgPlay;
		this.nowPlaying = null;
	}
});

And on the page it is started up as follows:

1
2
3
4
5
6
7
8

<script src="js/soundmanager2-nodebug-jsmin.js"></script>
<script src="js/pagePlayer.js"></script>
<script>
	soundManager.url = '';
	soundManager.onload = function() {
		new PagePlayer('a.mp3Link');
	};
</script>

It’s not the prettiest code, but it gets the job done in 1.58 KB of code and works at least in recent versions of Firefox, IE, Safari, and Chrome. So, if you need to add some mp3s to a page, check out SoundManager 2 – it’s easy to use, well documented, and super flexible…

Walking into the Ocean

Nothing too crazy on the JavaScript side – just playing around with some stuff I hadn’t done before. I wrote about three quarters of this a few months ago and just finished it off this afternoon. I had to write a simple, but hopefully effective, image preloader that has nice callbacks and a decent api. The actual slideshow could be written better, but it works, and that’s all I was going for…

And yes, I’m probably about the 58th person to build a Yelp interface for the iPhone, but I was looking for something I’d actually use and learn from!

Yelp provides a REST search API that allows you to pass in a location and a search term and they return a JSON object with a list of matching businesses, their ratings, and the business info. I used the Zend Framework and the Prototype JavaScript library to put it together. I could have done a pure JavaScript implementation using script hacks, but figured it’d be better to have the PHP code serve as a basic proxy for the Yelp web service.

Try it out!

For those who don’t know about Defensio, it is a web service for determining whether a comment on a blog or message in an application is spam. To use it, you must first register for an API key. Defensio is very similar to the venerable Akismet (see the article I wrote on Akismet) but they provide a couple other features such an indication of the ’spaminess’ of an individual message. Akismet has worked out great for me (123,419 spam comments caught so far!), but I figured it would be good to try out something new as well.

The class is a PHP5 class and the public methods are reasonably well commented. The bottom of this post has a link to a test application and a download of the class/test application. So…the usage of this class is quite straightforward, as shown below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

require('library/Gregphoto/Defensio.php');
require('library/Gregphoto/Defensio/Adapter/Streams.php);
 
$apiKey = 'mysecretapikey';
$siteUrl = 'http://my.secret.site.url.com';
 
$defensio = new Gregphoto_Defensio($apiKey,$siteUrl);
$defensio->setHttpClient(new Gregphoto_Defensio_Adapter_Streams());
 
$params = array(
	'user-ip' => $_SERVER['REMOTE_ADDR'],
	'article-date' => '2007/11/24',
	'comment-author' => 'Big Bad Spammer',
	'comment-type' => 'comment',
	'comment-content' => 'please click links and buy viagra',
	'comment-author-email' => 'bigbadspammer@annoying.com',
	'comment-author-url' => 'http://www.annoying.com'
);
$result = $defensio->audit_comment($params);
if($result['spam'] == 'true') {
	echo "Comment is spam with a spam score of " . $result['spaminess'];
} else {
	echo "Comment is not spam";
}

A couple key points on usage:

• Each Gregphoto_Defensio object requires an Http adapter that it will use to make Http POST requests to the Defensio web service. I originally hardcoded it to use the Zend_Http_Client from the Zend Framework, but figured this could discourage people from using it. Then I wrote up a quick adapter to use PHP’s Http Stream Wrappers, but realized that didn’t work on my Dreamhost account, so I added in an extra one for the Curl extension. In theory I should have added a Gregphoto_Defensio_Adapter_Interface class, but I was lazy and didn’t want to add in an extra file.
• Each Gregphoto_Defensio object can be used to make many requests
• All of the current Defensio API’s are covered by the class. These are covered by the following methods in the Gregphoto_Defensio class:
  • validate_key
  • announce_article
  • audit_comment
  • report_false_negatives
  • report_false_positives
  • get_stats
• Each of these methods takes a single parameter, an associative array of options as defined by the Defensio API. Each API also returns an associative array of response parameters. Two static utility methods Gregphoto_Defensio::getActions (returns a list of defensio methods such as ‘validate-key’) and Gregphoto_Defensio::getActionDetails (returns a list of required parameters, optional parameters, and response parameters for a specific Defensio action) are provided in order to get the details of the input and output parameters.

I created a simple test application which can be used to test Gregphoto_Defensio and all of the APIs provided by Defensio.

Download the Gregphoto_Defensio class and the test application

Check out my pictures here: http://picasaweb.google.com/gneustaetter/SouthKoreaIndiaAndSingapore

The class has the following basic features:

• Ability to read JPEG, PNG, or GIF images
• Ability to output JPEG, PNG, or GIF images
• 4 modes of thumbnail creation
  • MAX_HEIGHT – you specify a maximum height and the dimensions are calculated based off of the height
  • MAX_WIDTH – you specify a maximum width and the dimensions are calculated based off of the width
  • BEST_FIT – you specify a maximum height and width and the dimensions are calculated so that the thumbnail
    is as large as possible without exceeding the maximum height or width
  • EXACT – you specify a maximum height and width and these are directly used. Causes distortion if the
    chosen aspect ratio is different from the aspect ratio of the image
• Renders/saves images in their input format by default, but allows changing the format. For example, input a GIF but output a PNG
• Fully documented object oriented code
• Fluent interface for creating thumbnails with a minimal amount of code

The class is licensed under the MIT license, which basically means it can be used and modified by anyone – for personal or commercial use.

You can Download it from the project page on Google Code. You can view examples of it running on my site – the examples are checked into SVN and can be viewed on the project site. You can also view the docs.

Example usage:

1
2
3
4
5
6
7

require('path/to/Gregphoto_Image.php');
$image = new Gregphoto_Image('path/to/sample/image.jpg');
$image->setMaxHeight(200);
$image->setMaxWidth(200);
$image->setJpegQuality(90);
$image->resize(Gregphoto_Image::BEST_FIT);
$image->showThumbnail();

1
2

$image = new Gregphoto_Image('../images/fan.jpg');
$image->setMaxHeight(200)->setJpegQuality(90)->resize()->showThumbnail();

1
2
3
4
5
6
7
8

require('path/to/Gregphoto_Image.php');
$image = new Gregphoto_Image('path/to/image.jpg');
$image->setMaxHeight(200);
$image->setMaxWidth(200);
$image->setJpegQuality(90);
$image->setOutputType(IMAGETYPE_PNG);
$image->resize(Gregphoto_Image::BEST_FIT);
$image->saveThumbnail('path/to/thumbnail.png');

Enjoy!

See the example (note: example uses Scriptaculous 1.7 Beta 2)

The methodology behind this is quite simple:

1. Load the list values from the DB and show them on the screen
2. Using JavaScript, setup the sortables
3. Add a JavaScript callback to the drag/drop that points to a function that serializes the list and sends an Ajax request to the server
4. On the server, loop through the list and update the database with the proper order

To do this I created three main files:

• index.php – the UI that shows the list and has the JavaScript
• ajax.php – the page that processes the Ajax request
• db.php – a simple database class included in both index.php and ajax.php that makes the connection to the DB and has methods to get the current list and to update the list

Reviewing Index.php

Index.php looks like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

<?
require('db.php');
$demo = new SortableExample();
$list = $demo->getList();
?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
	<title>Scriptaculous 1.7 Sortables Ajax Example</title>
	<link rel="stylesheet" type="text/css" href="style.css">
	<script src="js/prototype.js"></script>
	<script src="js/scriptaculous.js"></script>
	<script>
		Event.observe(window,'load',init,false);
		function init() {
			Sortable.create('listContainer',{tag:'div',onUpdate:updateList});
		}
		function updateList(container) {
			var url = 'ajax.php';
			var params = Sortable.serialize(container.id);
			var ajax = new Ajax.Request(url,{
				method: 'post',
				parameters: params,
				onLoading: function(){$('workingMsg').show()},
				onLoaded: function(){$('workingMsg').hide()}
			});
		}
		function handleResponse(req) {
			// this function will fire after the ajax request is complete...but we have nothing to do here
		}
	</script>
</head>
<body>
 
<h2>Scriptaculous Sortables Demo with Ajax Callback</h2>
Built with Scriptaculous 1.7 Beta 2.  Drag items in the list below.  Each time you update the list an Ajax call is made
that updated the database with the new order.<br><br>
 
<div id="listContainer">
	<?
	foreach($list as $item) {
		?>
		<div id="item_<?=$item['catid'];?>"><?=$item['category'];?></div>
		<?
	}
	?>
</div>
<div id="workingMsg" style="display:none;">Updating database...</div>
 
</body>
</html>

Let’s look at this in reverse order. At the bottom of the file there is a div with id ‘containerDiv’ (line 36). This is the container for our list. Within this is a small snippet of PHP that loops through an associative array and prints out each list item as a div with id ‘item_12′ where 12 is the ID for that record in the database (line 40). Lines 2-4 contain the PHP code that include the db.php file and use it’s class to get the associative array that is used here.

Underneath the container div is another div that has the text ‘Updating database…’ – this div is hidden by default and will be shown while Ajax calls are in progress (line 45).

Now to the JavaScript…it starts off on line 14 with a call to Event.observe that tells the browser to call the init function after the page loads. The init function (line 15) creates a new sortable list on the listContainer element, setting all divs within it to be sortable and setting the updateList function as a callback whenever the list is updated. This means that when the order of items in the list change, this function will be called with the list element passed as an argument. This function will perform the Ajax request to update the database.

The updateList function (line 18) first sets a simple variable for the url used for the Ajax request. Next (line 20) it calls Sortable.serialize, passing the id of the container as an argument, which serializes the list to a format such as listContainer[]=5,listContainer[]=7,listContainer[]=2 – here, the first three items of the list would be the items 5, 7, and 2 and the divs representing these items would have the following id values: item_5, item_7, and item_2. This serialized list is set in the variable ‘params’. Next, on line 21, an Ajax request is opened with Prototype’s Ajax.Request class. It is called with two arguments, the url and an object with various options. The options include the type of request (POST in this example, parameters to pass (the params variable constructed on line 20), and two functions (onLoading/onLoaded) that handle the showing and hiding of the ‘Updating database…’ div. Normally in an Ajax request I’d also add a callback for onComplete to handle the response from the server, but in this case the Ajax response doesn’t really matter to me because it is really only a one way communication in this demo – in a real application I’d have more error handling and would need to handle error conditions.

That’s about it for the index page…not too bad, right?

Reviewing ajax.php

The file ajax.php is a simple file that is designed to receive the Ajax request and call the appropriate methods defined in db.php to update the list. Its contents are shown below:

1
2
3
4
5
6

<?
session_start();
require('db.php');
$demo = new SortableExample();
$demo->updateList($_POST['listContainer']);
?>

Yup, that’s it. Basically it starts off by calling session_start() – I typically call session_start() at the top of pages like this because starting the session sends the right http headers to prevent the file from being cached and I’m too lazy to look up what the right headers are! Next it requires the db.php file, instantiates an object, and calls the updateList method of the object, passing the listContainer variable from the POST request (containing our serialized list). That’s it for the ajax.php page.

Reviewing db.php

The file db.php is a simple database class that connects to the database and has methods to get the list and to update the order of the list. In a ‘real’ application I would definitely have a much cleaner implementation of the database access and would use other DB libraries to connect to the db – I used the simple mysql db functions to minimize on the number of lines needed here. Here are the contents of the file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<?
class SortableExample {
	protected $conn;
	protected $user = 'test';
	protected $pass = 'test';
	protected $dbname = 'scriptaculous';
	protected $host = 'localhost';
 
	public function __construct() {
		$this->conn = mysql_connect($this->host, $this->user, $this->pass);
		mysql_select_db($this->dbname,$this->conn);
	}
 
	public function getList() {
		$sql = "SELECT * FROM categories ORDER BY orderid";
		$recordSet = mysql_query($sql,$this->conn);
		$results = array();
		while($row = mysql_fetch_assoc($recordSet)) {
			$results[] = $row;
		}
		return $results;
	}
 
	public function updateList($orderArray) {
		$orderid = 1;
		foreach($orderArray as $catid) {
			$catid = (int) $catid;
			$sql = "UPDATE categories SET orderid={$orderid} WHERE catid={$catid}";
			$recordSet = mysql_query($sql,$this->conn);
			$orderid++;
		}
	}
}
?>

Important note – this file uses PHP 5 syntax in this object…you’d need some changes to get this to run in PHP 4. I’ll skip talking about the constructor (which connects to the database) and the getList function (which…gets the list) in order to focus on the last method, ‘updateList’. This function takes in an array of items, i.e. array(5,7,2), that come from the serialized list. It loops through the list and generates SQL UPDATE queries for each item. Each time it increments $orderid so that the first item has an orderid of 1, the 2nd an orderid of 2, etc. This means that whenever we get the list, as long as the SQL ‘ORDER BY orderid’ clause is used the list will show in the correct order.

Summary

That’s it…hope you enjoyed it. The hopeful moral of the story is…Ajax is easy, and so is drag and drop….especially if you’re using a good library. Personally I think that Prototype is incredibly useful for JavaScript development and Scriptaculous is a good sidekick for effects and drag/drop. I’ve also used the Yahoo YUI widgets at work where we needed to do some more dynamic widgets such as trees – it worked really well. Jack Slocum’s YUI extension is incredibly well done too…though it’s a heavy one in terms of file size! In the end, it comes down to finding the right tool for the job…

Download the sample application if you want to take a closer look….

The following is an example of a simple reusable widget created using the Prototype JavaScript library. The widget is an ‘accordian’ – a widget composed of multiple sections, of which only one is open at a time. This type of widget is available in all sorts of applications, from Microsoft Outlook (circa Outlook 2000), to web applications, and more. In addition to showing off this simple widget, I’d like to walk through it to explain how it works and how to write something like this with Prototype. For all of Prototype’s greatness, there is certainly a lack of documentation that makes it a little bit difficult to get into.

Example

Take a look at the example page I put together showing a few examples of accordians and their capabilities. This article will explain how to put together the class that does this.

Explaination: Creating Reusable Classes

I’ll skip with going through the HTML – you can see that on the example page if you’re interested – it would be helpful in understanding the javaScript here. In this example I’ve used version 1.5.0_rc0 of Prototype. The first line of the accordian.js file has the following:

1

Accordian = Class.create();

Prototype’s Class.create() sets up Accordian as an object that can be instantiated. When the object is instantiated the ‘initialize’ method, its constructor, will be automatically called. You setup all of the methods within the object by defining its prototype – an object with properties and methods. This could be done in the following way:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Accordian.prototype = {
	initialize: function(args) {
		// do something
	},
	sectionClicked: function(args) {
 
	},
	openSection: function(args) {
 
	},
	closeExistingSection: function(args) {
 
	}
}

This object could be instantiated in the following way:

1

var myAccordian = new Accordian(options);

Explanation: Writing the Constructor

The constructor needs to take two arguments – the ID of the element that contains the accordian and the type of entry that is used for the header of each section. The constructors main job is getting a list of all of the sections within the accordian and adds onClick event handlers to the headers so that clicking them will open the section. The constructor is shown below:

1
2
3
4
5
6
7

initialize: function(elem, clickableEntity) {
   this.container = $(elem);
   var headers = $$('#' + elem + ' .section ' + clickableEntity);
   headers.each(function(header) {
       Event.observe(header,'click',this.sectionClicked.bindAsEventListener(this));
   }.bind(this));
}

Now to explain what’s going on in the constructor:

• The first line defines the function that expects two variables – the ID of the element that holds the accordian and the type of element that will serve as the header for a section.
• The second line sets a class property, ‘container’, to the element passed in with variable ‘elem’. It uses Prototype’s $() function, which in this case is equivalent to document.getElementById()
• The third line uses the very powerful $$() function that returns an array of all elements that match a given css query. In this case, the query might look like ‘#myAccordian .section h3′, which would return all h3 elements under an element with class ’section’ under the element with ID ‘myAccordian’.
• Lines 4-6 setup the event handlers that will be used when the user clicks the headers. This uses the each() function that Prototype adds to arrays in order to quickly loop through an array without using a for loop or creating a bunch of temporary variables. This function takes a function as an argument that will be applied as an iterator over the array. This use of this technique is similar to the foreach concept in PHP (foreach($headers as $header)) and other languages. Because functions are objects in JavaScript, we need to add a trick at the end of the each function defined within ‘each’ – we need to add ‘bind(this)’. This means that within the new function, the ‘this’ keyword will be bound to the Accordian object, not to the function itself.
• Line 5 uses Prototype’s Event class to setup the observer – in this case it will bind the classes sectionClicked method to any click on the header elements. Similar to the binding needed on the function, the reference to the sectionClicked function is follwed by ‘bindAsEventListener(this)’, which means that inside the event handler, ‘this’ will refer to the Accordian object, not to the clicked header element.

Explanation: Writing the Event Handler

The function referenced as the event handler in the constructor is shown below:

1
2
3

  sectionClicked: function(event) {
   this.openSection(Event.element(event).parentNode);
}

Functions called as an event always get passed an event object. This function takes this event and uses the Prototype ‘Event’ class to get a handle on the parent node of the element that was clicked, the section itself. It then passes this as an argument to another method in this class – openSection.

Explanation: Opening a Section

This function if fairly straightfoward – it checks to see if the section being opened is already open, and if not, calls a function to close the open section, and finally opens the new section. It is shown below:

1
2
3
4
5
6
7
8
9

openSection: function(section) {
	var section = $(section);
	if(section.id != this.currentSection) {
		this.closeExistingSection();
		this.currentSection = section.id;
		var contents = document.getElementsByClassName('contents',section);
		contents[0].show();
	}
}

• The function takes one argument, the section that is to be opened
• The second line uses the $() function to get the DOM element. It is important to note that this function can either take the section ID as an argument or the actual section DOM node. The $() function adds this extra flexibility
• The third line checks to see whether the ID of the section is the same as the currently open section. If it is, no other logic is performed. If it isn’t, the next few lines will open that section.
• After line 4 calls a function to close the existing section, line 5 sets a class property ‘currentSection’ to the new section
• Line 6 uses Prototype’s getElementsByClassName, passing the class (contents) and the element under which it should look (the new section). This returns an array of elements
• Line 7 takes the first element with class contents (their should only be one), and uses Prototype’s show() function to show the element

Explanation: Closing a Section

This last function is the simplest of all – it checks to see whether there is an open section, and if so, it hides it.

1
2
3
4
5
6

closeExistingSection: function() {
	if(this.currentSection) {
		var contents = document.getElementsByClassName('contents',this.currentSection);
		contents[0].hide();
	}
}

• The second line checks if the currentSection exists – it is only set after the first section has been opened
• The third line uses the same technique as in the previous function – it uses getElementsByClassName to get the elements with class ’section’
• Finally, the hide function will hide this element so that the section is collapsed

The Final Script

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

Accordian = Class.create();
Accordian.prototype = {
	initialize: function(elem, clickableEntity) {
		this.container = $(elem);
		var headers = $$('#' + elem + ' .section ' + clickableEntity);
		headers.each(function(header) {
			Event.observe(header,'click',this.sectionClicked.bindAsEventListener(this));
		}.bind(this));
	},
	sectionClicked: function(event) {
		this.openSection(Event.element(event).parentNode);
	},
	openSection: function(section) {
		var section = $(section);
		if(section.id != this.currentSection) {
			this.closeExistingSection();
			this.currentSection = section.id;
			var contents = document.getElementsByClassName('contents',section);
			contents[0].show();
		}
	},
	closeExistingSection: function() {
		if(this.currentSection) {
			var contents = document.getElementsByClassName('contents',this.currentSection);
			contents[0].hide();
		}
	}
}

Conclusion

Though this is a fairly simple example, I hope it helped to explain some of the features of the Prototype library and can get people kickstarted to writing classes with JavaScript. Most of it is very simple…if only there were some real documentation. The best source right now is probably Developer notes for prototype.js, which covers features up to Prototype 1.4. Another site with a compilation of links is http://www.prototypedoc.com/.

Go forth and rid the world of nasty IE5 style, unreadable, browser-sniffing, hackish, global-scope JavaScript!

• Allows you to perform complex validation, such as verifying the uniqueness of a username, or checking something in the database…all without reloading the page
• Allows you to use the same validation routine for both client-side validation and server-side validation
• Reduces the amount of client-side code needed for validation

The JavaScript used in my example requires the Prototype library. My example uses PHP to perform the validation – more specifically, I’ve used several components of the Zend Framework (PHP5 only). The example uses:

• Zend_Controller_* classes including the new RewriteRouter to handle the routing within the application
• Zend_View to handle the output
• Zend_View_Helper_* classes to build form elements
• Zend_Config to read in configuration options
• Zend_Filter to perform several field validations
• Zend_Json to serialize PHP variables/objects to JSON objects

Did I need all of this stuff on the server-side to put together a simple form validation example? Heck no, but when I’m experimenting with new stuff I like to use a lot of new components so I can learn more about them and be prepared for when I actually do need to use all of this fire power. I’ve been following the Zend Framework carefully, so I wanted to use some of the stuff I hadn’t used yet – particularly the controller architecture.

The HTML and JavaScript

Ok, back to how this JavaScript is used. It’s actually really quite simple. First, you need to include the JavaScript files for both Prototype and AjaxFormValidator in the head of your HTML document:

1
2

<script src="/ajaxValidate/static/js/prototype.js"></script>
<script src="/ajaxValidate/static/js/ajaxFormValidate.js"></script>

Next, you add an ‘onSubmit’ handler to the form you’d like to validate – in this case, mine looks like this:

1

<form action="/ajaxValidate/index/success" method="POST" onSubmit="return submitForm(this);">

The form action is set to the page I’d like the script to go to if the validation is successful. The onSubmit calls a custom function that we still need to define. It passes ‘this’ as an argument – the ‘this’ refers to the form element itself.

Now we define the submitForm() function that the onSubmit of the form will call – it looks like the following:

1
2
3
4
5
6

function submitForm(form) {
	validator = new AjaxFormValidator(form,"/ajaxValidate/index/validate");
	validator.errorDisplay = 'inline';
	validator.inlineElem = 'errorDiv';
	return validator.validate();
}

This function first creates a new AjaxFormValidator object, passing it the form element (or the form id) and the url the validation request should be sent to. The next two lines setup the type of error display that should happen. The following error display types are supported:

• alert: The default option. Displays all errors in a JavaScript alert box.
• inline: Displays errors within an element that is defined on the page. You need to set the element name with validator.inlineElem. In this example, errors will be shown in a div with id=”errorDiv”.
• none: errors won’t be shown to the user. The will be available as an array of errors in the errors property of the validator (i.e. validator.errors). If there are no errors the property will be set to false. Once you have the errors you can perform more advanced error handling/display to the user.

Lastly, validator.validate() will send the values in the form, in an HTTP POST, to the validation url you’ve provided (/ajaxValidate/index/validate in this case). If there are no errors the form will be submitted, if there are errors the will be shown (or not shown if you’ve chosen ‘none’ as the errorDisplay).

The PHP

Once the request is sent it will eventually arrive at the server for processing – in this case, through the magic of routing, it is going to end up in my IndexController in the validateAction method. This function is shown below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

public function validateAction() {
	$errors = $this->getErrors($_POST);
	if(count($errors) == 0) $errors = false;
	echo Zend_Json::encode($errors);
}
</php>
This function calls another method within the IndexController class called getErrors, passing in the entire array of POST arguments (values in the form).  It receives back an array full of error strings.  If there are no errors, it changes the value of the $error variable to false.  Lastly, it uses Zend_Json to convert the PHP array/Boolean into the equivalent JavaScript array/Boolean.  This string is printed and sent back to the client.
 
The getErrors function itself is very straightforward - it just does a couple validations and returns back an array of the errors.
<pre lang="php" line="1">
protected function getErrors($values) {
	$errors = array();
	if(!Zend_Filter::isRegex($values['fname'],'/^[a-z]+[a-z 0-9-_]*$/i')) {
		$errors[] = 'First Name is required and may only contain letters, numbers, and spaces';
	}
	if(!Zend_Filter::isRegex($values['lname'],'/^[a-z]+[a-z 0-9-_]*$/i')) {
		$errors[] = 'Last Name is required and may only contain letters, numbers, and spaces';
	}
	if(!Zend_Filter::isRegex($values['email'],'/^[_a-zA-Z-]+[._a-zA-Z0-9-]+@[a-zA-Z0-9-]+\.[.a-zA-Z0-9]+$/')) {
		$errors[] = 'Email is required and must be a valid email address';
	}
	if(!Zend_Filter::isAlnum($values['password']) || (strlen($values['password']) < 6) || (strlen($values['password']) > 12)) {
		$errors[] = 'Password must consist of only letters and numbers and must be between 6 and 12 characters';
	}
	return $errors;
}

Check it out, in action. And that’s about it – pretty simple, huh?

You can download:

• The JavaScript
• The whole PHP project