Overview

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:

PLAIN TEXT
JAVASCRIPT:
  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:

PLAIN TEXT
JAVASCRIPT:
  1. Accordian.prototype = {
  2.     initialize: function(args) {
  3.         // do something
  4.     },
  5.     sectionClicked: function(args) {
  6.    
  7.     },
  8.     openSection: function(args) {
  9.    
  10.     },
  11.     closeExistingSection: function(args) {
  12.    
  13.     }
  14. }

This object could be instantiated in the following way:

PLAIN TEXT
JAVASCRIPT:
  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:

PLAIN TEXT
JAVASCRIPT:
  1. initialize: function(elem, clickableEntity) {
  2.    this.container = $(elem);
  3.    var headers = $$('#' + elem + ' .section ' + clickableEntity);
  4.    headers.each(function(header) {
  5.        Event.observe(header,'click',this.sectionClicked.bindAsEventListener(this));
  6.    }.bind(this));
  7. }

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:

PLAIN TEXT
JAVASCRIPT:
  1. sectionClicked: function(event) {
  2.    this.openSection(Event.element(event).parentNode);
  3. }

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:

PLAIN TEXT
JAVASCRIPT:
  1. openSection: function(section) {
  2.     var section = $(section);
  3.     if(section.id != this.currentSection) {
  4.         this.closeExistingSection();
  5.         this.currentSection = section.id;
  6.         var contents = document.getElementsByClassName('contents',section);
  7.         contents[0].show();
  8.     }
  9. }

  • 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.

PLAIN TEXT
JAVASCRIPT:
  1. closeExistingSection: function() {
  2.     if(this.currentSection) {
  3.         var contents = document.getElementsByClassName('contents',this.currentSection);
  4.         contents[0].hide();
  5.     }
  6. }

  • 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

PLAIN TEXT
JAVASCRIPT:
  1. Accordian = Class.create();
  2. Accordian.prototype = {
  3.     initialize: function(elem, clickableEntity) {
  4.         this.container = $(elem);
  5.         var headers = $$('#' + elem + ' .section ' + clickableEntity);
  6.         headers.each(function(header) {
  7.             Event.observe(header,'click',this.sectionClicked.bindAsEventListener(this));
  8.         }.bind(this));
  9.     },
  10.     sectionClicked: function(event) {
  11.         this.openSection(Event.element(event).parentNode);
  12.     },
  13.     openSection: function(section) {
  14.         var section = $(section);
  15.         if(section.id != this.currentSection) {
  16.             this.closeExistingSection();
  17.             this.currentSection = section.id;
  18.             var contents = document.getElementsByClassName('contents',section);
  19.             contents[0].show();
  20.         }
  21.     },
  22.     closeExistingSection: function() {
  23.         if(this.currentSection) {
  24.             var contents = document.getElementsByClassName('contents',this.currentSection);
  25.             contents[0].hide();
  26.         }
  27.     }
  28. }

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!