Users wishing to upgrade any large site from MooTools 1.1 to 1.2 can sometimes find it difficult. The API for 1.2 changed quite a bit, so without help upgrading your code can be fraught with danger.

Our solution is an upgrade helper that will allow you to replace your old MooTools 1.1 code with 1.2 code by logging deprecated methods to the console and telling you what needs to be changed.

The upgrade helper also attempts to automatically convert 1.1 calls to 1.2 calls. However, this helper is not really meant to be a compatibility script so much as a script designed to help you migrate your code. In almost all cases methods that have been deprecated or have had their API altered will provide feedback to the console when they are called. Ideally, developers will put this script into their environment with MooTools 1.2, use their application and change all the calls that throw warnings, then remove the upgrade helper from their environment.

You can download the upgrade helper on the MooTools Download Page along with current build of MooTools built for it. This companion library has all the functionality found in MooTools 1.1 (Drag, Accordion, etc. - some of these plugins moved out of MooTools Core and into MooTools More in 1.2).

Simply replace MooTools 1.1 with MooTools 1.2, include the upgrade helper, then include your site's code. Browse your site with a browser that provides a console API (we recommend Firefox with Firebug) and take note of the warnings thrown (note, you can adjust the logging; see the readme). Address these in your code base until you cannot find any more, then remove the upgrade helper. You have now an upgraded website, and you can use the plugins in the Forge!

If you still have warnings after you have finished converting your code, have a look at the documentation for 1.1 and 1.2 and also the source code in the upgrade helper. Most changes are simple, but may require a change of arguments. There are a few breaking changes but in the vast majority of cases these should not affect you. A complete list of the changes between 1.1 and 1.2 can be found in the readme of the github upgrade-helper repository.

The upgrade helper is being released as a beta for now. We've written and run tests against the browsers we support but the real world usage of MooTools will be the real test. As such, we hope that you, the MooTools community, will help us polish this script, by letting us know what features on your sites don't work. Bugs can be filed using the github issues for the repository.

Arguably, this is something we should have provided long ago. Going forward, we've pledged to make all releases 100% backwards compatible for all documented methods and features.

Should you require any guidance or assistance, you can, as always, find us in the #mootools IRC channel or post in the MooTools Google Group.

Last of all, massive thanks to Nathan White and David Isaacson, for their early work on this. In the last few weeks the MooTools Dev team has spent a lot of time making and testing this upgrade helper, but these guys kicked this off with their contributions and they are most appreciated.

Since the dawn of time, MooTools used a method named $ to get an HTML element by it's id or direct reference. This method name, being the coolest and shortest you can find in JavaScript, is also used by a number of other javascript frameworks and libraries for similar functionality. Now, we do not think including 2 libraries or frameworks is OK. It's not. Never. It's an overhead of duplication you do not want to have. However, you might not have the full control of the page in some circumstances, and we recognize that. That's why we implemented this: Dollar Safe Mode™. It's nothing special really, but it should help in those situations where including multiple libraries is not your choice (because if it is, quite frankly, you're doing everything wrong. Pick one, will you? And make sure it's MooTools :-)).

MooTools 1.2.3 DOM stuff doesn't depend on the presence of $ anymore. The method that used to be $ is now called document.id (short for identify). The method $ is still assigned when not already present in the page, and aliased to document.id.

But let me show you how it works:

Let's say you have mootools.js and a fictional JS library called jLib.js. Both use a method called $.

<script type="text/javascript" src="mootools.js" />
<script type="text/javascript" src="jLib.js" />

jLib would "steal" the $ method from MooTools. MooTools doesn't work unless jLib has some sort of no-conflict mode of its own that will allow you to prevent it from "stealing" $ from MooTools.

<script type="text/javascript" src="jLib.js" />
<script type="text/javascript" src="mootools.js" />

MooTools would "steal" the $ method from jLib, which may or may not work without it.

Scenario 1: Include MooTools first:

<script type="text/javascript" src="mootools.js" />
<script type="text/javascript" src="jLib.js" />

MooTools checks if a method called $ exists; if not, it defines it. In this scenario, MooTools defines it as it doesn't find anything named $, being included first. jLib "steals" the $ method from MooTools. MooTools doesn't care. MooTools now doesnt need $ to properly function. You can regain control of $ simply by reassigning it to its alias ($ = document.id).

Scenario 2: Include jLib first:

<script type="text/javascript" src="jLib.js" />
<script type="text/javascript" src="mootools.js" />

MooTools checks if a method called $ exists. It does find it, being included last, therefore it doesn't define it. You can directly use document.id() or assign your own var to it, or manually assign $ to document.id, if you would like MooTools to have control of it.

As you can see, it's pretty straightforward. In short, MooTools doesn't need $ to function anymore, and doesn't steal it from other frameworks when included after them.

The above applies for MooTools-Core and MooTools-More. However, MooTools plugins use the $ method, therefore, while not breaking MooTools by including jLib, you will break the MooTools plugins. If you desperately need plugins to be multiple-framework compatible, and you the other frameworks to have control of $, there are a few things you can do.

The first, most obvious and recommended option is to replace every call to $() with document.id() by hand. It doesn't take more than 10 seconds with a simple find and replace. This is probably what plugin authors should do, if they wish their plugin to be dollar-safe.

Another option is to encapsulate the plugin using a closure. This might come handy if you are processing a plugin that isn't yours:

var X = new Class({
    initialize: function(element){
        this.element = $(element);
    }
});

it should become:

(function(){

    var $ = document.id;

    this.X = new Class({
        initialize: function(element){
            this.element = $(element);
        }
    });

})();

As you can see, we've simply assigned $ as a local variable, using a closure. Everything in that closure will use document.id as its $ method. Remember to export the global variables though, as vars defined in the closure will stay private. I like to export globals using this., but you can use window. as well.

Please note that MooTools will probably remain incompatible with other frameworks that modify native prototypes, as there will probably be more name clashes. This isn't a cross-framework compatible MooTools version by any means, nor does it want to be. The whole point is not to "steal" the dollar function from other libraries.

And that's pretty much it about the Dollar Safe Mode™ in MooTools 1.2.3.