# Element.js

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

#### Dependencies

Moo.js, Function.js, Array.js, String.js

#### Author

Valerio Proietti, http://mad4milk.net

#### 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.js | Contains useful Element prototypes, to be used with the dollar function $.
Element | Custom class to allow all of its methods to be used with any DOM element via the dollar function $.
Properties |
initialize | Creates a new element of the type passed in.
injectBefore | Inserts the Element before the passed element.
injectAfter | Same as Element.injectBefore, but inserts the element after.
injectInside | Same as Element.injectBefore, but inserts the element inside.
adopt | Inserts the passed element inside the Element.
remove | Removes the Element from the DOM.
clone | Clones the Element and returns the cloned one.
replaceWith | Replaces the Element with an element passed.
appendText | Appends text node to a DOM element.
hasClass | Tests the Element to see if it has the passed in className.
addClass | Adds the passed in class to the Element, if the element doesnt already have it.
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.
setStyle | Sets a css property to the Element.
setStyles | Applies a collection of styles to the Element.
setOpacity | Sets the opacity of the Element, and sets also visibility == “hidden” if opacity == 0, and visibility = “visible” if opacity == 1.
getStyle | Returns the style of the Element given the property passed in.
addEvent | Attaches an event listener to a DOM element.
removeEvent | Works as Element.addEvent, but instead removes the previously added event listener.
getPrevious | Returns the previousSibling of the Element, excluding text nodes.
getNext | Works as Element.getPrevious, but tries to find the nextSibling.
getNext | Works as Element.getPrevious, but tries to find the firstChild.
getLast | Works as Element.getPrevious, but tries to find the lastChild.
setProperty | Sets an attribute for the Element.
setProperties | Sets numerous attributes for the Element.
setHTML | Sets the innerHTML of the Element.
getProperty | Gets the an attribute of the Element.
getTag | Returns the tagName of the element in lower case.
getTop | Returns the distance from the top of the window to the Element.
getLeft | Returns the distance from the left of the window to the Element.
getValue | Returns the value of the Element, if its tag is textarea, select or input.
Utility Functions |
Functions |
$Element | Applies a method with the passed in args to the passed in element.
$() | returns the element passed in with all the Element prototypes applied.

## Element

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

Summary

Properties |
initialize | Creates a new element of the type passed in.
injectBefore | Inserts the Element before the passed element.
injectAfter | Same as Element.injectBefore, but inserts the element after.
injectInside | Same as Element.injectBefore, but inserts the element inside.
adopt | Inserts the passed element inside the Element.
remove | Removes the Element from the DOM.
clone | Clones the Element and returns the cloned one.
replaceWith | Replaces the Element with an element passed.
appendText | Appends text node to a DOM element.
hasClass | Tests the Element to see if it has the passed in className.
addClass | Adds the passed in class to the Element, if the element doesnt already have it.
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.
setStyle | Sets a css property to the Element.
setStyles | Applies a collection of styles to the Element.
setOpacity | Sets the opacity of the Element, and sets also visibility == “hidden” if opacity == 0, and visibility = “visible” if opacity == 1.
getStyle | Returns the style of the Element given the property passed in.
addEvent | Attaches an event listener to a DOM element.
removeEvent | Works as Element.addEvent, but instead removes the previously added event listener.
getPrevious | Returns the previousSibling of the Element, excluding text nodes.
getNext | Works as Element.getPrevious, but tries to find the nextSibling.
getNext | Works as Element.getPrevious, but tries to find the firstChild.
getLast | Works as Element.getPrevious, but tries to find the lastChild.
setProperty | Sets an attribute for the Element.
setProperties | Sets numerous attributes for the Element.
setHTML | Sets the innerHTML of the Element.
getProperty | Gets the an attribute of the Element.
getTag | Returns the tagName of the element in lower case.
getTop | Returns the distance from the top of the window to the Element.
getLeft | Returns the distance from the left of the window to the Element.
getValue | Returns the value of the Element, if its tag is textarea, select or input.

### Properties

### initialize

Creates a new element of the type passed in.

#### Arguments

el | the tag name for the element you wish to create.

#### Example

>     var div = new Element('div');

### injectBefore

Inserts the Element before the passed element.

#### Parameteres

el | a 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.

#### Example

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

### injectAfter

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

### injectInside

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

### adopt

Inserts the passed element inside the Element. Works as Element.injectInside but in reverse.

#### Parameteres

el | a 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.

### remove

Removes the Element from the DOM.

#### Example

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

### clone

Clones the Element and returns the cloned one.

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

#### Parameteres

el | a 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

text | the 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

true | the Element has the class
false | it doesn’t

#### Arguments

className | 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

className | 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

className | the 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

property | the property to set
value | the value to which to set it

#### Example

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

### setStyles

Applies a collection of styles to the Element.

#### Arguments

source | an object or string containing all the styles to apply

#### Examples

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

OR

>     $('myElement').setStyle('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 == 1.

#### Arguments

opacity | Accepts numbers 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

property | the 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

### addEvent

Attaches an event listener to a DOM element.

#### Arguments

action | the event to monitor (‘click’, ‘load’, etc)
fn | the function to execute

#### Example

>     $('myElement').addEvent('click', function(){alert('clicked!')});

### removeEvent

Works as Element.addEvent, but instead removes the previously added event listener.

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

### getNext

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

### getLast

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

### setProperty

Sets an attribute for the Element.

#### Arguments

property | the property to assign the value passed in
value | the 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

source | an 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

html | the new innerHTML for the element.

#### Example

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

### getProperty

Gets the an attribute of the Element.

#### Arguments

property | the attribute to retrieve

#### Example

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

#### Returns

the value, or an empty string

### getTag

Returns the tagName of the element in lower case.

#### Example

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

#### Returns

The tag name in lower case

### getTop

Returns the distance from the top of the window to the Element.

### getLeft

Returns the distance from the left of the window to the Element.

### getValue

Returns the value of the Element, if its tag is textarea, select or input.

## Utility Functions

Summary

Functions |
$Element | Applies a method with the passed in args to the passed in element.
$() | returns the element passed in with all the Element prototypes applied.

### Functions

### $Element

> function $Element( | el,
> | method,
> | args | )

Applies a method with the passed in args to the passed in element. Useful if you dont want to extend the element

#### Arguments

el | the element
method | a string representing the Element Class method to execute on that element
args | an array representing the arguments to pass to that method

#### Example

>     $Element(el, 'hasClass', className) //true or false

### $()

> function $( | el | )

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

#### Arguments

el | a 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.

> function $( | el | )

returns the element passed in with all the Element prototypes applied.
Inserts the Element before the passed element.
Adds the passed in class to the Element, if the element doesnt already have it.
Returns the previousSibling of the Element, excluding text nodes.

> function $Element( | el,
> | method,
> | args | )

Applies a method with the passed in args to the passed in element.
My Object Oriented javascript.
Contains Function prototypes, utility functions and Chain.

> function $A( | array | )

Copy the array and returns it.
Same as Array.copy, but as function.
Contains Array prototypes and the function $A;
Contains String prototypes and Number prototypes.
Same as <Element.injectBefore>, but inserts the element inside.