Siafoo – the intersection of pastebin, help desk, version control, and social networking Join Siafoo Now or Learn More

Upgrading to MooTools 1.2 - Tips, Tricks, and Backwards Compatibility Atom Feed 0

MooTools is an awesome, lightweight Javascript library. The second major version (1.2) just came out and you want to upgrade, but the backwards-compatibility sucks. I've created a custom compatibility file that should solve *most* of your problems; here's what you need to do...

MooTools is a lightweight, efficient Javascript enhancement library. It has all of those functions that you wish Javascript had to make your life easier. It gives you automatic workarounds for many browser-specific bugs.

Unfortunately, the Powers That Be at MooTools didn't decide to make version 1.2 backwards-compatible with version 1.1. There are some compatibility libraries, but they still don't do a complete job (or even close to one).

This article aims to be a clearinghouse for tips, tricks, and other information about upgrading to MooTools 1.2. Feel free to add any that you might have!

1   Get The Code

1.1   MooTools

MooTools 1.2 is divided into two libraries: "Core" and "More". Core contains the vital components, while More contains plugins and effects to stop you from having to write such things yourself. For each one, you can select which modules you want to include -- in my experience you might as well download everything for development; you can always go back and remove modules you don't end up needing:


If you're doing ANY debugging, make sure you disable compression and enable code comments in these downloads. Look near the bottom of the form for these options.

1.2   Compatibility Libraries

Since you're upgrading from 1.1, you'll also want the compatibility libraries. (Note that these are direct links, you probably want to 'Save link as' or whatever.)

Awesome. Make sure you load these in a reasonable order in your webapp (I load the four in the order above), and you're ready to go.

Don't delete the old MooTools yet though, you might need to compare it with the new one to figure out why something isn't working as expected.

2   Know Your Enemy

The most important thing you can do right now is to take a few minutes and read about what's different in 1.2. That way when you come across a new feature you won't be scratching your head for an hour. Trust me, it's totally worth it.

2.3   Docs and Demos

When you're debugging an upgrade problem, it can be useful to compare code, documentation, and demos between versions. You've already got the code; here are the docs and demos:

3   Here We Go

3.1   A Custom Compatibility File

I've created a custom compatibility library based on my experiences getting MooTools to work. My goal was to change none of my code, to just have a drop-in compatibility library, and I was nearly successful.

It is by no means complete, but give it a shot. If you find any other problems with backwards compatibility, see if you can find a universal fix and add it to this file:


The XHR class in mootools-1.2-compat.js is implemented incorrectly. If you don't use the above compatibility file, be aware of this. It expects to be initialized with (url, options) where the original XHR class only expected (options).

3.2   Sizes and Scrolls

Mootools 1.2 changes the definition of Element.getSize() rather drastically. There's not really a way to simultaneously preserve backwards- and forwards-compatibility here, so I recommend you perform these search-and-replaces in your code:

  • getSize().size -> getSize()
  • getSize().scroll -> getScroll()
  • getSize().scrollSize -> getScrollSize()

Doing global search-and-replace-all should be fine, I think.

3.3   Miscellaneous

There are a few more things that I haven't been able to fix with a backwards-compatibility file...

  • Element.getElement(): If you are searching by id, this function no longer finds elements which are not children of the document node. I've opened a bug for this (Bug #203); I don't have a great workaround. :( Finding elements by class still works.
  • Fx.Slide wraps your element in a div (and always has), but now that wrapper div inherits the position of the wrapped element when Fx.Slide is instantiated. This broke a hack I had, but I suppose is more correct.
  • In the Ajax class (now implemented via the Remote class), the event 'complete' is now called just before the event 'success'. I figure that though this breaks my code, that's more of a design flaw on my part as I think they should be considered simultaneous.
  • The Fx and Fx.CSS internals work completely differently now... since we weren't supposed to be using them in the first place I just rewrote my class that uses it, and not a compatibility layer. It would probably just be the entire 1.1 Fx.CSS class anyways.


over 11 years ago (11 May 2009 at 12:23 PM) by dfediuk
Links to Compatibility Libraries in the 1.2 paragraph are broken.
over 11 years ago (11 May 2009 at 01:54 PM) by Stou S.
Thanks for reporting this... I actually couldn't find the files on the mootools web-site so I just uploaded my local copy.