MooTools - Home

Calling All Plugins

2008-06-24T00:23:00Z

One of the main things missing since the forums have gone into read only mode is the Your Scripts section. We realize this and are working to complete our own plugin directory.

We’re trying to assemble a comprehensive list of all our plugins. As part of this effort, we’re asking all plugin creators to send an email to plugins@mootools.net with the following information:

Plugin Name
Plugin URL
Plugin Description (one line)
Plugin author name and link (if applicable)

At this time, we’re only interested in collecting data on plugins which are compatible with the 1.2 release.

This is a temporary measure until we get a more interactive system in place.

MooTools 1.2: It's Official!

2008-06-12T18:35:00Z

I speak for everyone the MooTools team when I tell you that we are extremely happy to announce the official release of MooTools 1.2. After a year of development and six months in beta, you might call us perfectionists. But now we’re finally ready to call the 1.2 release complete and stable. For those of you who have been waiting to make the switch, now would be the perfect time.

Not only has the API been completely revamped, but there have been several significant changes to the site and the way the MooTools community interacts.

Why the Rush?

You may have noticed that the 1.2 release has come, quite literally, overnight. Over the past few months, we’ve come to realize that the 1.2 beta is even more stable than the “stable” 1.11 release. In fact, many developers (including some of us on the Moo team) have been using 1.2 in critical applications for some time now.

Users coming into #mootools asking for support have been unofficially told to by us to upgrade to 1.2 for months. Reluctant as we were to let ourselves call our work on 1.2 “complete”, the reality finally hit us that it was time to officially offer our release to the entire development community. We therefor decided to “just do it”, flipping the final switch and changing to the new version of the site before this blog post and some areas of the site were completely functional.

Where Have the 1.11 Docs and Demos Gone?

The 1.11 docs have been moved to http://docs111.mootools.net. Conversely, the 1.2 docs have been moved from http://docs12b.mootools.net to the main docs subdomain (http://docs.mootools.net). The same is true for demos.

1.2 is Totally New

Don’t let the version number fool you. 1.2 is not merely a minor revision of 1.11. As those of you who have been reading the blog will be aware, 1.2 has a completely updated API and is not compatible with 1.11 code. You can, however, utilize the compatibility layer that has been built to make the transition to 1.2 easier.

Since most of the changes between 1.2 and 1.11 have been documented in earlier posts to this blog, I won’t go into the details here.

Offsite Hosting of Version Management, Tickets, and Discussions

Because of the increasing popularity of this project of ours, we have been under an increasing amount of stress to keep the various parts of this site running in good order. You may have experienced downtime relative to MooTools recently. We understand that many developers utilize MooTools in critical components of their projects, and such downtime is completely unacceptable.

To solve these issues for the 1.2 release, we have moved our critical components offsite to the best provider of each component, granting MooTools users with the highest possible uptime of all areas of the site. A major benefit of this move is being able to completely reinvent the way we interact with our community of users (aka you guys!).

Git

Along with the 1.2 release comes our shift from Subversion to Git. Git is a huge step forward to our development model, allowing everyone who wants to contribute to MooTools the ability to create their very own fork. Each fork can then be merged into the main core as seen fit or used on its own as an alternate version of MooTools. This allows us to release faster, iterate to better versions and better handle the contributions of the community.

This allows would-be contributors to play in their own sandbox without worrying about whether or not their suggestions are appropriate. So get forking!

Please note that the Subversion repository will no longer keep up with changes to MooTools. You will have to check out the Git repository for that.

To keep the core lean and mean, we have created a separate repository for plugins, called “More”. Plugins are defined as specialty components which aren’t crucial to the core functionality of MooTools. This includes modules which have been part of the core distribution until now.

You’ll also notice that the download page has been split into two pages, one for Core and one for More. (Further repositories may be coming in the future if we can think of more rhyming names.)

GitHub

We’re using GitHub to host our new Git repositories. We now have one respository for Core and another for More. The folks over there have given us an extremely warm reception, and we are likewise very happy to have such a great service at our disposal.

Bug Tracking by Lighthouse

We have abandoned our Trac, which has been giving us problems over the past weeks, for Lighthouse. Lighthouse allows us to integrate our ticketing system with our new Github account and should provide everyone with a comparable experience to our previous system.

You can visit the new Lighthouse account here.

New MooTools User Group

As part of our offsite initiative, we have moved the community forum to Google, where it hopefully will not crash and die. The forums will be back shortly, but only as a read-only archive.

Join Us on IRC

While we’ve been partying in the IRC room for quite some time, the IRC link to #mootools on Freenode has been added to the main page of MooTools.net. If you have not visited us there before, please feel free to stop by to ask your questions or just hang out. We love chatting with new users.

New Faces

One last note is that we’ve added two new members to the MooTools production team, Jan Kassens and Thomas Aylott. Both of them have been working extremely hard for quite some time now to bring you a better framework, and we’re very happy to give them formal recognition.

Links In Case You Missed Them

Docs and Demos

Compatibility

Git Repositories

Core Repository
Plugin Repository

THE SUBVERSION REPOSITORY WILL NO LONGER BE UPDATED.

Bug Tracking / Tickets

MooTools at Lighthouse

Community Discussion

Snippely!

2008-03-15T18:52:00Z

With the initial release of Adobe AIR, a lot of web developers (myself included) are starting to get excited about developing rich web applications that run natively on the desktop across platforms. We've already seen several great AIR apps popping up all over the Internet, and thought we'd try our hand at creating one of our own.

Snippely was created by myself, Tom Occhino, and Valerio Proietti as our first attempt at creating a robust and useful AIR application.

What can we do with MooTools and a little bit of fresh AIR?

When we were thinking about what type of application to make our AIR playground, we tried to think of something that we'd want to use ourselves. Valerio and I are notorious for storing countless bits of code in all sorts of different languages all over our hard drives, and thought it would be nice if we had a central place to store and organize those bits of code. We came up with the idea of 'snippets', and an application called Snippely.

Snippely was born...

Snippely is a basic text and code organizational tool. Instead of storing bits of code, quick notes, and memos in text files all over your hard drive, this application will let you save and organize "snippets" in one convenient location. A snippet is a collection of one or more pieces of code and notes. Snippets are stored in groups for organization and quick retrieval.

A snippet is composed of a title, description, and one or more 'snips'. You can add any number of note and code snips in a variety of different languages (more to be added). When not being edited, the snip will be syntax highlighted according to the language selected. Snips are also sortable so you can organize your snippet however you want. Since everything is saved to a local database as you work, there's no need to worry about pressing the save button or submitting a form.

Usage is pretty self explanatory, but I may post a screencast within the next day or two to get everyone familiar with how to use the app.

Initial release

Snippely is an open source project released under an MIT Style license. It is hosted on Google Code so feel free to browse through and play with the source code. If you'd like to contribute to Snippely, contact either myself or Valerio (preferably in the IRC channel).

While we do plan on adding more to the app, we wanted to get the first version out there so we could see what everyone thinks. It's been developed and tested mostly on OS X, but since AIR is inherently cross platform, it works perfectly on Windows as well.

Download

Note that the Adobe AIR runtime must be installed to run Snippely.

Adobe Air Runtime (required)
Snippely Installer - Installer, version 1.0
Snippely Source - zipped source code, version 1.0

What's New in 1.2: Swiff

2008-02-12T15:17:00Z

Today we're going to talk about Swiff, which lets you combine Flash and JavaScript to do things MooTools can't do on its own.

What's Swiff ?

Though an earlier version of Swiff has been packaged with Harald's FancyUpload, it's officially new the MooTools 1.2 distribution. Swiff allows for communication between Flash movie (.swf) files and the page's JavaScript, opening up possibilities not available with JavaScript alone.

The Best of Both Worlds

Unless you're a diehard fan of the embedded Quicktime movie, you might see the benefit in a Flash video player to provide smooth playback of videos to your users, while still yearning for full control over the action using JavaScript and MooTools.

It's not even necessary for the Swiff object to be visible in order to benefit from its use. Using Swiff, you can utilize all of Flash's functionality, including its video, sound, file streaming, and clipboard accessing features, and lots more.

You get all the flashiness of Flash, while still being able to manipulate and display your content using the DOM and MooTools.

Talking to Flash

The first thing you'll want to do when creating a Swiff script is to create the Flash file. In most cases, the "stage" of the Flash file will be empty, the only content being within the action box. You'll have to write ActionScript that's able to interface with Swiff.

A basic ActionScript file might look something like this:

//(ActionScript)
import flash.external.*;

function echoText(text) {
    ExternalInterface.call('alert', "This message is from Flash: "+text);   
}

//Fires the 'onLoad' event within the Swiff object.
ExternalInterface.call(onLoad);

Once you finish writing the ActionScript, you'll have to publish your .fla file into a .swf file. Now we're ready to load the SWF file with Swiff:

//(JavaScript)
var obj = new Swiff('mySwf.swf', {
    width:  1, 
    height: 1, 
    container: $('swiffContainer'),
    events: {
        onLoad: function() {
            alert("Flash is loaded!")
        }
    }
});

In this example, when the SWF file is done being loaded, the window will alert "Flash is loaded!".

Notice that, although the Swiff object in this example doesn't need to be visible, its dimensions are set to 1x1 pixels. If the object is not visible in the browser (ie, if the dimensions are 0x0), problems may occur.

Calling Flash Functions From JavaScript

The main reason to load a SWF file is to call the ActionScript functions within it. To do this, we can use the Swiff.remote method, like so:

Swiff.remote(obj, 'echoText', 'Hello Flash, meet Swiff.');

However, if we run this immediately after our call to new Swiff, this line will most likely fail, because we first have to wait until the SWF is loaded (just like how we have to wait to make sure the DOM is loaded when we want to access its elements).

Our onLoad event does for Flash what the DomReady event does for pages. It lets us know when the SWF file is ready to be accessed by the JavaScript.

So, in order to call methods within the SWF file, we'll have to put the code that calls them inside our flashIsLoaded function, like so:

//(JavaScript)
var obj = new Swiff('mySwf.swf', {
    //[...]
    events: {
        onLoad: function() {
            Swiff.remote(obj, 'echoText', 'Hello Flash, meet Swiff.');
        }
    }
});

Letting Flash Know To Expect Us

If you're following along at home and not set up with any sort of special Flash development tools, you might notice that your browser crashes when this code is executed (hopefully you're just reading and not following along).

This is because we forgot to tell Flash to expect our JavaScript to talk to it. We can do this easily with a call to ExternalInterface:

//(ActionScript)
ExternalInterface.addCallback("echoText", this, echoText);

Now, we can try our call to Swiff.remote again and, instead of a crashed browser, we should be rewarded with a fancy new alert message. It should say, "This message is from Flash: Hello Flash, meet JavaScript."

Passing Variables to the SWF File

What would happen if you decided to pass options or other variables to the ActionScript? Manually going back into the Flash file, changing the call, and then republishing the SWF file seems horribly inefficient, and it wouldn't work if we want to change them dynamically.

Luckily, passing variables to the SWF is very easy. All we have to do is add a 'vars' property to our new Swiff, containing an object that lists all of the variables we want to pass.

//(JavaScript)
var obj = new Swiff('mySwf.swf', {
    //[...]
    vars: {luckyColor: 'blue'}
});

Let's add a getLuckyColor event to our ActionScript:

//(ActionScript)
function getLuckyColor() {
       return luckyColor;
}
ExternalInterface.addCallback("getLuckyColor", this, getLuckyColor);

Now, let's change our onLoad event to get it to tell us our lucky color:

var obj = new Swiff('mySwf.swf', {
    //[...]
    events: {
        onLoad: function() {
            alert("Your lucky color is "+this.getLuckyColor());
        }
    }
});

Notice that we used this.getLuckyColor instead of Swiff.remote(obj, 'getLuckyColor')? We're using an alternate syntax to call Flash methods.

The Swiff.Remote Alternative

Swiff.Remote isn't the only way to access functions within the SWF file. You can also call methods on the Swiff object directly, like so:

obj.echoText("Hello, Flash.  We skipped a call to Swiff.remote!");

Both ways will work, so it's up to you to choose which one is best for your needs. As in our use of this.getLuckyColor() within our onLoad event, the second syntax often makes a lot more sense.

In this way, we can think of our Swiff objects as wrappers around the functions inside our ActionScript, and can use them like we would use any normal MooTools Class.

Go Have Fun!

This article, of course, has only covered the basics, which means there's still a lot for you to learn. The best way to master Swiff is to go get yourself the latest copy of the 1.2 beta and have yourself a Swiff party.

Good luck, and have fun reading the ActionScript documentation!

MooTools Classes: How to use them

2008-02-05T18:26:00Z

A very entry-level article: if you think you can beat MooTools Hero in expert mode, feel free to totally skip this.

Cars

So, what is a Class? A Class is a car factory. A factory that throws out an infinite number of cars.

If you need to make a trip, then another one, then another one, you will probably use the same car over and over. Only if you decide to change something about your car, like the engine, or the color, or the materials for the seats, then you'll need another one.

Let's make a totally facetious example out of it, and buy a Car from the Car store! Say I want to buy a Smart Car:

var mySmartCar = new Car({model: 'smart'});

Now that I have my car, it's parked in my virtual garage. Let's make a virtual trip!

mySmartCar.goTo('Washington DC');

That was nice! Let's go to NYC:

mySmartCar.goTo('New York');

As you can see, I'm using the same car to go to Washington DC and New York City. They're geographically close, so my smart car will suffice. What happens if I need to cross the cold Russia? Then I'm gonna need another car. A bigger, more powerful car. That's exactly when I must use new again.

var myBigCar = new Car({model: 'Jeep'});

Let's use it now:

myBigCar.goTo('Russia').goTo('China');

I wish going to China was this easy. :P

Classes

In MooTools, we have classes to perform different types of actions. We have Classes that deal with data (Request) or classes that display visual effects (Fx) and many more that I'm not talking about here today.

Fx.Morph, for example, is your factory. It makes Fx.Morph cars. Let's buy a car now: I want it to have a duration of 1000 ms, and I want it to be linked to this certain HTML element called "element":

var myMorph = new Fx.Morph(element, {duration: 1000});

I have a car now, that we call Instance. Let's use it to change the height and width for the element previously specified to 200:

myMorph.start({height: 200, width: 200});

Nothing easier.

These days, I see the same mistake being made over and over again: People buy a Car, and they make only one trip with it:

new Fx.Morph(element, {duration: 1000}).start({height: 200, width: 200});

This is usually attached to a click event, which makes things even worse:

element.addEvent('click', function(){
    new Fx.Morph(this, {duration: 1000}).start({height: 200, width: 200});
});

Well, this is not how ~~life~~ MooTools works! Just like in real life, there is no need to buy a car each trip you make, unless you want to significantly change the properties of this car. This use and discard approach is wrong in so many ways.

First of all, it's memory inefficient, as a new Class instance is created every time you click the button. Second, it's also speed inefficient, as the class constructor is called every time you click the button. Third, using this approach will make it impossible to take advantage of the Instance properties.

In the Fx Class Instances there are a number of properties and checks being made to see if the effect is in execution, and a number of options you can define to determine the behaviour of subsequent start calls if a previous one is still running.

This is how you write the previous example correctly:

var myMorph = new Fx.Morph(element, {duration: 1000});

element.addEvent('click', function(){
    myMorph.start({height: 200, width: 200});
});

This way, I create the Instance only once, and reuse it every time the user clicks the button! It won't screw up the effect for multiple clicks, and our OCD will have a rest for a change.

Same goes for the Request classes. What happens if I send the same request multiple times? Should I cancel the last one? Should I send both? Should I queue them?

If you do not properly use instances, a new request will be made each time. Same goes for Fx: a new fx on the same element will start at the same time, basically screwing up the whole animation.

MooTools is not Script.aculo.us

This approach of "use and discard" was used (and its still used afaik) in Script.aculo.us.

As an early scriptaculous user, I always struggled with the "multiple start calls" problem, and more often than I should, I took advantage the onComplete (afterFinish, in Script.aculo.us) option to set flags, and checked them in my click events, to avoid multiple executions at the same time.

That's exactly why I decided to write my own effects library, called moo.fx (which evolved into MooTools), so I could use classes--and their instances, as reusable objects.

This is not to criticize the Script.aculo.us approach. Since the library is designed to work that way, that's exactly how you should use it. MooTools however, is not designed to work this way, and using it the same way as Script.aculo.us is a mistake.

What's New in 1.2: Element Storage

2008-01-22T18:13:00Z

Another new feature that's been built into the latest version of MooTools is the Element Storage. This article describes the usage of this great new feature, as well as why it was developed, and how it can be used to keep your applications organized and efficient.

What's all this storage business about?

When developing advanced JavaScript applications, it's sometimes beneficial to associate extra properties or attributes to DOM Elements. While we have always been able to use DOM Elements as storage containers for all sorts of other data, this generic technique has a few drawbacks. While the problems associated with this technique are almost exclusively Internet Explorer problems, they must be dealt with nonetheless.

Let's consider the following simple example:

var element = $('myElement');
element.effectInstance = new Fx.Tween(element, 'color');
element.customProperty = 'someProperty';

element.effectInstance; //the Fx.Tween instance
element.customProperty; //'someProperty'

As we know, IE doesn't like when objects are stored as Element attributes in this way, and the effectInstance property will leak if it's not manually managed. Another problem we've seen is that when accessing the innerHTML of any parent of our element, IE will return simple custom properties (like strings, numbers, etc) along with the expected properties. This means that customProperty would be copied as well, which could pose a problem if it was some unique custom attribute. Obviously of the two cases, memory management is our biggest concern here, but both are issues to consider.

What's a Moo to Do?

MooTools used to store custom events and attributes directly in custom properties of Elements called $events and $attributes. MooTools would then manually detach these properties from Elements upon unloading of the page.

Let's take a look at our previous example again, this time storing custom items in $attributes:

var element = $('myElement');
element.$attributes.effectInstance = new Fx.Tween(element, 'color');
element.$attributes.customProperty = 'someProperty';

element.$attributes.effectInstance; //the Fx.Tween instance
element.$attributes.customProperty; //'someProperty'

This example won't leak or produce the adverse effects of the first example, but man is it ugly! Also, sometimes the browser would hang on unload, trying to clear all these things out. This style of code didn't fit in with the rest of MooTools anyway, so we came up with a better solution.

When we access an element, we want to be able to store and retrieve custom properties for that element. But why attach these properties directly to the Element? If we used some form of external storage, we wouldn't need to worry about clearing values on page unload, things would be faster, and memory leaks would be a thing of the past.

A MooTools Worthy Solution

Element.Storage is brand new in MooTools 1.2. It is basically an external Hash that stores all the custom properties and events for every element you interact with.

Let's take another look at our previous example, this time using the new Element.Storage API:

var element = $('myElement');
element.store('effectInstance', new Fx.Tween(element, 'color'));
element.store('customProperty', 'someProperty');

element.retrieve('effectInstance'); //the Fx.Tween instance
element.retrieve('customProperty'); //'someProperty'

Note that events and actions are no longer attached directly to the Elements. Everything is stored in the external Hash, and managed by MooTools, so as a developer, you have nothing to worry about. Finally, an elegant and coherent API for attaching custom properties, functions, and objects to Elements.

How it Works (and What We're Using it For)

For those who are interested, I encourage you to take a look at the source. Basically, every element you interact with or traverse over when working with MooTools receives a unique ID. This id which is actually attached to the element then serves as it's key in the Element.Storage Hash.

We want MooTools to be fast as possible, so we do a whole lot of memoization. Basically, don't create something until it's needed the first time, but then cache it for immediate later use. Many of you who have already tested out the MooTools 1.2 betas have hopefully been having fun with the new Element shortcuts. All of these shortcuts use the new Storage API to make things as smooth and efficient as possible.

Advanced Examples

Element:retrieve actually accepts an optional second parameter which will act as the default value to store if another value doesn't previously exist. It will then retrieve the value as expected.

$('myElement').retrieve('defaultValue', 'Some Default Value'); //stores and returns 'Some Default Value' if the key doesn't previously exist

Also, many users have asked about namespacing the Element Storage. We have responded by telling them that it's already allows this since you can store Objects and Hashes. Consider the following example.

var element = $('myElement');
var data = element.retrieve('galleryData', {});
data.id = 16;
data.source = '/images/16.jpg';
data.title = 'Some Title';

//later
$('myElement').retrieve('galleryData'); //{ id: 16, source: '/images/16.jpg', title: 'Some Title' }
$('myElement').retrieve('galleryData').id; //16

The possibilities are endless. We'd love to know how everyone likes this new feature, as well as how you use it in your applications. In my next article ill talk a bit more about how MooTools uses the Element Storage internally for all the awesome new Element shortcuts like Element:highlight!

--ciao for now!

MooTools 1.2 Beta 2

2008-01-16T20:48:00Z

Its been almost 2 months since the first 1.2 beta. Bugs were fixed, features were improved, and here it comes: the second beta.

The first big feature we've been working on for 1.2 is Documentation.

1.2 Documentation is in fact almost 5 times more detailed than it was in version 1. Every class option has now its description, every method has a complete list of arguments along with description, type, and now every functionality comes with a code example -- sometimes more than one. If you want to see it for yourself, here is the temporary link for the 1.2 beta documentation.

A lot of the new 1.2 features have now been refined. An example that I'd like to share with you now is the Element Accessors feature. This is completely new for 1.2, aimed at making it easier working with elements and their attributes, properties or "special attributes". Continue reading for 1.2 code examples.

Let's see a basic example of an accessor. I want to work with the href attribute of an element:

$(element).set('href', 'http://mad4milk.net'); //setter
$(element).get('href'); //getter

Pretty easy, and pretty basic too. Now, Let's do something slightly more complex: I want to set the default morph options for an element:

$(element).set('morph', {duration: 100, transition: 'quart:out'});

After I set the morph "special attribute", every time I call the morph method on the element it will respect my defined options:

$(element).morph({height: 200, width: 200});

In addition, the set method now accepts any Object containing any of the settable properties: lets have an example:

$(element).set({
    href: 'http://mad4milk.net',
    text: 'mad4milk website',
    morph: {duration: 200, transition: 'quad:out'},
    events: {
        click: function(){
            document.location.href = this.href;
            return false;
        }
    }
});

Pretty cool huh? We can now basically set anything without chaining. While choosing this style over chaining could be a matter of personal taste, this technique is preferable when using multiple Element methods on a collection of Elements: you will loop through them only once. It will definitely make the code run faster.

Take note that every default element attribute can be managed with the set and get accessors. Other than that you can work with the inner text, the inner html, events and styles, and default effects options.

Last at but not least, we have a complete and public API for those accessors: if you want, say, change a number of things of an element with a single "special attribute" you can define it, and this "special attribute" can then be used like the examples above. For more information about accessors, and more examples, you can go see the new shiny documentation.

Other notable changes since 1.2 beta1 include a fully redesigned dimension system: its now much easier to get window or element dimensions, scrolling offsets, visible height or the full scroll height. Again, for more info, documentation.

If you're not familiar with the changes in 1.2 beta1, you can read more about it in the previous article.

I think this pretty much sums it up: have fun with the 1.2 beta 2 release.

P.S. This is very likely to be the last beta for 1.2.

MooTools 1.2 beta 1

2007-11-14T02:13:00Z

The first beta for MooTools 1.2 is finally here!

After months in the making, we can confidently say that MooTools 1.2 is now feature complete. However, there are still some bugs left to squash.

Head over to MooTools download page to start playing with it right away.

A Note About Compatibility

Some parts of MooTools 1.2 aren't immediately compatible with those found in MooTools 1.1. In the downloads page, you'll find a box that says: "include compatibility with previous version". Clicking that box will add the missing pieces and will make MooTools 1.2 play nice with code written for MooTools 1.1.

New stuff that we already covered:

The amazing Hash

Specs!

Effects Enhancements

Important stuff thats not yet covered in a blog article:

Full IFrames support with the Native IFrame Class.

Swiff: Flash content injection Class. Include Flash files, the easy way!

A Little Help, Please!

We are currently looking for bug reports and incompatibilities with previous plugins. If you want to help out, open a ticket in the Trac, and we will make sure that the problem is fixed for the final release.

Read more for a (not so) brief "what's new" list.

(P.S. This list is not exhaustive, it's just the stuff we could remember.)

Core

Every native method is now backed up by generics. Array.flatten(arguments)
New Function $lambda, that makes any value into a function. $lambda(1)(); or $lambda(function(){return 1;})();
New Function $arguments, returns the specified arguments index of the passed in function. var x = $arguments(1); x(1, 2);
Hash is now a Native, too. This is especially useful for Generics on objects. Defined in the core along with its .each method. {a:1,b:2}.each(function(value, key){console.log(value, key);});
The Array .each method is now defined in the core. [1,2,3].each(function(item){console.log(item);});
$type now returns the relative type for each defined Native (including window, document, and others). $type(window);
New Function $exec, which is now the standard function to evaluate code in the global scope. $exec('var x = 10;'); window.x;

Browser

Window and Document are now Natives. new Window(iframe.contentWindow)
New Browser object, that holds useful information on the browser being used. This informations used to be stored in the window object. Browser.Engine.webkit;
.head, .html and .window are now automatically created shortcuts on document instantiation.

Array

New Array method .flatten. Flattens a multidimensional array in a single, 2d array. Especially useful with arguments.
New Array method .link. Links the contents of an array with an hash based on names/functions. If the functions successfully runs on an array item, the item will be linked to that name.

Hash

Hash is now a Native. It sports almost the same methods as Array (.map, .every, .some, .each) plus others from the original Hash class.

Number

Now the Number Native also includes all the methods from the Math object, to allow for a more OOP experience. (10).sin(); (10).cos(); (10).pow(2);.

String

New String method .stripScripts, to strip and optionally evaluate script tags from a string.

Class

Class method .extend has been deprecated. Now every class accepts Extends and Implements properties. new Class({Extends: OtherClass, Implements: [Events, Options]})

Element

New TextNode Native, to allow easy creation and manipulation of text nodes. new TextNode('ciao').inject(document.body);
New IFrame Native, to allow for easy IFrames creation / augmentation. new IFrame('/index.html').inject(document.body);
.inject, .grab, .append methods now supports instantiated text nodes. element.grab(new TextNode('ciao'))
Element Storage, to store information linked to the DOM elements, but in the storage.
.store and .retrieve Element methods, to work with the Element Storage. element.store('property', 100); element.retrieve('property');
New Element .set, .get and .erase methods. Can be used as set/get/removeProperty shortcuts, and they also support defining new "getters" and "setters".
Element .match method, to match an element against a selector. element.match('div.someClass[name=stupid]');
New Element .wraps method, to wrap an element with another one.
New Element .replaces method, to replace an element with another one. This replaces the .replaceWith method.
Element .remove is now .dispose to resolve a naming conflict in internet explorer.
Element methods .getFirst, .getLast, .getPrevious, .getNext now support a selector to match the result to. inputElement.getParent('form');
Added methods .getAllNext, .getAllPrevious, .getParents. They also support matching against selectors, but they return elements collections.
Element method .setHTML deprecated in favor of .set('html', value). Also added the .get('html') counterpart.
Element method .setText deprecated in favor of .set('text', value). Also added the .get('text') counterpart.
Element method .getValue deprecated in favor of .get('value').
Element method .getTag deprecated in favor of .get('tag').
Element Custom Events creation API is changed, and its now 100% more intuitive.
Element Events section overhauled. When adding a new Listener with .addEvent the window event will be automatically instantiated, removing the cruft.
Element Styles section overhauled. Styles are more solid than ever, and you can even write your own style rules.

Selectors

Support for pseudo selectors (CSS3) has been added. You can now even define your own custom pseudo selectors.
The performance of the CSS selectors has been vastly improved.
Selectors now include support for matching a selector against an element.

Element/Document Dimensions

Dimensions is a new component to handle the size and position in space of elements and the document.
Methods are not attached to the window object anymore, but rather on document.
Method .getSize is now deprecated, as well as .getHeight and .getWidth. The official method to get the offset size of either the document or an element is now .getOffsetSize, which returns an object containing x and y keys.
Methods .getScrollHeight and .getScrollWidth are now deprecated. The official method to get the scroll size of either the document or an element is now .getScrollSize, returning an object containing x and y keys.
Methods .getScrollTop and .getScrollLeft are now deprecated. The official method to get the scroll of either the document or an element is now .getScroll, returning an object containing x and y keys.
New Method .getRelativePosition, gets the position relative to an element's offset parent. This returns the values that you would need to set via CSS to make it appear where it is on the page. Returns an object containing x and y keys.
Method .getPosition has been enhanced to work in every situation, without the need to manually include scrolled parent nodes. It also accepts an additional argument, relative, to automatically calculate the difference of positions of these two elements (this and relative). Returns an object containing x and y keys.
New Element method .position, to position an element with x and y coordinates. Note: this is relative to the element's offset parent, so its best used along with .getRelativePosition.
New Element method .positioned, to check if an element is positioned with absolute, relative or fixed style.
New Element method .getOffsetParent, to get the real offset parent of an element. This is to circumvent a bug with Internet Explorer not returning the real offsetParent.

Sortables

Support for sortable floated lists has been added.
Support for sorting between many lists has been added.
You can now add and remove items from sortable lists on the fly.
Positioning logic has been hugely improved and everything now works independent of CSS configurations.
Serializing is now much more robust and allows for the use of a custom callback.

Drag

Drag.Base is now simply named Drag.
The onSnap event has been deprecated.
The onStart event is now fired after the element has been dragged farther than the distance defined in the snap option.
The onCancel event is now fired correctly when the user begins a drag but lets up the mouse button before moving a distance greater than the distance defined by the snap option.
The onComplete event will no longer be fired if the user simple clicks on the draggable element without actually dragging.
The mousedown event is no longer prevented from propagating, so textareas are focusable and links are clickable inside of draggable elements without defined handles.

Drag.Move

When making an element draggable, the element will now stay in the same place on the page without manually setting its position after the call to makeDraggable.

Fx

Fx.Base is now simply named Fx.
The base class for all the Fx has been completely rewritten for optimization and a cleaner API.
Fx:pause and Fx:resume methods have been added.
The Fx constructors now accept durations as one of the three strings 'short', 'normal', and 'long' corresponding to values of 250, 500, and 1000 milliseconds.
A new 'link' option is provided to control what happens when calls are made to start while an effect is currently running
- link: 'cancel' - like wait:false from previous releases, will cancel the currently running effect to start the new one.
- link: 'ignore' - like wait:true from previous releases, will ignore any calls made to start while a transition is in progress.
- link: 'chain' - will chain all calls made to start so that they run one at a time in succession.

Fx.Tween

Fx.Style is now named Fx.Tween to more accurately reflect the behavior and to be consistent with the new Element:tween.
Element:tween has been added which will use the Element's internal Fx.Tween instance to transition any property in a single function call.
Element:highlight has been added which will fade an Element's background color from the specified value down to its current color. Default color is '#ff8'.
Element:fade has been added which will fade an Element to the specified state or opacity in a single function call. Possible values are:
- 'in', 'out', 'toggle' - fade the element in, out, or to the opposite of its current state (respectively).
- 'show', 'hide' - set the elements opacity immediately to 1 or 0 respectively, without a transition.
- numeric value between 0 and 1 - fade the element to the specified opacity.

Fx.Morph

Fx.Styles is now named Fx.Morph to more accurately reflect the behavior and to be consistent with the new Element:morph.
Element:morph has been added which will use the Element's internal Fx.Morph instance to transition any number of properties in a single function call.
CSS Selectors may now also be used as the argument to grab the transition styles from so properties can be stored in the Stylesheets.

Fx.Slide

Element:slide has been added which will use the Element's internal Fx.Slide instance to slide the element in and out in a single function call. Possible values are:
- 'in', 'out', 'toggle' - slide the element in, out, or to the opposite of its current state (respectively).
- 'show', 'hide' - set the slide state of the element immediately to in or out respectively, without a transition.

Fx.Transitions

When Fx.Transitions is included, the transition may now be passed to the Fx option as a colon separated string (type:how). Examples include:
- 'linear', 'sine:in', 'expo:out', 'quad:in', 'bounce:out', 'elastic:out', 'quint:in:out', etc.

Request

New Request class replaces XHR and Ajax as the MooTools XMLHttpRequest wrapper.
The Request constructor takes in only options, one of which is the URL, which used to be passed as the first argument.
Request:send now takes an options object, or a String or Element to be used as data as the only argument.
- Any options passed to send are used in place of the defaults that were provided (if they were provided) when creating the instance.
New Request methods for handling specific types of requests more easily.
- Request:get, Request:post - Strings passed to these functions will be used as the url, an object passed will be the data, and the method will be get and post respectively.
- GET, POST, PUT, and DELETE methods have also been added to make RPC with MooTools easier. All behave the same way as get and post.
Element:send no longer takes options as an argument, but rather, takes the url to send the request to. In order to use special options for the internal Request instance, you must use Element:set.

Request.HTML

Request.HTML adds some extra functionality for automatically processing HTML responses to the Request Class.
After a successful Request, the response's HTML is processed, scripts can be evaluated, and several arguments are passed to the onSuccess callback.
- tree - the original tree of the HTML snippet that was returned from the Request.
- elements - a flattened array of all the Elements that were returned from the Request.
- html - the raw HTML string that was returned from the Response.
Element:load has been added which allows you to update the HTML content of an element from the response of a Request called using the Element's internal Request.HTML instance.

Request.JSON

Request.JSON now replaces JSON.Remote and adds some extra functionality for automatically processing JSON responses to the Request Class.
After a successful Request, the response's JSON is processed and passed directly to the onSuccess callback.

A Final Note

Thanks for reading this far! We promise you won't be disappointed with 1.2.

MooTools Foundations: Natives and Elements

2007-10-31T08:00:00Z

We haven't had this blog for very long, and talking to many users recently, I became aware of the fact that many people just don't understand how powerful MooTools actually is. The purpose of this series of articles is to shed a little light on some of the functionality provided by MooTools that many users might be missing. I think maybe it's time we got everyone caught up to speed. First topic... Natives and Elements!

A quick note about this article

So I know I said my next article would be about the new Element shortcuts added in 1.2, but there are so many other things we should probably talk about first! All the code examples featured in this article are intended for MooTools 1.2. Although almost all of it either works with 1.x or has a 1.x equivalent, the purpose of this article is not to teach MooTools syntax, but rather to help users understand the concepts that drive the development of MooTools.

A MooTools Native, not just a person born in the country of MooTools...

First thing I'd like to talk about is the Native in MooTools. JavaScript provides us with many native Classes like Arrays, Functions, Numbers, Strings, etc. While they are all very powerful, we'd obviously like to make them much more flexible. We can call functions on our Arrays and Strings like:

[1,2,3].join('-');
//'1-2-3'
'this is my string'.split(' ');
//['this', 'is', 'my', 'string']

But there's absolutely no way native JavaScript could possibly provide us with all the functionality we want, right? Well not exactly. JavaScript lets us extend these native types by adding functions to their prototypes. Many of our JavaScript veterans are all too familiar with this topic. Here is an example:

//the following line will throw an error because there is no alert method for Strings
'this is my string'.alert();
//but by adding this small bit of code
String.prototype.alert = function(){ alert(this); };
//now the following line will work as intended
'this is my string'.alert();

MooTools has something called a Native which makes this process a bit more straightforward. When we make a new Native out of a JavaScript type, it gets all sorts of magical new properties. For example, with MooTools, here's how we can add methods to Strings:

String.implement('alert', function(){ alert(this); });

Right, it's the same amount of code, that's not impressive. But what about when I want to add more than one function?

String.implement({
    'method1': function(){ ... },
    'method2': function(){ ... },
    'method3': function(){ ... },
    'method4': function(){ ... },
    ...
});

Now all my strings will have all these functions right in their prototypes.

Is this available in a generic version?

Another big thing about implementing new methods into your Natives is that full generics support is automatically added. While this may not make much sense for a function like String:alert, it is extremely useful for things like using Array generics on HTMLCollections or Hash generics on Objects.

Hash.each({'one': 'item 1', 'two': 'item 2', 'three': 'item 3'}, function(){ ... });
Array.filter(document.getElementsByTagName('div'), function(){ ... });
Element.addClass(document.getElementById('myElement'), 'className');
Array.each(arguments, function(){ ... });

Generics are even provided for native functions...

Array.join([1,2,3], '-');
//'1-2-3'
String.split('this is my string', ' ');
//['this', 'is', 'my', 'string']

Declaring a new Native also lets us do the following (among other) things....

String.type('mystring'); //true
String.type([1,2,3]); //false
$type('myString'); //'string'
$type([1,2,3]); //'array'
$type(function(){}); //'function'

Since Functions, Strings, Arrays, and the rest of the Natives all know their type, we don't need to do any kind of convoluted test to determine it. The $type function can immediately access and return the type of any Native instance. This makes things clean and fast throughout the framework.

Awesome, now I know what a Native is... so what?

Well now we know how to extend the native JavaScript types... we're done, right? Mmm, not even close. Why don't we define some of our own Native types!? Awesome idea, let's do it. Let's add the following to the list of Native types [String, Function, Number, Array] at our disposal, all created by MooTools:

Hash - Object implementation which allows us to extend JavaScript Objects.
Event - Event wrapper which allows us to fix cross-browser quirks and enhance the information provided by native Events.
Element - A Wrapper which allows us to do what was once thought to be impossible, extend the functionality of native HTMLElements.
Elements - A powerful collection of MooTools extended Elements which combines all the functionality of an Array with all the functionality of an Element.
TextNode - A simple native used when injecting text into Elements.
IFrame - An awesome Element wrapper (the first of its kind) that allows you to use all the functionality of your parent document inside children documents (iframes).
Color - A useful native which allows you to mix, match, and modify colors.
Date - Extends the native Date type so you can add functionality and test for type on variables.

I already talked a bit about the newest Native, the Hash in a previous article. In a future article we will talk about the awesomazing IFrame (it really is so cool), but for now, there are quite a few things I'd like to tell you about Element(s).

Wait, you mean Elements are more than just little boxes on the periodic table?

Alright, by now hopefully you know what an Element is. Whenever you use the $ function in MooTools to select an element by id, or extend an existing element, it becomes a MooTools Element. This means you can do all sorts of stuff with it, no matter what browser you're in. Here's a few simple examples...

var element = $('myElement'); //select the element with id 'myElement'
//add the className 'active' to myElement
element.addClass('active');
//get myElement's title
element.getProperty('title');
//get myElement's color, width, and height properties
element.getStyles('color', 'width', 'height');
//set the border style of myElement
element.setStyle('border', '1px solid #f00');
//add a click event to myElement
element.addEvent('click', myClickFunction);
//...and do all this stuff
element.getNext('div').addClass('active').getParent().adopt(new Element('input', {type:'text'}));

Elements actually have so much functionality, there's no way I could show you it all (as this article is already getting pretty long). Now on to the part that many of you may not know about. The Elements Class in MooTools is a special type of Array that contains MooTools Elements. An Element gets returned from any call to $, and Elements get returned from any call to $$. Don't let the 's' at the end confuse you, here is a breakdown.

$: takes an id or an element, returns Element - a single MooTools Element.
$$: takes one or many CSS Selectors or elements, returns Elements - many MooTools Elements in an Array.

Here's the amazing part... Anything you can do to an Element, you can do to a collection of Elements. If you call an Element method on Elements that returns something, (for instance, an an accessor like getStyle or getCoordinates), you will receive back an Array. This resulting Array will be the same as if you manually iterated through all the Elements by hand, calling the function on each one, and pushing the result to an Array... it's just a lot less code. :P

//add the className 'active' to myElement
$('myElement').addClass('active');
//add the className 'active' to all the li's inside a ul that are children of a div
$$('div > ul li').addClass('active');
//add the className 'odd' to every other row in a table of data
$$('table tr:odd').addClass('odd');

//make myElement red
$('myElement').setStyle('color', '#f00');
//make all the divs with className 'info' red
$$('div.info').setStyle('color', '#f00');

//get the color of myElement
$('myElement').getStyle('color'); //returns '#f00'
//get the colors of all the divs with the className 'account'
$$('div.account').getStyle('color'); //returns ['#ff0000', '#00ff00', '#0000ff'], etc.

These are just very simple examples to demonstrate this concept, but the implementation is flexible and powerful. Similar functionality is provided by other frameworks, but in slightly different ways. In Prototype there is the Enumerable function invoke which will execute a function on every element in an Array. This is convenient, but a bit more code, and a bit less straightforward. In jQuery you always act on collections. While this is convenient most of the time, it may not be the most efficient way to manipulate single elements. With MooTools, whether you are dealing with a single Element or a collection of Elements, all the Element methods work. Methods are easy to use, easy to expand, consistent, and less ambiguous.

As the first article in this series, I hope this sheds a little light on some of the Core building blocks of MooTools. More articles will follow in this series describing other components of the Framework in better detail.

--ciao for now!

MooTools + AIR = Love

2007-10-26T19:14:00Z

Today I found a nice article on coderseye.com:

I spent a half hour tinkering around in Aptana, downloading MooTools 1.1, and setting up a few tests. The result is extremely pleasing. Not only is MooTools way better and easier to use than I remember, but it works out of the box with AIR.

That’s Very nice to know!

I personally haven’t yet tried MooTools in AIR extensively (i only did a few basic tests) but I’m definitely looking forward to creating something in the very near future. Maybe a downloader app? We’ll see!

What's New in 1.2: The Best Fx, Now Even Better

2007-10-23T19:32:00Z

MooTools has always been known for having some of the most fluid and impressive effects around. In 1.2 we’ve introduced some exciting new enhancements that make them even more efficient, powerful, flexible, and easy to use. Here are the changes made to the Fx Classes to take note of...

What's in a name?

One of the most obvious changes to the MooTools Fx Library is a change in the naming of Fx.Style and Fx.Styles. Though you can still use these class names in 1.2, they will be deprecated in future versions, so please start using the classes through their new names, Fx.Tween and Fx.Morph respectively. The reason for the name change is two-fold. First, we feel these names more explicitly describe the functionality of the classes, and second, the classes correspond to some awesome new Element shortcuts, which I will talk much more about in my next article! (Expect a nice demo of all the things talked about in this article to come along with the article about Element enhancements)

If I told you Fx.Morph was just a new name for the same old Fx.Styles, I'd be lying through my teeth. Thanks to some flexible CSS parsing code, you can now transition not only to an object full of rules, but also to any CSS rule defined in your stylesheets. Ever wanted to make an element look like another one, or add the styles of an error class to an element smoothly? Well now you can do it in style! Personally, I'm really excited about the flexibility of the new Fx.Morph class, and I've started using it regularly already. Here are some of the cool things that can be done...

var myMorph = new Fx.Morph('myElement', { 'duration': 1000 });
//transition myElement to have a text color of red, a width of 200px, and a line-height of 20px
myMorph.start({ 'color': '#c03', 'width': 200, 'line-height': 20 });
//transition myElement to the properties defined in the .warning rule in my stylesheet
myMorph.start('.warning');
//transition myElement to look the same as a paragraph that has the information class inside the element whose id is content
myMorph.start('#content p.information');

What do you mean, 'any property'?!

The Fx.Tween and Fx.Morph classes (along with all Element style methods) allow you to transition literally any style property of an element. We don't need special classes for colors, dimensions, borders, and clipping, no sir! If you can style it with CSS, you can transition it with the new MooTools Fx! If the transition is something that isn't calculable like a background image or border-style, the property will be set immediately at the start of the transition.

//transition the background position of my element to 400px 20px
myMorph.start({ 'background-position': '400px 20px' });
//the following is another way to achieve the same effect
myMorph.start({ 'background-position': '400 20' });
//here, we transition the CSS clip for this element from the start to the end value
myMorph.start({ 'clip': ['0px 500px 500px 0px', [130, 410, 220, 130]] });
//transition the border-width's of this element
myMorph.start({ 'border-width': '4px 10px 16px' });
//morph many different properties of this element at once... oh, the possibilities!
myMorph.start({ 'border': '5px solid #f03', 'border-bottom-color': '#ccc', 'background-color': '#fee', 'color': '#f03', 'width': 200, 'height': '300px', margin:[10, 20], 'opacity': 0.6 });

A few notes about the above examples:

The syntax is very lenient. You don't need to provide units, you can use hex colors, or rgb / rgba colors, and properties that take multiple values, like clip for instance, accept a space separated string, or an array of values.
The starting parameter is optional in most cases. If two parameters are passed in an array to any property, the first will be the start value and the second the end value. Otherwise, the transition will start from the element's current state.
If you dont want to use objects everywhere to define your transitions, simply save the properties to your CSS, and create a morph as complicated as you want just by calling start with that CSS rule's selector!
Lastly, as was mentioned above, any property that cannot be calculated will be set immediately upon start of a transition.

How cool is this stuff?! Please, experiment as much as you can and show us all the cool stuff you do.

The new awesomazing link option!

The next enhancement to Fx has to do with the 'wait' option. What happens if I call start on an effect while the effect is running? Just recently Valerio and I were talking about one of the reasons MooTools was first created. He had the idea that by reusing a single Fx instance whenever he wanted to perform a transition on an element, he could keep track of the current state of the effect. This would allow him to prevent the annoying flickering that plagued many other JavaScript Fx libraries. Using the wait option in MooTools 1.x, you could tell the effect to either ignore concurrent calls to start (wait: true, by default) or stop wherever it was, and start the next effect. (wait: false, very common for things like mouseover / mouseout transitions).

Well, in 1.2 wait is no more, because we found a slightly more powerful solution. We now have the 'link' option, which describes how two concurring effects should be linked together, if at all. There are three possible values for link, namely: 'ignore', 'cancel', and 'chain'. Here is how each behaves.

link: 'ignore' - This configuration is synonymous with 'wait: true' from 1.x, and is the default behavior. Any calls made to start while the effect is running will be ignored.
link: 'cancel' - This configuration is synonymous with 'wait: false' from 1.x. Any calls made to start while the effect is running will take precedence over the currently running transition. The new transition will start immediately, canceling the one that is currently running.
link: 'chain' - This configuration is new for MooTools 1.2. Any calls made to start while the effect is running will be chained up, and will take place as soon as the current effect has finished, one after another.

Here are some examples of the link option in action...

var myTween = new Fx.Tween('myElement', 'background-color', { 'link': 'chain' });
//fade myElement to red, then to white, then to blue
myTween.start('#c03').start('#fff').start('#369');

var myMorph = new Fx.Morph('myElement', { 'link': 'cancel' });
//transition myElement to red 16px sized text
myMorph.start({ 'color': '#c03', 'font-size': 16 });
//a few ms later... stop right there! make that blue 10px text with a height of 100px
myMorph.start({ 'color': '#369', 'font-size': 10,  'height': 100  });

Core changes and enhancements

There are a few other minor changes to take note of. First, two new public methods were added to the API as per request, namely Fx:pause, and Fx:resume. They work exactly as you'd expect. Another minor change is that duration now also accepts one of the strings 'short', 'long', and 'normal', which is the default.

var myTween = new Fx.Tween('myElement', 'background-color', { 'duration': 'long' });
//transition myElement's background color from white to a nice blue
myTween.start('#fff', '#369');
//a few ms later... hang on a sec in your whitish-bluish state, I have something to take care of!
myTween.pause();
//some time later... alright, I'm ready to finish up.
myTween.resume();

Most of the other changes won't affect users too much, but there was quite a bit of restructuring done to the Fx framework. The core is now more consistent, organized, and robust. Plugin developers should be aware of the new structure for creating Fx extensions.

That pretty much sums up all the new stuff in Fx. All the rest of the goodness you've come to know and love about MooTools Fx is still there, cleaner and more efficient than ever! We encourage everyone to dive into the source and discover just how much you can do with the most compact, smooth, and robust Fx Framework on the Internet. Let us know what you think. ;)

What's New in 1.2: Behaviour Driven Development

2007-10-20T09:18:00Z

You know we've been telling you that MooTools is reliable, but how can you can be sure that it will work for your project without just taking our word for it?

Check the Spec folder out from the repository and its self-contained testing suite will prove it. Show your boss, show your coworkers, and let them know that MooTools is professional grade.

Verifiably Rock-Solid

What makes this possible? We've added our own special blend of JSSpec to the MooTools source. It goes through critical components of MooTools to make sure that they work as expected.

For this release, we'll be supporting specs for Core, Class, Natives, and Element.js. While not all of the Elements scripts or the other folders will make it into 1.2, we hope to release their specs in later releases.

What's A Spec?

The spec is short for specification. Specifications are meant to be human-readable descriptions of code which can be verified programmatically. They also serve as code samples and documentation all in a neat little package. Exciting, right?

You could call them tests, but they're a little different.

Specs vs. Tests

Switching from tests to specs is a semantic shift between TDD (Test Driven Development) and BDD (Behavioral Driven Development).

The examples describe the behavior, while tests make assertions of the state of a system. Describing the behavior is the most intuitive way to verify that a system will behave the same way every time.

Roll Your Own

As an added bonus, you can use the spec runner to create your own tests. The syntax is pretty simple.

describe('Game', {

  'before each': function(){
    Game.start('Plum', 'library', 'wrench');
  },

  'should lose if bad guess': function(){
    var result = Game.guess('Plum', 'study', 'rope');
    value_of(Game.hasWon()).should_be_false();
  },

  'should win if good guess': function(){
    Game.guess('Plum', 'library', 'wrench');
    value_of(Game.hasWon()).should_be_true();
  }

});

In this example, the first line denotes what we'll be testing.

describe('Game', {

The first spec, 'before each', will be run before each example.

'before each': function(){
    Game.start('Plum', 'library', 'wrench');
},

This means that every example, the new method of the Game object will be called, passing in its predefined parameters.

This is followed by each spec you want to test.

'<human readable description>': function(){
    <setup code goes here>
    value_of(<what you want to test to verify the spec>).should_be_true();
}

Of course, should_be_true(); is just one example of what you can do. For more examples, you can read the specs we've done for the framework, or check out the main JSSpec documentation.

Why Bother?

So what's the point of making specs for all your MooTools goodness?

Without specs, you might not know about a JavaScript problem until you get a call from an angry customer, assuming you're lucky and get enough traffic to have the issue reported. Otherwise, errors could fester on your site unbeknownst to you for weeks, like a big "Kick Me" sign for your visitors to laugh at.

With specs, you can know before you update your site whether or not it will crash and burn. It might not make you richer or more popular, but at least you won't have to worry about it.

What's New in 1.2: The Hash

2007-10-08T02:22:00Z

In recent development of MooTools, we've incorporated into the core a plugin that was once pushed under the table and neglected. The Hash is a powerful new way to extend objects just like you've always wanted...

Alright, what the heck is all this Hash business?

The current 1.2 development version of MooTools saw a promotion of the Hash Class up from a plugin to a Native type. A Hash is basically a wrapper for native JavaScript Objects. The reason it was created was because as we all know, the Object prototype is off limits! (for a brief explanation... see rule #2). So what can i do with this crazy new thing?

var hash = new Hash({ 'a': 'one', 'b': 'two', 'c': 'three', 'd': 'four'});
hash.get('a'); //"one"
hash.set('e', 'five'); //hash.e is now 'five'
hash.set('c', 'new value'); //hash.c is now 'new value'
hash.f = 'another value here'; //this is perfectly acceptable also, get / set are just shortcuts to filter out prototypes
hash.has('b') //true
hash.each(function(value, key){ alert(key + ':' + value); }); //alerts a:one, b:two, etc.
hash.get('each'); //null

Now i know what you're thinking, "Alright, so what... i could do all that stuff before with Objects, even the each with a simple for in loop." Well, no. The Hash Native also supports just about every Array method including 'map', 'every', 'some', and 'filter', as well as a few other really handy shortcuts. We now use Hash as the all-purpose data type throughout the MooTools Framework. Once you start using it, you'll know why. ;) (Also a note to anyone who has ever used Abstract in MooTools... The Hash is a replacement for Abstract and is much, much more powerful. Anywhere you used to have Abstract in your 1.1+ MooTools code, just replace with Hash and you should be all good)

Generics are so cool...

Just like all other MooTools Natives, Hash has full generics support. This means that any function you can call on a hash, you can also call by passing the hash as the first argument to the genericized function. Also, any generic you can use on a hash can also be used on a native JavaScript Object.

var obj = { 'a': 'one', 'b': 'two', 'c': 'three', 'd': 'four'};
Hash.each(obj, function(value, key){ alert(key + ':' + value); }); //alerts a:one, b:two, etc.
Hash.filter(obj, function(value, key){ return key.test(/a|c/); }); //returns a hash containing { 'a': 'one', 'c': 'three' }
Hash.getKeys(obj); //returns ['a', 'b', 'c', 'd']

What other stuff can i do?

Well perhaps the most powerful aspect of Hashes is as i mentioned before, all the Array functions you've come to know and love can now be used on Hashes. Check out the source for many more implemented methods. Hash really is a awesome tool, so wonderful in fact that it's been included in the Core of the framework. In my next article, I'll talk about some exciting changes to Fx in MooTools, as well as some awesome new Element shortcuts.

--ciao for now!

Help Us Help You

2007-06-18T14:29:00Z

While we love to help everyone who comes to us for support, sometimes there’s a breakdown in communication.

To clear up some of these issues, I’ve written this article about how to get the friendliest response possible from the community.

We’re Not Mean

The MooTools community is one of the friendliest JavaScript communities you’ll ever find. We comb the forums all day, looking for people to help. Questions are answered promptly, and tons of documentation has been written to help people learn the framework.

I’m even trying to start an initiative where everyone uses :) a lot to show people that we’re friendly and helpful. :)

How to Ask Better Questions

There are a few things you can do to help us help you.

Read the Documentation First

We spend a lot of time writing documentation to help out all the people who find MooTools. Writing documentation is a complicated and thought intensive process, so it makes us sad when people ask questions without looking at the documentation first.

We might disguise our sadness with anger and bitter sarcasm, but we’re really crying on the inside. :)

The JavaScript Code Tag

There is a button on the forums to use when pasting JavaScript code which makes things a lot more readable. Please use it. The same goes for the HTML code button. :)

Links Are Best

I don’t know about you, but looking through every line of your HTML, CSS, and JS code to find out why your tooltips aren’t fading in properly isn’t my idea of a fun time. The best way to get quick help is to post a link, so that I don’t have to download mootools.js, make a local file on my machine, edit the file so it points to my local version of the moo.js, and then open up the file in Firefox. It’s just a lot of work and I’m a lazy person. And even after all that, I’ll still have to dig around until I find your offending code.

The best combination of information is a brief but detailed problem description, a small excerpt of code where you’re having your troubles, and a link to the development page.

Be Descriptive

It’s much easier for us to help you figure out your problem when you tell us what you’re expecting to happen and what actually happens. “I’m trying to use Fx.Slide to make my content div slide in and out, but when I trigger the effect, it gives me a ‘Method not found’ error,” is infinitely more helpful than, “I’m trying to do a slide effect, but it doesn’t work.”

Show Us Some Sample Code

Write a man some code, and he has fancy effects for a project. Teach a man to code, and he has fancy effects for the rest of his life.

The main purpose of the forum is to assist people in learning MooTools. As a rule of thumb, we try not to tell people how to do things directly, opting instead to assist people in finding their own answers.

We’ll give hints, we’ll tell you where a bug is, we’ll link you to the helpful bit of documentation you might not have known to search for, but you’ll have to meet us halfway.

We’d like to see evidence that you’ve already made an attempt to code something and that you’ve read the documentation. If you don’t provide us with sample code or a link, your thread might be closed, depending on your question. Code copied and pasted from the demos does not count as sample code. :)

We understand that sometimes, you’re not able to post code based on restrictions placed upon you by your client or employer. If this is the case, try to give us as detailed an account as possible.

We Won’t Code For You (Unless You Pay Us To)

A major issue for us is people who come to the forum who don’t want to learn MooTools, but just want to get some fancy effects up on their sites as easiest as possible. In this case, the easiest way possible is to get someone else to do it for them. We’re not going to code things for you. If that makes us elitists, so be it. :)

Many of the people who have had threads closed fall into this category.

JavaScript is a skill, and we won’t code custom sites for people just because they ask us to on the forums. We’re already giving you a framework that makes a lot of awesome things really easy, written up tons of documentation about every feature, and given it all to you for free. Please don’t expect us to do more than that. :)

If You Don’t Want To Learn MooTools…

If you don’t know JavaScript or MooTools, have no intention of learning, and you need fancy effects on your website, you can post in the Get Help section about hiring someone to do it for you. I’m sure there are plenty of starving Moo artisans who would be happy to give you a hand. :)

In Conclusion

Selectors on fire: a tale of pseudoselectors

2007-06-11T20:02:00Z

During the last few days, we've added some nifty CSS3 selectors to the trunk. Continue reading to know what this is all about, or try SlickSpeed now!

UPDATE: SlickSpeed can now be downloaded from googlecode.

The Beginning of a New Era

Ok, so the last couple of days were very productive ones.

I started adding the CSS3 adjacency selectors, like ~, > and +. It was quite an easy task which didn't require much logic changing, and I was able to implement and get it running across all browsers in (a little more than) a few hours.

This allows us to select direct children, following siblings and the direct following sibling. So let's add these to the supported selectors:

//all spans immediately preceded by a div
$$('div + span');

//all the following sibling of divs, that also happens to be spans
$$('div ~ span');

//all the direct children of all divs with tag == span
$$('div > span');

And the easy part was done. Now the hard part was left, which is what this article is all about: the famous pseudo selectors.

Zebra Tables For the Winners

Pseudo selectors are little known in the world of CSS because of the lack of browser support. From what I understand, Opera is the only browser supporting pseudo selectors at all, and even its support is limited.

So I started by implement :nth-child, rigorously following the W3C specs, so we could compete in the zebra table showdown.

The tricky part was mostly 2n+1, because I had to understand what the heck it was all about. Lucky for me, I had all the supporting devs in the channel who are apparently better with specs (and math) than myself.

Hours later, I had the first working version of nth-child, along with the very similar :odd, :even, :last-child and :first-child, that luckily shared the same logic.

So we can also add these to the supported css selectors:

////every odd (1st 3rd 5th 7th ... 13th) li inside an ul
$$('ul li:nth-child(2n+1)'); //same as
$$('ul li:nth-child(odd)'); //same as
$$('ul li:odd');

//every even (2nd 4th 6th ... 12th ...) li inside an ul, starting from the second
$$('ul li:nth-child(2n)'); //same as
$$('ul li:nth-child(even)'); //same as
$$('ul li:even');

//every li which is the second child of an ul.
$$('ul li:nth-child(2)');

Obviously, other numbers are also supported in this format: "int"n+"int" or "int" or "int"n or "int"n-"int". Pretty sleek if you ask me.

Now that the big part of the work was done, I needed to get the rest of the CSS3 selectors in there.

Getting the Rest of Them

Ok, this part was quite easy. Since Harald already coded a bunch of them in his branch a long time ago, it was just a matter of cleaning them up and testing across browsers.

And so I added :disabled, :enabled, :contains, :checked and :empty

The one that gave me nightmares was contains: it kept returning more results than the expected ones. I admit I also checked other libraries like Prototype or jQuery. Prototype doesn't support :contains, and jQuery returned the same wrong results as mine.

Something must have been wrong, very wrong.

With the help of the funny boys in the IRC channel, we defeated the enemy once again. Without going into all the glorious details, an element contains some text only if it contains a textnode with that text; not if a child element contains the text. I tell you, this stuff challenges a man's patience.

Ok, so lets add these too to the list of the supported selectors:

//every div that contains a direct textnode with the text "ROSALIND"
$$('div:contains(ROSALIND)');

//every radio input that is checked.
$$('input[type=radio]:checked'); //same concept for disabled and enabled.

And I was done!! Or so I thought...

Pseudos on Fire

Thats when I started noticing a bit of redundancy in the code. My inner perfectionism wouldn't let me go on knowing of this redundancy so I had to straighten things out.

I noticed redundancies especially in places like :disabled and :checked. Thats when I had this idea: lets make pseudo selectors default to attributes, so stuff like :checked and :disabled didn't have to be explicitly coded.

Now, any pseudo selector defaults to an attribute, if no pseudo selector is predefined. Lets make an example:

//every link with a title attribute
$$('a:title'); //the pseudo is not predefined, so it defaults to:
$$('a[title]');

//same concept here, but with a value too:
$$('a:title(mootools)'); //the pseudo is not predefined, so it defaults to:
$$('a[title=mootools]');

This obviously gives us some nice freedom of movement inside the huge reign of the DOM.

At this point, you're probably dying to know what in the world that header image is. NOT YET! Keep reading dude.

Getting Control of the Pseudos

That's the point when most of you might think, "Ok, we have enough pseudoselectors! We don't need any more!" But, wouldn't it be nice if we gave users the ability to create their own, matching their own custom rules?

Time for a complete refactor on how the pseudoselectors are parsed!

Five hours later, all the pseudoselectors were written as custom pseudoselectors, all lined up in nice form inside a separate, optional file.

Now, everyone can write custom pseudoselectors for themselves!

Lets make a quick, stupid example:

Selectors.Pseudo.blue = {
    xpath: function(){
        return '[@class=blue]';
    },
    filter: function(el){
        return (el.className == 'blue');
    }
};

//usage
$$('div:blue'); //all the divs with className == blue!

So, as you can see its pretty straightforward. We write a rule for xpath browsers, and a filter for non-xpath browsers and voila', our new, shiny, breathing, custom pseudoselector is born.

There is obviously much more you can do with custom pseudoselectors, but lets keep it simple for today.

OK, can you tell me about the header now?

The header is a screenshot of a selector testing suite we're going to release as opensource. With all these many new selectors, a test suite was the easiest way to test the selectors in every browser, whether or not the browser included xpath. The test suite is written in simple PHP and plain JavaScript. No framework is used in the suite JavaScript file, as the point of it is to test frameworks against each other. This avoids favoritism. Also, each framework runs in its own iframe, so no prototyping conflicts can happen.

The html template for all frameworks is the same Andrew Dupont used in his DOM Selector speed tests. His test was flawed though, as every framework was just included in the same page. This created prototypes conflict, so speed results were unreliable.

In the demo I tried to include the latest development version of the frameworks where possible. Currently in the demo: mootools, prototype, jquery, ext, cssQuery and dojo.

So welcome to the battle of the frameworks, and may the best win. Meet SlickSpeed.

~~P.S. We're gonna release SlickSpeed next week, as we need to add a few features.~~ SlickSpeed can now be downloaded from googlecode.

And thats all.