Native Code

The Native group of scripts are basic extensions to the default objects in javascript (currently, Mootools has Native code for Array, Element, Event, Function, and String). These files alter the way these elements and every instance of them work. Because it's possible to create arrays or strings before this code is executed (or otherwise outside this scope), they typically have a means by which to apply these functions to existing strings. Here's a run down of the functions available for these objects; most of these can be executed by clicking "execute this code".

Here is the documentation for Array.js.

Array.each() iterates through the array executing the specified function for each item in the array. The anonymous function can be passed two arguments (optional) - the item and the index.

.each() is really just a pointer to .forEach, which Mootools implements for browsers that don't already support it. Here's the documentation at Mozilla on .forEach.

["one", "two", "three"].each(function(number){
  alert(number);
});

["one", "two", "three"].each(function(number, index){
  /*let's just alert the first one*/
  if(index == 0) alert(number); 
});

.each() takes an optional second option for binding. This is really useful when your function is in an object:

var exampleObj = {
  setNumbers: function(numbers){
    this.numbers = numbers;
  },
  calcNumbers: function(){
    this.numbers.each(function(number, index){
      this.numbers[index] = number*2
    }, this); /*here is the interesting bit*/
  }
};
exampleObj.setNumbers([1,2,3]);
exampleObj.calcNumbers();
alert(exampleObj.numbers); //alerts 2,4,6

The above example is somewhat convoluted but it demonstrates where and why you use binding this way. If you called this.timesTwo inside the .each(function... then "this" would refer to the .each(function, not your exampleObj, where timesTwo is defined. So with .each(), you call a function and you can optionally bind an object to the "this" inside that function.

See Function:Bind for more details on binding.

Mootools implements .filter() for browsers that don't already support it. Here's the documentation at Mozilla on .filter.

Array.filter calls a provided callback function once for each element in an array, and constructs a new array of all the values for which callback returns a value that evaluates true. The callback is invoked only for indexes of the array which have assigned values; it is not invoked for indexes which have been deleted or which have never been assigned values. Array elements which do not pass the callback test are simply skipped, and are not included in the new array.

Callback is invoked with three arguments: the value of the element, the index of the element, and the Array object being traversed.

function isBigEnough(element, index, array) {
  return (element >= 10);
}
[12, 5, 8, 130, 44].filter(isBigEnough);
//returns [12, 130, 44]

Array.filter can take a second argument for binding:

var exampleObj = {
  setNumbers: function(numbers){
    this.numbers = numbers;
  },
  filterValue: 10,
  filterBigEnough: function(){
    this.numbers = this.numbers.filter(this.isBigEnough, this);
    /*	the second arg filter() binds this (exampleObj)	*/
  },
  isBigEnough: function(element, index, array) {
    return (element >= this.filterValue); 
    /*	this has to == exampleObj	*/
  }
};
exampleObj.setNumbers([1,10,100]);
exampleObj.filterBigEnough();
console.log(exampleObj.numbers);
/*	logs [10,100]	*/

Applies a function to each item in an array and returns an array with the results of each application.

Mootools implements .map for browsers that don't already support it. Here's the documentation at Mozilla on .map.

[1,2,3].map(function(num){
  return num*2;
}); //returns [2,4,6];

Just like .each, .map takes an optional binding element as its second input. Also, the function you call in .map can take two inputs; the object and its index.

var exampleObj = {
  setNumbers: function(numbers){
    this.numbers = numbers;
  },
  multiplier: 2,
  calcNumbers: function(){
    this.numbers = this.numbers.map(function(number){
      return number*this.multiplier; 
      /* note here that we return the result of the calculation
      also note that we refer to "this", so we need to bind this
      function	*/
    }, this); /*here is the interesting bit*/
    /*.map will execute this on each item in the 
     array, and then return the entire result set.*/
  }
};
exampleObj.setNumbers([1,2,3]);
exampleObj.calcNumbers();
alert(exampleObj.numbers); //alerts 2,4,6

.every() tests all the elements in an array to see if they pass; returns true if they all do, otherwise false.

Mootools implements .every for browsers that don't already support it. Here's the documentation at Mozilla on .every.

[1,2,3].every(function(num){
  return $type(num) == "number";
}); //returns true because 1, 2, and 3 are all numbers

[1,2,'foo'].every(function(num){
  return $type(num) == "number";
}); //returns false because 'foo' is not a number

.some() tests all the elements in an array to see if they pass; returns true if any do, otherwise false.

Mootools implements .some for browsers that don't already support it. Here's the documentation at Mozilla on .some.

[1,2,'foo'].some(function(num){
  return $type(num) == "number";
}); //returns true because 1 and 2 are numbers, even though 'foo' isn't

.indexOf() finds the first index of an object within an array; returns -1 if no match is found.

Mootools implements .indexOf for browsers that don't already support it. Here's the documentation at Mozilla on .indexOf.

['apple','lemon','banana'].indexOf('apple');
//index is 0

Returns -1 if the item is not found.

.indexOf can take a second argument as an offset of where to look:

['apple','lemon','banana'].indexOf('apple',1);
//index is -1, because apple is not found in indexes >= 1

Copies the array and returns it.

var letters = ["a","b","c"];
var copy = ["a","b","c"].copy();
alert(copy);

["1","2","3"].remove("2") // ["1","3"];

This is a change from Mootools 1.0 - this functionality used to be called Array.test(), but is now Array.contains(). Mootools 1.1 has the old name (.test) mapped to the new one, but it is deprecated, and Mootools 1.2 and beyond will not have this backwards compatibility (you can always add it yourself).

["a","b","c"].contains("a"); // true

["a","b","c"].contains("d"); // false

var Animals = ['Cat', 'Dog', 'Koala'];
Animals.extend(['Lizard']); //Animals is now: ['Cat', 'Dog', 'Koala', 'Lizard'];

Note that extend does not exclude duplicates:

['Cat','Dog'].extend(['Dog','Koala']); //returns ['Cat','Dog','Dog','Koala']

var Animals = ['Cat', 'Dog', 'Bird', 'Lizard'];
var Speech = ['Meow', 'Bark', 'Chirp', 'Mute'];
var Speeches = Animals.associate(speech); 
//Speeches['Meow'] is now Cat.
//Speeches['Bark'] is now Dog.
//...

This merges an array in another array, without duplicates (case- and type-sensitive):

['Cat','Dog'].merge(['Dog','Koala']); //returns ['Cat','Dog','Koala']

This works like Array.merge() but you pass it a value to add to the array if it's not already present, not an array to merge:

['Cat','Dog'].include('Dog'); //returns ['Cat','Dog']

['Cat','Dog'].include('Coala'); //returns ['Cat','Dog','Coala']

Returns a random item from the array:

['Cat', 'Dog', 'Bird', 'Lizard'].getRandom()

['Cat', 'Dog', 'Bird', 'Lizard'].getLast() //'Lizard'

$A() applies these functions to any iterable object. Example:

function myFunction(){
  $A(arguments).each(function(argument){
    alert(argument);
  });
};
//the above will alert all the arguments passed to the function myFunction.

If you want to iterate through an iterable object (such as the arguments passed to a function) without applying all the array properties to it (which is slightly slower), you can use $each() to do this.

$each(["one", "two", "three"],function(number){
  alert(number);
}); //alert one, two, three

$each also lets you iterate over objects:

$each({apple:'red',lemon:'yellow',lime:'green'}, function(value, key){
	console.log(key+"s are "+value);
});
//logs apples are red, lemons are yellow, limes are green

Like Array.each, it can take a third argument for binding.

Here is the documentation page for String.js.

Tests a string against a regular expression; optional second parameter for Regex options. Accepts regular expressions in both string and regexp mode.

"I like cookies".test("cookie"); // returns true

/*ignore case*/
"I like cookies".test("COOKIE", "i")

/*returns false*/
"I like cookies".test("cake");

/*here's an example of how you would probably actually use it*/
if("I like cookies".test("cake")) alert ('you like cake');
else alert("you don't like cake (what's wrong with you?)");

Checks if the passed in string is contained in the string. Also accepts an optional second parameter, to check if the string is contained in a list of separated values. The big difference between this and String.test is that String.contains does not use regular expressions. The second argument also is notable, as it basically performs a String.split on the string and then searches the results:

'a b c'.contains('c', ' '); //true

'a bc'.contains('bc'); //true

'a bc'.contains('b', ' '); //false

Returns string with escaped regular expression characters:

'animals.sheeps[1]'.escapeRegExp(); //'animals\.sheeps\[1\]'

Parses the string to an integer.

"10".toInt(); // value is 10

"10px".toInt(); // value is 10

"-10".toInt(); // value is -10

"px10".toInt(); // NaN

"10.1".toInt(); // returns 10

Parses a string to a float (a number with decimal values).

"10".toFloat(); // value is 10

"10.01".toFloat(); // value is 10.01

"-10.01".toFloat(); // value is -10.01

Converts a hyphenated string into a mixed case string; mostly used by Mootools for setting and getting css properties.

"I-like-cookies".camelCase(); //"ILikeCookies"

Converts a CamelCase string to a hyphenated one; mostly used by Mootools for setting and getting css properties.

"ILikeCookies".hyphenate(); //"I-like-cookies"

"i like cookies".capitalize(); //"I Like Cookies"

"    i like cookies     ".trim() //"i like cookies"

Trims (String.trim) a string AND removes all the double spaces in a string.

" i      like     cookies      \n\n".clean() //"i like cookies"

"rgb(17,34,51)".rgbToHex(); //"#112233"

"rgba(17,34,51,0)".rgbToHex(); //"transparent"

"rgb(17,34,51)".rgbToHex(true); //[11,22,33]

"#112233".hexToRgb(); //"rgb(17,34,51)"

"#112233".hexToRgb(true); //[17,34,51]

Takes an array with three color values and converts them to an RGB value; mostly used by Mootools to set css color values.

[99,100,101].rgbToHex() //returns "#636465"

Takes an array with three hexidecimal color values and converts them to an rgb value; mostly used by Mootools to set css color values.

['63','64','65'].hexToRgb() //returns "rgb(99,100,101)"

Number.toInt() just returns the number; useful because toInt must work on both Strings and Numbers. Note that if you call .toInt() on a float, you'll get an integer back.

var x = 10;
x.toInt(); //returns 10

var x = 10.01;
x.toFloat(); //returns 10.01

var x = 10.01;
x.toInt(); //returns 10

(12).limit(2, 6.5)  // returns 6.5

(-4).limit(2, 6.5)  // returns 2

(4.3).limit(2, 6.5) // returns 4.3

Returns the number rounded to specified precision: the number of digits after the decimal point. Can also be negative or zero (default).

12.45.round() // returns 12

12.45.round(1) // returns 12.5

12.45.round(-1) // returns 10

Executes a passed in function the specified number of times:

(3).times(alert)
//alert(0)
//alert(1)
//alert(2)

Here is the documentation for Function.js.

.create automatically wraps the function into another one with the defined set of functionalities, therefore shortens your code. It's used throughout mootools itself, as the foundation for .pass, .bind, .delay, .periodical.

You probably won't find find yourself using create directly that often (well, at least I don't).

.create takes a handful of options in a single argument as an object:

'bind'

the object to bind the "this" keyword within your function

'event'

capture the event that fired this function and pass it in as an argument

'arguments'

the arguments to pass to your function

'delay'

a duration to delay before executing the function

'periodical'

the duration to wait between executions of this function repeatedly

'attempt'

catch any error in this function and return it

By way of example, here's what Function.pass (the next item in the tutorial) looks like:

pass: function(args, bind){
	return this.create({'arguments': args, 'bind': bind});
}

More on .pass in a second, but what this demonstrates is taking a function, setting up some definitions (arguments, bind) and returning it ready to execute later.

/*syntax: Function.pass(arguments, bind)
  bind is optional; more on bind later
  example: myFunction.pass([arg1, arg2], myElement);*/
function say(msg){
    alert(msg);
};
say.pass('hello world')();

You might ask yourself why do this, but you'll see why in examples later. Basically, you don't always want to execute a function immediately, and without something like the .pass method, you have no way to pass variables to that function without executing it. myFunction(value) executes myFunction. myFunction.pass(value) sets up myFunction so that it can execute later.

Let's say you have an effect that's going to make something fade out. When it's done, you want to have it execute a callback of some sort. Your effect has an option for you to hand it a function to execute when it's finished, but you need to pass that function some variables. If you did something like: "onComplete: myFunction(value)" you'll execute your function immediately, and onComplete will be equal to whatever is returned, which isn't what you want. Instead, you do "onComplete: myFunction.pass(value)" - which gets you want you want. myFunction.pass(value) returns an instance of that function with that parameter set. So when you execute onComplete() you're really executing myFunction(value).

The "this" namespace inside an object (such as a function) refers to the instance of that object. It's really useful for a lot of things, not the least of which is referring to other functions in the same object or the state of some variable. The problem is that you might author functionality that needs to be able to refer to variables in the object that's calling it. Below is a simple example of this, but when you write more complex classes and functions you'll find that this ability to define what "this" is in a given context is a necessity.

This example should change this paragraph to have a border around it.

function myFunction(){
    this.setStyle('border', '1px solid black');
    /*note that 'this' here refers to myFunction, not an element
      we'll need to bind this function to the element we want to
      alter*/
};
/*bind the element I want to effect to the function
note that a function is returned, not executed.*/
var myBoundFunction = myFunction.bind($('bindExample'));
/*execute that new function with the bound object*/
myBoundFunction();

You use bindAsEventListener when you want as the first argument the event, no matter if its ie or firefox or any other browser.

function fn(event){
  //event is the event, no need to do window.event || event
  //the keyword this is the element, because we used element in the bindAsEventListener argument.
};
element.onclick = fn.bindAsEventListener(element);

with bindWithEvent you'll get the mootools Event wrapper as the first argument:

function fn(event){
  //event is the mootools event, that supports all the cool stuff like
  event.page.y //position of the mouse in the page
  event.key //the key pressed
  event.shift //if shift has been pressed to trigger the event
  //and tons of others, refer to the docs, Native/Event.js
  //the keyword this is the element, because we used element in the bindWithEvent argument.
};
element.onclick = fn.bindWithEvent(element);

Basically bind withEvent will do this automatically for you:

function fn(event){
    event = new Event(event);
};
element.onclick = fn;

Yes, you can set up delays with setTimeout, but it's sometimes convoluted and complicated. Additionally, delay allows you to bind an element to the function that's going to get delayed.

The example below should draw a border around this paragraph after a one second delay.

function myFunction(){
    this.setStyle('border', '1px solid black');
};
myFunction.delay(1000, $('delayExample'));

Here's a great example of binding. If the element were an argument to the function, I couldn't call the function with an argument with out executing it. This type of syntax wouldn't work:

myFunction($('delayExample')).delay(500);

...couldn't work, because you'd execute the function immediately, and .delay would then attempt to execute as a method on what was returned.

You could do this though:

myFunction.delay(500, $('delayExample'));
//OR
myFunction.pass($('delayExample')).delay(500);

.delay takes three parameters: the delay (in ms), an object to bind (can be null), and any arguments you wish to pass the function. If you only pass one, you can just specify the argument, if you pass more than one, use an array:

myFunction.delay(500, null, [$('delayExample'), argument2, etc.]);

There's also //.periodical//, which repeatedly executes your function.

	function blink(element){
		if(element.getStyle('visibility') == 'visible') element.setStyle('visibility', 'hidden');
		else element.setStyle('visibility', 'visible');
	}
	var blinker = blink.periodical(200, null, $('periodicalExample')); 
	/*curses! the blink tag is back!*/
	$clear.delay(2200, null, blinker);//make it stop!

This is a shortcut for try/catch. Function.attempt will catch any errors in your function and return false to you if the function fails (otherwise it returns the results of your function).

This is a change from Mootools 1.0 where Function.attempt() returned the error thrown instead.

function test(value){
	alert(value.something); 
	/*in this test, value won't be defined, 
	so it'll throw an error*/
}
test.attempt(); /*returns false because of the error*/

The above is the equivalent of this:

function test(value){
	try {
		alert(value.something); 
		/*in this test, value won't be defined, 
		so it'll throw an error*/
	} catch(err) {
		return false;
	}
}

Here is the documentation for Element.js.

The Element object gets a LOT of love in Mootools. Most of the functions in the Element object are pretty self explanatory. Element.getTag does what you'd think it would. Element.remove has no surprises.

Note: Mootools 1.1 split up all the functionality in Element.js into several other scripts in the /Element directory. Element.js now contains the core functionality for Element, but if you're looking for something that used to be here, look in Additional Element Extensions.

This just creates a new element object - same as document.createElement, but it also applies the Mootools extensions to that element.

var img = new Element("img");

new Element also lets you set any properties when you create it:

new Element('a', {
	styles: {
		'display': 'block',
		'border': '1px solid black'
	},
	events: {
		click: function(){
			//something to do on click
		},
		mousedown: function(){
			//something to do on mousedown
		}
	},
	/*	class must be in quotes; it is a reserved word in IE	*/
	'class': 'myClassSuperClass',
	href: 'http://mad4milk.net'
});

The key 'styles' will be used as setStyles, the key 'events' will be used as addEvents. Any other key is used as setProperty. Note that you don't have to write the keys with quotes ('styles' or 'events' - these can just be {styles: '...', events: '...'} - but class DOES have to be in quotes as it's a reserved word in IE.

Note that this doesn't insert the element into the DOM, you need to use Element.adopt, .injectInside, .injectAfter, etc. to put the element into the document:

new Element('img', {src: 'http//...'}).injectInside($(myElement));

The $ function has 2 purposes: getting an element by its id, and applying all the elements methods to that element. $ can take 2 types of arguments: a string representing the id of an element in the dom, or an element reference:

//by a string representing the id of an element:
var element1 = $('getElementByIdExample');
 
//by element reference:
var element2 = $(element1.childNodes[0]);

now both element1 and element2 will have the mootools elements extensions applied.

Final Note:

In firefox and other modern browsers such as Safari and Opera, the elements extensions are automatically applied to all the elements in the dom. For the more unfortunate and crippled browsers like internet explorer, running the $ function is mandatory to have the extensions applied.

The $$ (double dollar) function has one big important role in Mootools: transforming a bunch of elements in an instance of the Elements class.

$$ can take any number of different types of arguments:

• element references
• arrays of elements ids
• native html collections (such as document.getElementByTagName, or element.childNodes)

Note: If you included Element.Selectors.js, $$ can also target elements using a CSS selector.

 //all the pre and p tag elements on this page.
$$('pre', 'p');
 
//all the pres contained in the element with id=myElement
var myElement = $('myElement');
$$(myElement.getElementsByTagName('pre'));
 
//here we pass in several collections (all either Arrays
//or instances of Elements)
var myElements = $$(myElement.childNodes, myElement, ['anotherElementId']);

Note: the collection returned will be first all the elements matching the first arguments, in order, then all the elements that match the second, in order, and so on. If you have alternating pre and p tags, the above example will still return all the pre tags, then all the p tags.

The Elements class (docs) is really just an array of elements, but it's been extended to allow you to execute any of the extensions that you could execute on an element. So, for example:

/* turn all the paragraphs on this page red */
$$('p').setStyle('color','red');
/* ok, that's ugly, let's turn it back */
(function(){$$('p').setStyle('color','#000')}).delay(1000);

The same is true for every method listed down below. The Elements class can be extended like the Element class and every Elements object will get the properties. There's a catch though.

THIS IS IMPORTANT

When you execute a method on a collection of elements, it will iterate through all the elements and execute that method on each. This is fine when you only need to execute one method, but if you need to execute more than one method, you should loop through the elements. Multiple method calls on an Elements object will loop through them all each time, and this will be very slow.

So, this is bad:

$$('p').setStyle('color','red');
$$('p').effect('opacity').start(0,1);
//This is the same thing (and also bad):
$$('p').setStyle('color','red').effect('opacity').start(0,1);

In this example, it's far better to use a loop:

$$('p').each(function(p){
  p.setStyle('color','red').effect('opacity').start(0,1);
});

$$() returns an instance of the Elements class, which is also an array, so it inherits all the methods in the Array object.

You can set events, styles and properties with this shortcut; same syntax as the second argument when calling new Element.

$(el).set({events: ..., styles: ..., etc.});
//which is the same as
$(el).setStyles({...}).addEvents({...}).etc.

Pretty much what it looks like. Injects the element relative to the one passed in as an argument.

html:
<div id="myElement"></div>
<div id="mySecondElement"></div>
<script>$('mySecondElement').injectBefore('myElement');</script>
resulting html:
<div id="mySecondElement"></div>
<div id="myElement"></div>

.injectInside uses .appendChild on the supplied element:

html:
<div id="myElement"></div>
<div id="mySecondElement"></div>
<script>$('mySecondElement').injectInside('myElement');</script>
resulting html:
<div id="myElement"><div id="mySecondElement"></div></div>

.injectInside uses .appendChild on the supplied element:

html:
<div id="myElement">
	<div id="childOne"></div>
	<div id="childTwo"></div>
	<div id="childThree"></div>
</div>
<script>$('childTwo').injectTop('myElement');</script>
resulting html:
<div id="myElement">
	<div id="childTwo"></div>
	<div id="childOne"></div>
	<div id="childThree"></div>
</div>

Removes the element from the DOM:

<div id="myElement">
	<div id="childOne"></div>
	<div id="childTwo"></div>
	<div id="childThree"></div>
</div>
<script>$('childTwo').remove();</script>
resulting html:
<div id="myElement">
	<div id="childOne"></div>
	<div id="childThree"></div>
</div>

Clones the Element and returns the copy:

var clone = $('myElement').clone().injectAfter('myElement');
//clones the Element and append the clone after the Element.

Element.clone takes an argument (a boolean): true will clone the node's children (this is the default), false will only clone the node:

<div id="myElement">
	<div id="childOne"></div>
	<div id="childTwo"></div>
	<div id="childThree"></div>
</div>
<script>$('myElement').clone(false).injectAfter('myElement');</script>
resulting html:
<div id="myElement">
	<div id="childOne"></div>
	<div id="childTwo"></div>
	<div id="childThree"></div>
</div>
<div id="myElement"></div>

This is just like .injectInside, but in reverse (it appends the supplied element to the applied one):

html:
<div id="myElement"></div>
<div id="mySecondElement"></div>
<script>$('mySecondElement').adopt('myElement');</script>
resulting html:
<div id="mySecondElement"><div id="myElement"></div></div>

$('myOldElement').replaceWith($('myNewElement'));

$('myOldElement') is gone, and $('myNewElement') is in its place.

<div id="myElement">hey</div>
<script>
	$('myElement').appendText(' howdy'); 
	//myElement innerHTML is now "hey howdy"
</script>

These do pretty much what they look like they'd do.

This paragraph has id = cssClassesExample for the examples below.

/*does the paragraph above have the className blue?*/
$('cssClassesExample').hasClass('blue');

/*let's add it*/
$('cssClassesExample').addClass('blue');

/*now let's remove it*/
$('cssClassesExample').removeClass('blue');

/*now let's toggle it on and off*/
$('cssClassesExample').toggleClass('blue');

Pretty straight forward:

This paragraph has id = getStyleExample for the examples below.

$('getStyleExample').getStyle('width'); //returns something like "528px"

$('getStyleExample').getStyle('width').toInt(); //returns 528 (an integer)

$('getStyleExample').getStyles('width', 'height'); 
//returns something like {width:"528px", height:"89px"}

$('getStyleExample').getStyle('width').toInt(); //returns 528 (an integer)