Migrating from the Prototype JavaScript Framework to jQuery

Here is a list of issues I encountered when upgrading the JavaScript code used for this website (AndyK Docs) from Prototype JS 1.6 to jQuery 1.4.2.
created by on 2010-03-29

When I started this website some years ago, I think it was somewhere around 2008, I used Prototype JS for all the client-side interaction required for a small blog like this:

And if I remember correctly, the first version of this website (2006-2007) was not a PHP application but the web-interface of a full-blown Lotus Notes / Domino 6 database which I hosted on my own little Domino Server. I used this Lotus Notes document repository primarily for the knowledge- and document management during my studies at the University of Paderborn, but I extended the database with a web interface that offered a subset of the documents over the Domino’s HTTP-Task with an user-interface which is quite similar the this website as it is now.

This early version of AndyK Docs did use some custom JavaScript functions for a simple AJAX search interface, but did not utilize Prototype or any other JavaScript framework as we know them today.

Why did I use Prototype JS?

Prototype JS was first released in 2005 and back then was one the the most-popular JavaScript-frameworks. I first noticed Prototype JS when I stumbled upon the scriptaculous (or script.aculo.us) JavaScript library for dynamic web-user-interfaces and visual effects. The Script.aculo.us library is a great collection of JavaScript functions for enhancing web pages which neat visual-effects (fade-in, fade-out, puff, pulsate, highlight, shake), useful web-controls such as a Slider, an Autocompletion-control or an InPlace-Editor and convenient utility-functions for creating DOM elements. And the foundation for all these functions is the Prototype JS Library.

Besides the animation capabilities of the scriptaculous library, Prototype offers a wide range of fundamental functionality which can be used in all major browser versions. The functions I used the most where certainly the dollar-selector-functions and the HTML element-related functions for creating and manipulating DOM elements. Followed by the Array- and Enumerable-extensions (such as the each-method, the unique- and the reverse-function). And finally the Prototype’s Ajax-capabilities:

The Ajax.Request, Ajax.PeriodicalUpdater and Ajax.Updater functions allow easy access to remote APIs and data.

In short:

Why migrate from Prototype to jQuery?

So why would I go through the pain of a migration, if Prototype (and Scriptaculous) is such a feature-rich and reliable JavaScript library?

The answer is short and simple:

Prototype is dead*. And jQuery is on fire.

* Or at least less alive than jQuery 😉

Even though the code of Prototype framework has a very high quality and the compatibility with the different browser-types is still extremely good (and seems almost timeless to me), the version history of
the Prototype Framework
draws a clear picture and proves my point, that is is time to move on to something new:

As of today (2010-04-05) the latest release of Prototype JS is the version 1.6.1 and was published in September 2009 - almost one year ago.

The prototype.js file for itself is already 136 KB heavy and there is no (official) packed and minified version available for download. Scriptaculous pointed in the right direction with its modular approach - loading only the libraries that are actually required for the current scenario, but the problem is Prototype with its all-in-one architecture. The Prototype library offers way to much functionality and isn’t targeted towards a lightweight architecture.

And that’s where jQuery comes into play.

The Taskspeed Benchmark Result-Chart for the comparison of the jQuery 1.3.2, jQuery 1.4.1, jQuery 1.4.2, Prototype 1.6.1, MooTools 1.2.4, Dojo 1.4.1 and YUI 3.0.0 JavaScript framework performance, by browser (Firefox 3.5, Firefox 3.6, Opera, Safari, Chrome, Internet Explorer 8, Internet Explorer 7, Internet Explorer 6)

In the end I don’t want to convert you to one framework or the other. Both frameworks are reliable, have a huge community, many useful plug-ins and (in the end) a (very) similar syntax and functionality.
I liked Prototype JS a lot in the past, but I think it’s time to move on to something new now.

Migration steps: Transforming your JavaScript code from Prototype to jQuery

Even though the syntax of Prototype and jQuery do not differ that much and there many similarities
between both JavaScript frameworks, there are a couple of things to keep in mind while migrating.

Selecting DOM elements

The function that are used the most are the dollar-utility methods for selecting DOM elements:

$(elementId) function calls must be handled with caution because a missing ’#‘-sign in front of the selector can cause you a lot of grief.

For a quick-migration you can simply use a text-editor that supports Regular Expressions (e.g. UltraEdit, Notepad, Eclipse), search for this pattern /$(['"]([a-z0-9_-]+)['"])/gim and replace it with this pattern $('#$1').

Or, you can try the “Prototype-To-jQuery-Migration-Script” I created along with this little migration-guide.
The JavaScript-based online-migration-script automates the transformation of your Prototype code to the jQuery syntax and may speed up your Prototype-migration a little. Just try out the online migration script or see the next section where I’ll describe it in more detail.

Screenshot: Migrating from Prototype JS to jQuery using Regular Expressions. Searching for dollar-function calls that will be replaced with a new selector.

But, I would recommend you to manually review every single reference of a $(elementId) function-call in your code in order to ensure that you have an ‘#’ in front of your elementId where you need one - this will spare you long hours of debugging.

And it’s a good chance to review your code and improve your code-quality.

Since the Prototype Element.select()-function has a matching part in the jQuery library, you can simply replace all occurrences of .select( with .find(

Get and set the content of HTML elements

Function-calls that I encountered the second-most during my very own migration process were function calls for reading/writing the values of form-elements and getting/setting the HTML-contents of DOM-elements:

$F(element | selector | elementId) or $(element | selector | elementId).getValue() function calls must be transformed to match the jQuery syntax: $(element | selector | elementId).val()

At first you must make sure that you migrated all $F(elementId) function calls to match the new jQuery syntax.
This can be done with these two little regular expressions.

Find-Pattern: /$F(['"]([a-z0-9_-]+)['"])/gim
Replace-Pattern: $F('#$1')

The regular expression for finding and transforming the relevant code segments with $F function-calls could look like this:

Find-Pattern: /$F(['"]([#a-z0-9_-]+)['"])/gim
Replace-Pattern: $('$1').val()

Using these regular-expression for the parts of your migration process that are pure and simple monkey work can save you a lot of time, but keep in mind that they are not perfect.

Code blocks that use the standard innerHTML JavaScript property (→ $(element | selector | elementId).innerHTML) for manipulating the content of DOM elements must use the .html() function of the jQuery library.

Get HTML content

Migrating the innerHTML property to the jQuery syntax is a little more tricky than the examples listed before, but you can give it a try with these regular expressions.

Find-Pattern: /$(['"]([^)]+)['"]).innerHTMLs*=s*(["']*.+["']*);/gim
Replace-Pattern: $('#$1').html($2);

Set HTML content

Migrating the innerHTML property to the jQuery syntax.

Find-Pattern: /).innerHTML([^=]*);/gim
Replace-Pattern: ).html()$1;

If you want to test, adapt or improve the regular expressions listed here with your JavaScript code, you can do so with an awesome website for testing RegExps:

http://gskinner.com/RegExr/

The functionality of the Prototype-Element.update() method for setting the contents of DOM elements is as well as the .innerHTML property reflected by the jQuery .html()-function.

The migration from .update() to .html() can be done with a simple search & replace operation.

Updating the style and CSS of DOM elements

The functions and methods for setting new style attributes, adding CSS class names to HTML elements or removing classes are completely alike in both JavaScript frameworks and require very little migration-efforts.

A simple set of search & replace operations will suffice to migrate your Prototype code with HTML-style related functions to the jQuery syntax.

Getting and setting element attributes

Another common type of operations that are used quite often are actions like reading the href-attribute of a link-element, setting the id-attribute of a newly created DOM element or setting the width and height of a div-container.

Events

Binding events to DOM-elements is another important topic for all JavaScript frameworks and is of course equally well implemented in Prototype and jQuery - even though jQuery offers more native event-handlers such as click, dblclick, mouseover, keyup and many more.

Ajax requests

The migration-procedure between the Prototype-Ajax syntax and the jQuery-Ajax syntax is a little bit more complicated than the examples above. Again, the concept and the syntax do not differ significantly, but this special case is a little bit too tricky (for me) to create a regular expression for it which does the transformation.

Search for the text string Ajax.Request in your Prototype JavaScript code and manually transform the signatureof the Prototype Ajax.Request to match the jQuery.ajax function signature.

If you have a text editor that supports multi-line regular expression searches, you can also the following RegExp to highlight all code blocks using Prototype Ajax.Request.

Find-Pattern: new Ajax.Request(([^});] )});
Replace-Pattern: <blank>

Screenshot: Using UltraEdits multi-line, regular expression search and replace functionalities to transform a Prototype JS Ajax.Request to jQuery

See the comparison-table below for further migration instructions.

Creating new DOM elements

Creating HTML elements from scratch is another frequently used function of a JavaScript framework. And because the syntax is pretty much the same in jQuery and Prototype, the migration is nothing than a simple search & replace operation.

Automatically migrate Prototype to jQuery

I assembled a little JavaScript-based application that can help you transform your old Prototype code to the jQuery syntax.

The migration-script combines all the migration-steps and regular-expressions listed in the sections above and run executes them on the code you can paste into the input-area of the online-migration tool:

Screenshot 1: Automated Prototype-to-jQuery migration tool. Paste your Prototype JavaScript code into the input-area of the online-migration-tool and press migrate-now. (jQuery, Migration, Tool, AndyK Docs, Prototype, Screenshot, Andreas Koch)

→ Using my little Prototype-to-jQuery migration script can speed-up your migration process a little.
But please let me know if it really worked for you.

Comparing Prototype to jQuery

The following section contains a comparison-table which contrasts some of the frequently used functions of the Prototype framework with their jQuery counterparts and highlights the differences.

The table is quite big - so it cannot be displayed with its full witdh, but you can also view the jQuery-migration cheat sheet (in its full size) if you open either the HTML-file, the PNG-Image or the PDF-document below:

Is it worth it?

A migration is always a lot of pain and you might ask yourself if it is worth it.

And for myself the answer is yes.

It took me a couple of hours of (mostly dull) work, but I took the opportunity to refactor and some of my old code along the migration process and made it “better”. AND I’ve got the good feeling that I am no longer using a dead horse (even though it was a good one).

Links & Resources

Here are a couple of links that can help you with your own migration process or might help you decide
whether to migrate your Prototype code to jQuery, or not.

The two JavaScript frameworks

Tools & Resources

JavaScript framework performance

Further Articles

Pictures

Migrating-Prototype-JS-to-jQuery-Cheat-Sheet-Version-1-1902x4186.png
Screenshot-Migrate-from-Prototype-to-jQuery-Notepad-Plus-Plus-Regular-Expression-Ajax-Request-multi-line-search-width-Ultra-Edit-01.png
Screenshot-Migrate-from-Prototype-to-jQuery-Notepad-Plus-Plus-Regular-Expression-dollar-function-replace-02.png
Screenshot-Migrate-from-Prototype-to-jQuery-Notepad-Plus-Plus-Regular-Expression-dollar-function-replace-03.png
Screenshot-Migrate-from-Prototype-to-jQuery-Notepad-Plus-Plus-Regular-Expression-dollar-function-search-01.png
Screenshot-Migration-Tool-Version-1-Transform-Prototype-Code-To-jQuery-01.png
Screenshot-Migration-Tool-Version-1-Transform-Prototype-Code-To-jQuery-02.png
Taskspeed-Benchmark-Chart-Comparing-Performance-of-jQuery-Prototype-MooTools-Dojo-and-YUI-3.png

Shortlinks:
Tags: