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!
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.
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.
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.
- An Overview
- The Hash
- Accessor Functions (think Python's descriptors)
- Storing Custom Data in Elements (my favorite new thing)
- Fx enhancements
You don't need to read these now, but they're here if you need them
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).
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.
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.