Here's a hacker's lesson I learnt the hard way — if you're going to make any changes or additions to a JavaScript library don't do it directly in the source code for that library.

Remember my Drag-n-Drop Sorting of Documents article from this time last year (Rough Cut? Huh!)? Here's a demo. It uses the scriptaculous drag and drop to convert a simple <ul> element in to a sortable list. Re-sorting this list sends a POST message to Domino to tell it the new order of the documents. To get this to work with Domino I had to hack the code a little..

The scriptaculous Sortable object has a method called serialize:

The Sortable object also provides a function to serialize the Sortable in a format suitable for HTTP GET or POST requests. This can be used to submit the order of the Sortable via an Ajax call. See Sortable.serialize

So, given a UL element with an id of "SortOrder" and three child LI items the serialize method will produce a string like:

This can then be POSTed to the server for processing. Domino inerprets POST data with repeated keys as a multi-value item. The use of []s is a Rails/PHP convention which confuses Domino and so I had to get rid of them, so that the string would look like:

To do this I found the serialize method in scriptaculous's dragdrop.js file and removed the [] from the line of code with the comment shown below.

var Sortable = {
  serialize = function(element) {
    element = $(element);
    var options = Object.extend(Sortable.options(element), arguments1 || {});
    var name = encodeURIComponent(
      (arguments1 && arguments1.name) ? arguments1.name : element.id);
    
    if (options.tree) {
      return Sortable.tree(element, arguments1).children.map( function (item) {
        return name + Sortable._constructIndex(item) + "[id]=" + 
          encodeURIComponent(item.id)].concat(item.children.map(arguments.callee));
      }).flatten().join('&');
    } else {
      return Sortable.sequence(element, arguments[1).map( function(item) {
        return name + "[]=" + encodeURIComponent(item); //removed the [] from here!
      }).join('&');
    }
  }
}

This change I made in the source code itself. Cue one year later and I'm working on a new version of an application for a customer, which uses this sorting feature. This seems like a good time to upgrade the versions of Prototype and Scriptaculous in use to the most current, so I do. Expecting problems due to the upgrade, I test it all out, only to find the sorting feature is broken. After some messing about I found the extraneous [] characters and it dawned on me what I'd done wrong — the upgrade had over-written the old JS file and so my hack went with it.

To fix this the easiest option would have been to re-edit the scriptaculous dragdrop.js file and make the same change again. However, this would be stupid and have meant I'd learnt nothing from having wasted an hour of time scratching my head. What I needed to do was make the change, but not in the dragdrop.js file, so that any future upgrades wouldn't break the application.

What I did was leave the source code alone and then place the following snippet of code in my own "global.js" file:

Sortable.serialize = function(element) {
    element = $(element);
    var options = Object.extend(Sortable.options(element), arguments1 || {});
    var name = encodeURIComponent(
      (arguments1 && arguments1.name) ? arguments1.name : element.id);
    
    if (options.tree) {
      return Sortable.tree(element, arguments1).children.map( function (item) {
        return name + Sortable._constructIndex(item) + "[id]=" + 
          encodeURIComponent(item.id)].concat(item.children.map(arguments.callee));
      }).flatten().join('&');
    } else {
      return Sortable.sequence(element, arguments[1).map( function(item) {
        return name + "=" + encodeURIComponent(item);
      }).join('&');
    }
}

As my global.js file was referenced below the scriptaculous files in the page's header it was loaded afterwards and so the original Sortable.serialize method was over-written by my own. Any upgrades to dragdrop.js in the future won't break my code.

Moral of the story being — if you're going to hack a JavaScript library do it in your own space.