Element.js

Contains useful Element prototypes, to be used with the dollar function $.

License

MIT-style license.

Credits

  • Some functions are inspired by those found in prototype.js http://prototype.conio.net/ © 2005 Sam Stephenson sam [at] conio [dot] net, MIT-style license
Summary
Element.jsContains useful Element prototypes, to be used with the dollar function $.
ElementCustom class to allow all of its methods to be used with any DOM element via the dollar function $.
Properties
initializeCreates a new element of the type passed in.
Elements
Utility Functions
Functions
$returns the element passed in with all the Element prototypes applied.
$$Selects, and extends DOM elements.
ElementCustom class to allow all of its methods to be used with any DOM element via the dollar function $.
Properties
setyou can set events, styles and properties with this shortcut.
injectBeforeInserts the Element before the passed element.
injectAfterSame as Element.injectBefore, but inserts the element after.
injectInsideSame as Element.injectBefore, but inserts the element inside.
injectTopSame as Element.injectInside, but inserts the element inside, at the top.
adoptInserts the passed elements inside the Element.
removeRemoves the Element from the DOM.
cloneClones the Element and returns the cloned one.
replaceWithReplaces the Element with an element passed.
appendTextAppends text node to a DOM element.
hasClassTests the Element to see if it has the passed in className.
addClassAdds the passed in class to the Element, if the element doesnt already have it.
removeClassWorks like Element.addClass, but removes the class from the element.
toggleClassAdds or removes the passed in class name to the element, depending on if it’s present or not.
setStyleSets a css property to the Element.
setStylesApplies a collection of styles to the Element.
setOpacitySets the opacity of the Element, and sets also visibility == “hidden” if opacity == 0, and visibility = “visible” if opacity > 0.
getStyleReturns the style of the Element given the property passed in.
getStylesReturns an object of styles of the Element for each argument passed in.
getPreviousReturns the previousSibling of the Element, excluding text nodes.
getNextWorks as Element.getPrevious, but tries to find the nextSibling.
getFirstWorks as Element.getPrevious, but tries to find the firstChild.
getLastWorks as Element.getPrevious, but tries to find the lastChild.
getParentreturns the $(element.parentNode)
getChildrenreturns all the $(element.childNodes), excluding text nodes.
hasChildreturns true if the passed in element is a child of the $(element).
getPropertyGets the an attribute of the Element.
removePropertyRemoves an attribute from the Element
getPropertiessame as Element.getStyles, but for properties
setPropertySets an attribute for the Element.
setPropertiesSets numerous attributes for the Element.
setHTMLSets the innerHTML of the Element.
setTextSets the inner text of the Element.
getTextGets the inner text of the Element.
getTagReturns the tagName of the element in lower case.
emptyEmpties an element of all its children.

Element

Custom class to allow all of its methods to be used with any DOM element via the dollar function $.

Summary
Properties
initializeCreates a new element of the type passed in.

Properties

initialize

Creates a new element of the type passed in.

Arguments

elstring; the tag name for the element you wish to create. you can also pass in an element reference, in which case it will be extended.
propsobject; the properties you want to add to your element.  Accepts the same keys as Element.setProperties, but also allows events and styles

Props

the key styles will be used as setStyles, the key events will be used as addEvents. any other key is used as setProperty.

Example

new Element('a', {
    'styles': {
        'display': 'block',
        'border': '1px solid black'
    },
    'events': {
        'click': function(){
            //aaa
        },
        'mousedown': function(){
            //aaa
        }
    },
    'class': 'myClassSuperClass',
    'href': 'https://github.com/kamicane'
});

Elements

  • Every dom function such as $$, or in general every function that returns a collection of nodes in mootools, returns them as an Elements class.
  • The purpose of the Elements class is to allow Element methods to work also on Elements array.
  • Elements is also an Array, so it accepts all the Array methods.
  • Every node of the Elements instance is already extended with $.

Example

$$('myselector').each(function(el){
 //...
});

some iterations here, $$(‘myselector’) is also an array.

$$('myselector').setStyle('color', 'red');

every element returned by $$(‘myselector’) also accepts Element methods, in this example every element will be made red.

Utility Functions

Summary
Functions
$returns the element passed in with all the Element prototypes applied.
$$Selects, and extends DOM elements.

Functions

$

returns the element passed in with all the Element prototypes applied.

Arguments

ela reference to an actual element or a string representing the id of an element

Example

$('myElement') // gets a DOM element by id with all the Element prototypes applied.
var div = document.getElementById('myElement');
$(div) //returns an Element also with all the mootools extentions applied.

You’ll use this when you aren’t sure if a variable is an actual element or an id, as well as just shorthand for document.getElementById().

Returns

a DOM element or false (if no id was found).

Note

you need to call $ on an element only once to get all the prototypes.  But its no harm to call it multiple times, as it will detect if it has been already extended.

$$

document.getElementsBySelector = document.getElementsByTagName; function $$()

Selects, and extends DOM elements.  Elements arrays returned with $$ will also accept all the Element methods.  The return type of element methods run through $$ is always an array.  If the return array is only made by elements, $$ will be applied automatically.

Arguments

HTML Collections, arrays of elements, arrays of strings as element ids, elements, strings as selectors.  Any number of the above as arguments are accepted.

Note

if you load Element.Selectors.js, $$ will also accept CSS Selectors, otherwise the only selectors supported are tag names.

Example

$$('a') //an array of all anchor tags on the page
$$('a', 'b') //an array of all anchor and bold tags on the page
$$('#myElement') //array containing only the element with id = myElement. (only with <Element.Selectors.js>)
$$('#myElement a.myClass') //an array of all anchor tags with the class "myClass"
//within the DOM element with id "myElement" (only with <Element.Selectors.js>)
$$(myelement, myelement2, 'a', ['myid', myid2, 'myid3'], document.getElementsByTagName('div')) //an array containing:
// the element referenced as myelement if existing,
// the element referenced as myelement2 if existing,
// all the elements with a as tag in the page,
// the element with id = myid if existing
// the element with id = myid2 if existing
// the element with id = myid3 if existing
// all the elements with div as tag in the page

Returns

arrayarray of all the dom elements matched, extended with $.  Returns as Elements.

Element

Custom class to allow all of its methods to be used with any DOM element via the dollar function $.

Summary
Properties
setyou can set events, styles and properties with this shortcut.
injectBeforeInserts the Element before the passed element.
injectAfterSame as Element.injectBefore, but inserts the element after.
injectInsideSame as Element.injectBefore, but inserts the element inside.
injectTopSame as Element.injectInside, but inserts the element inside, at the top.
adoptInserts the passed elements inside the Element.
removeRemoves the Element from the DOM.
cloneClones the Element and returns the cloned one.
replaceWithReplaces the Element with an element passed.
appendTextAppends text node to a DOM element.
hasClassTests the Element to see if it has the passed in className.
addClassAdds the passed in class to the Element, if the element doesnt already have it.
removeClassWorks like Element.addClass, but removes the class from the element.
toggleClassAdds or removes the passed in class name to the element, depending on if it’s present or not.
setStyleSets a css property to the Element.
setStylesApplies a collection of styles to the Element.
setOpacitySets the opacity of the Element, and sets also visibility == “hidden” if opacity == 0, and visibility = “visible” if opacity > 0.
getStyleReturns the style of the Element given the property passed in.
getStylesReturns an object of styles of the Element for each argument passed in.
getPreviousReturns the previousSibling of the Element, excluding text nodes.
getNextWorks as Element.getPrevious, but tries to find the nextSibling.
getFirstWorks as Element.getPrevious, but tries to find the firstChild.
getLastWorks as Element.getPrevious, but tries to find the lastChild.
getParentreturns the $(element.parentNode)
getChildrenreturns all the $(element.childNodes), excluding text nodes.
hasChildreturns true if the passed in element is a child of the $(element).
getPropertyGets the an attribute of the Element.
removePropertyRemoves an attribute from the Element
getPropertiessame as Element.getStyles, but for properties
setPropertySets an attribute for the Element.
setPropertiesSets numerous attributes for the Element.
setHTMLSets the innerHTML of the Element.
setTextSets the inner text of the Element.
getTextGets the inner text of the Element.
getTagReturns the tagName of the element in lower case.
emptyEmpties an element of all its children.

Properties

set

you can set events, styles and properties with this shortcut. same as calling new Element.

injectBefore

Inserts the Element before the passed element.

Arguments

elan element reference or the id of the element to be injected in.

Example

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

injectAfter

Same as Element.injectBefore, but inserts the element after.

injectInside

Same as Element.injectBefore, but inserts the element inside.

injectTop

Same as Element.injectInside, but inserts the element inside, at the top.

adopt

Inserts the passed elements inside the Element.

Arguments

accepts elements references, element ids as string, selectors ($$(‘stuff’)) / array of elements, array of ids as strings and collections.

remove

Removes the Element from the DOM.

Example

$('myElement').remove() //bye bye

clone

Clones the Element and returns the cloned one.

Arguments

contentsboolean, when true the Element is cloned with childNodes, default true

Returns

the cloned element

Example

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

replaceWith

Replaces the Element with an element passed.

Arguments

ela string representing the element to be injected in (myElementId, or div), or an element reference.  If you pass div or another tag, the element will be created.

Returns

the passed in element

Example

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

appendText

Appends text node to a DOM element.

Arguments

textthe text to append.

Example

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

hasClass

Tests the Element to see if it has the passed in className.

Returns

truethe Element has the class
falseit doesn’t

Arguments

classNamestring; the class name to test.

Example

<div id="myElement" class="testClass"></div>
$('myElement').hasClass('testClass'); //returns true

addClass

Adds the passed in class to the Element, if the element doesnt already have it.

Arguments

classNamestring; the class name to add

Example

<div id="myElement" class="testClass"></div>
$('myElement').addClass('newClass'); //<div id="myElement" class="testClass newClass"></div>

removeClass

Works like Element.addClass, but removes the class from the element.

toggleClass

Adds or removes the passed in class name to the element, depending on if it’s present or not.

Arguments

classNamethe class to add or remove

Example

<div id="myElement" class="myClass"></div>
$('myElement').toggleClass('myClass');
<div id="myElement" class=""></div>
$('myElement').toggleClass('myClass');
<div id="myElement" class="myClass"></div>

setStyle

Sets a css property to the Element.

Arguments

propertythe property to set
valuethe value to which to set it; for numeric values that require “px” you can pass an integer

Example

$('myElement').setStyle('width', '300px'); //the width is now 300px
$('myElement').setStyle('width', 300); //the width is now 300px

setStyles

Applies a collection of styles to the Element.

Arguments

sourcean object or string containing all the styles to apply.  When its a string it overrides old style.

Examples

$('myElement').setStyles({
   border: '1px solid #000',
   width: 300,
   height: 400
});

OR

$('myElement').setStyles('border: 1px solid #000; width: 300px; height: 400px;');

setOpacity

Sets the opacity of the Element, and sets also visibility == “hidden” if opacity == 0, and visibility = “visible” if opacity > 0.

Arguments

opacityfloat; Accepts values from 0 to 1.

Example

$('myElement').setOpacity(0.5) //make it 50% transparent

getStyle

Returns the style of the Element given the property passed in.

Arguments

propertythe css style property you want to retrieve

Example

$('myElement').getStyle('width'); //returns "400px"
//but you can also use
$('myElement').getStyle('width').toInt(); //returns 400

Returns

the style as a string

getStyles

Returns an object of styles of the Element for each argument passed in.  Arguments: properties - strings; any number of style properties Example:

$('myElement').getStyles('width','height','padding');
//returns an object like:
{width: "10px", height: "10px", padding: "10px 0px 10px 0px"}

getPrevious

Returns the previousSibling of the Element, excluding text nodes.

Example

$('myElement').getPrevious(); //get the previous DOM element from myElement

Returns

the sibling element or undefined if none found.

getNext

Works as Element.getPrevious, but tries to find the nextSibling.

getFirst

Works as Element.getPrevious, but tries to find the firstChild.

getLast

Works as Element.getPrevious, but tries to find the lastChild.

getParent

returns the $(element.parentNode)

getChildren

returns all the $(element.childNodes), excluding text nodes.  Returns as Elements.

hasChild

returns true if the passed in element is a child of the $(element).

getProperty

Gets the an attribute of the Element.

Arguments

propertystring; the attribute to retrieve

Example

$('myImage').getProperty('src') // returns whatever.gif

Returns

the value, or an empty string

removeProperty

Removes an attribute from the Element

Arguments

propertystring; the attribute to remove

getProperties

same as Element.getStyles, but for properties

setProperty

Sets an attribute for the Element.

Arguments

propertystring; the property to assign the value passed in
valuethe value to assign to the property passed in

Example

$('myImage').setProperty('src', 'whatever.gif'); //myImage now points to whatever.gif for its source

setProperties

Sets numerous attributes for the Element.

Arguments

sourcean object with key/value pairs.

Example

$('myElement').setProperties({
    src: 'whatever.gif',
    alt: 'whatever dude'
});
<img src="whatever.gif" alt="whatever dude">

setHTML

Sets the innerHTML of the Element.

Arguments

htmlstring; the new innerHTML for the element.

Example

$('myElement').setHTML(newHTML) //the innerHTML of myElement is now = newHTML

setText

Sets the inner text of the Element.

Arguments

textstring; the new text content for the element.

Example

$('myElement').setText('some text') //the text of myElement is now = 'some text'

getText

Gets the inner text of the Element.

getTag

Returns the tagName of the element in lower case.

Example

$('myImage').getTag() // returns 'img'

Returns

The tag name in lower case

empty

Empties an element of all its children.

Example

$('myDiv').empty() // empties the Div and returns it

Returns

The element.

returns the element passed in with all the Element prototypes applied.
document.getElementsBySelector = document.getElementsByTagName; function $$()
Selects, and extends DOM elements.
Inserts the Element before the passed element.
Same as Element.injectBefore, but inserts the element inside.
Adds the passed in class to the Element, if the element doesnt already have it.
Returns the previousSibling of the Element, excluding text nodes.
Returns an object of styles of the Element for each argument passed in.
Sets numerous attributes for the Element.
Custom class to allow all of its methods to be used with any DOM element via the dollar function $.
A collection of The Array Object prototype methods.
Css Query related functions and Element extensions

Documentation by Aaron Newton & Mootools Developers, generated by NaturalDocs and GeSHi