Upgrading to MooTools 1.2 - Tips, Tricks, and Backwards Compatibility

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:

• MooTools 1.2 Core
• MooTools 1.2 More

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.)

• MooTools 1.2 Core Compatibility File
• MooTools 1.2 More Compatibility File (Smallest file ever)

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.1   Enhancements

• An Overview
• The Hash
• Accessor Functions (think Python's descriptors)
• Storing Custom Data in Elements (my favorite new thing)
• Fx enhancements

2.2   New Features

You don't need to read these now, but they're here if you need them

• Behavior Driven Development (aka Specs... aka basically unit tests)
• "Swiff" for Javascript-Flash interaction

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:

• MooTools 1.11 Docs
• MooTools 1.11 Demos
• MooTools 1.2 Docs
• MooTools 1.2 Demos

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:

• MooTools 1.2 Custom Backwards-Compatibility Library

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.