Code in the hole (Entries tagged as javascript)

Javascript refactoring for customising shared libraries

nospam@example.com (David Winterbottom) — Tue, 13 Oct 2009 22:48:42 +0000

One difficulty working with a shared in-house framework is it is difficult to maintain a common javascript file that is valid across multiple applications. This is currently an issue we face at Tangent, where we run a generic e-commerce platform which we customise to the needs of each client. Most of these e-commerce applications have a javascript-rich checkout page whose functionality differs in small yet significant ways such as the required and optional fields within a delivery address, or the range of delivery options available. Ideally, you would have a single javascript file to work for all these checkouts, but these differences make such a file impracticle due to the changes in DOM structure and business logic between applications.

For instance, one problem that arose recently was a requirement to remove the javascript messaging from within certain parts of the checkout for one appliation. The shared checkout.js file features a method which reloads the order totals within the page after a new delivery option has been chosen and displays a message to notify the user:

// [checkout.js]
var shop = {
    checkout: {
        reloadOrderTotals: function() {
            // Do the reloading...
            shop.display.notify("Order totals recalculating...");
        }
}

Unfortunately, another client required the same functionality to reload the order totals but without the notification call. One option would have been to create a local version of the checkout.js file and remove the offending line, but this would have created a larger maintenance overhead going forward due to the large amount of duplicate code.

A neater option would have been to dynamically override the shop.checkout.reloadOrderTotals method in an application-specific file:

// [application.js]
shop.checkout.reloadOrderTotals = function() {
    // Reload order totals but without a notification call
}

However, again this leads to most of the the body of the shop.checkout.reloadOrderTotals method being duplicated just to remove one line.

Instead, drawing inspiration from the excellent Working with Legacy Code by Michael Flowers, a neater solution is to perform a dynamic-language version of the Extract method refactoring to isolate the functionality that we wanted to override into it's own method. Hence, we alter checkout.js to split the reloading and notification functionality into two methods:

// [checkout.js]
var shop = {
    checkout: {
        reloadOrderTotals: function() {
             // Do the reloading...
            shop.checkout.displayOrderTotalNotification("Order totals recalculating...");
        },
        displayOrderTotalNotification(message) {
            shop.display.notify(message);
        } 
}

Now in the local project javascript file, we can null out the messaging behaviour:

// [application.js]
shop.checkout.displayOrderTotalNotification = function(){}

This neat trick allows us to customise our core javascript functionality in a way that does not lead to code duplication. The only thing required to make this work is to ensure that the shared checkout file is loaded before the application-specific one.

Auto-generating an FAQ with Prototype

nospam@example.com (David Winterbottom) — Mon, 25 May 2009 20:34:01 +0000

Have just been writing an FAQ page for commandlinefu.com. Documenting is always tiresome, but FAQs particularly so when hand-coding the HTML links between each question and the summary table at the top of the page.

Javascript to the rescue: I cobbled together a quick Prototype script which automatically generates the FAQ summary links by parsing the DOM for the appropriate links:

document.observe('dom:loaded', function(){
    $$('a.question').each(function(ele){
        var id = ele.innerHTML.unescapeHTML().gsub(/[^\w- ]/, '').gsub(/[\s-]+/, '-').toLowerCase();
        ele.writeAttribute({id: id});
        var link = new Element('a', {href: '#'+id})
            .update(ele.innerHTML)
            .observe('click', function(event){
                event.stop();
                Effect.ScrollTo(ele); 
            });
        $('questions').insert(new Element('li').insert(link));
    });
});

Now, all I have to do is write my FAQ ensuring the questions live in anchor tags with the class "question" and there is an empty list tag at the top of the page to house the summary block.

Here's two snapshots the relevant section of the DOM before and after the dom:loaded event has fired. Before:

<ul id="questions"></ul>
<dl>
    <dt><a class="question">What is this site?</a></dt>
    <dd>...</dd>
    <dt><a class="question">Who created this site?</a></dt>
    <dd>...</dd>
</dl>

and after:

<ul id="questions">
    <li><a href="#what-is-this-site">What is this site?</a></li>
    <li><a href="#who-created-this-site">Who created this site?</a></li>
</ul>
<dl>
    <dt><a class="question" id="what-is-this-site">What is this site?</a></dt>
    <dd>...</dd>
    <dt><a class="question" id="who-created-this-site">Who created this site?</a></dt>
    <dd>...</dd>
</dl>

As you can see, the javascript simply extracts the relevant content from the questions and inserts the appropriate identities and links into the DOM to form the quick-links. Using the Effect.ScrollTo function also gives a pleasant user experience.

Inspecting Javascript objects

nospam@example.com (David Winterbottom) — Sun, 24 May 2009 12:04:00 +0000

Learning Ruby or Python from the command-line prompt is greatly enhanced by the built-in inspection methods these languages provide. These allow the methods and properties of an object to be interrogated via a simple method call which returns an array of all property or method names.

For instance, in IRB (the interactive Ruby command-line) we can interrogate the integer object:

irb(main):001:0>my_int = 1
irb(main):002:0>my_int.methods

This returns an array of all method names for integer objects:

["%", "odd?", "inspect", "prec_i", "<<", "tap", "div", "&", "clone", ">>", "public_methods", "_send_", "object_id", "instance_variable_defined?", "equal?", "freeze", "to_sym", "*", "ord", "+", "extend", "next", "send", "round", "methods", "prec_f", "-", "even?", "singleton_method_added", "divmod", "hash", "/", "integer?", "downto", "dup", "to_enum", "instance_variables", "|", "eql?", "size", "instance_eval", "truncate", "~", "id", "to_i", "singleton_methods", "modulo", "taint", "zero?", "times", "instance_variable_get", "frozen?", "enum_for", "display", "instance_of?", "^", "method", "to_a", "+@", "-@", "quo", "instance_exec", "type", "**", "upto", "to_f", "<", "step", "protected_methods", "<=>", "between?", "==", "remainder", ">", "===", "to_int", "nonzero?", "pred", "instance_variable_set", "coerce", "respond_to?", "kind_of?", "floor", "succ", ">=", "prec", "to_s", "<=", "fdiv", "class", "private_methods", "=~", "tainted?", "_id_", "abs", "untaint", "nil?", "chr", "id2name", "is_a?", "ceil", "[]"]

Meanwhile, in Python we use the build-in function dir():

>>> my_dict = {}
>>> dir(my_dict)

to get a list of attributes (including methods) for a dictionary variable:

['_class_', '_cmp_', '_contains_', '_delattr_', '_delitem_', '_doc_', '_eq_', '_ge_', '_getattribute_', '_getitem_', '_gt_', '_hash_', '_init_', '_iter_', '_le_', '_len_', '_lt_', '_ne_', '_new_', '_reduce_', '_reduce_ex_', '_repr_', '_setattr_', '_setitem_', '_str_', 'clear', 'copy', 'fromkeys', 'get', 'has_key', 'items', 'iteritems', 'iterkeys', 'itervalues', 'keys', 'pop', 'popitem', 'setdefault', 'update', 'values']

Javascript doesn't provide such a feature as standard but it's straightforward to implement a simple inspection object:

var Inspect = {
    TYPE_FUNCTION: 'function',
    // Returns an array of (the names of) all methods
    methods: function(obj) {
        var testObj = obj || self;
        var methods = [];
        for (prop in testObj) {
            if (typeof testObj[prop] == Inspect.TYPE_FUNCTION && typeof Inspect[prop] != Inspect.TYPE_FUNCTION) {
                methods.push(prop);
            }
        }
        return methods;
    },
    // Returns an array of (the names of) all properties
    properties: function(obj) {
        var testObj = obj || self;
        var properties = [];
        for (prop in testObj) {
            if (typeof testObj[prop] != Inspect.TYPE_FUNCTION && typeof Inspect[prop] != Inspect.TYPE_FUNCTION) {
                properties.push(prop);
            }
        }
        return properties;
    }
}

Now we can simply pass in any object (or call without an argument to test the window object) to retrieve an array or properties or methods. For example, working at the Firebug console, we can examine the hash object of the Prototype Javascript library, and the native document.location object:

Moreover, it can sometimes be useful to have a debug mode for an application where these methods are added to the supertype "object" which provides the prototype for all others. In this instance, debug mode is switched on by added a 'debug_mode' parameter to the GET parameters. For convenience, I'm also using the methodize function provided by Prototype:

if (/[?&]debug_mode(&.*)?$/.test(document.location.search)) {
    Object.prototype.properties = Inspect.properties.methodize();
    Object.prototype.methods = Inspect.methods.methodize();
}

Then you can inspect an object without refering to the Inspect object (namespace really):

var my_hash = new Hash();
my_hash.methods();
my_hash.properties()

Code and associated JSunit test suite available at my github repo.

Active record javascript objects using cookies

nospam@example.com (David Winterbottom) — Sat, 08 Nov 2008 18:29:01 +0000

Building on a previous post on javascript cookie objects, it is possible to create a simple layer supertype object that persists objects between requests. This works by defining an active-record-like interface for saving an object's properties to a JSON-encoded cookie. Objects can then be reloaded on later requests and will have all their properties populated automatically.

Such behaviour can be useful in javascript-heavy applications, where complex javascript objects are used that don't map easily back to server-side data. In these instance, it is much easier to persist these objects on the client-side.

Once more, this extension relies on the Prototype javascript library to provide the mechanisms for class definition and inheritance.

The layer supertype is defined as follows:

There's nothing difficult here: this object composes an instance of the JsonCookies object and then persists the object properties in a JSON-encoded cookie when the save() method is called. On later instantiations, the object checks for a matching cookie and, if one exists, reloads the properties.

The only subtlety is to carefully choose an immutable id to identify the object. Of course, in the absence of auto-incrementing database fields to provide (meaningless) object ids, one would have to choose another suitable identifier which was immutable with respect to the object in question.

Basic usage would then involve defining simple subclasses:

var Person = Class.create(PersistentObject, {
name: null,
initialize: function($super, id) {
$super('person_'+id);
},
sayName: function() {
alert('My name is '+this.name);
}
});

Instances of this person object can then be manipulated as follows:

var me = new Person(1); // 1 is the immutable id for this person
me.name = 'David';
me.save(); // This writes the name data to a JSON-encoded cookie identified by person_1

// In later request, reload object
me = new Person(1);
me.sayName();

// And later on - best to clean up as cookie storage is limited
me = new Person(1);
me.delete();

A working set of unit-tests can be run that tests the above object using a simple stub - these use the JSUnit test suite.

Health warning

It should be noted that there are several shortcomings with using cookies for data persistence in this way To start with:

Cookie storage is limited to around 4kb and around 20 key-value pairs per domain. This covers all cookies including google analytics and other gubbins.
Cookies are transmitted over HTTP for every request. Having several JSON-encoded object strings in the header of every request is a rather unnecessary overhead.
Cookies are stored on the client's machine and are thus susceptible to tampering or snooping.

For these reasons, it is always a good idea to delete object cookies as soon as they are finished with.

Even with these limitations, persisting objects on the client-side is still a useful option - to be used carefully of course.

Update: the source code for this persistent object is now available through the Prototype extensions site Scripteka.

Javascript cookie objects using Prototype and JSON

nospam@example.com (David Winterbottom) — Fri, 07 Nov 2008 17:00:24 +0000

It's sometime useful to interact with cookies directly on the client-side using javascript. This can be useful for a variety of situations, such as persisting display settings between page requests without storing anything on the server. I've also used them to display a simple welcome message to new visitors. It can make your controller code simpler if this kind of simple display logic is contained entirely on the client side.

To this end, I use the following simple Cookies object, build on top of the Prototype Javascript library (version > 1.5):

The API is simple: cookie objects are created with optional path and domain arguments to the constructor. The set(), get() and clear() methods are then used to define the name=value pairs that cookies comprise. In addition, the get() method takes an optional third parameter for setting the expiry time in days if you want the data persisted longer than the current session.

Cookies can now be interacted with in the following manner:

var biscuits = new Cookies();
biscuits.set('show_nav', 'yes');
if (biscuits.get('show_nav') {
// Show the navigation...
}

The above object is useful for storing simple string data, but we can easily extend the above to allow arrays and objects to be persisted in the cookie by using JSON.

As we're overriding the set and get methods, the API remains the same:

// Persist some array data
var hobnobs = new JsonCookies();
hobnobs.set('selectedIds', [12,46,32], 7)

// On a different request, use the data
var hobnobs = new JsonCookies();
var selectedIds = hobnobs.get('selectedIds');
if (selectedIds) {
// Do something with the selected ids
}

As this object does not rely on the DOM in any way, it is easily testable as it requires little in the way of fixtures. What follows is set of unit tests that work with the JSUnit testing suite. You can run the unit tests directly, using the JSUnit test runner.

One minor shortcoming of the present version of JSUnit is that it is difficult to test equality of arrays and objects. The simple work-around used above is to test equality of their JSON encodings, which acheives the same end without resorting to looping through comparing property by property.

It should be noted that I am far from the first person to create Javascript cookie objects in this way - here are a few others doing similar things:

The main difference is that my objects use an inheritance structure to add the JSON-encoding facilities and throw errors when invalid arguments are passed. Also, I have another post in the pipeline which builds on these cookie objects to do something cool. Watch this space.