top ↑include

Element.include(Object methods[, boolean don_rewrite])

Description

Registers additional methods for the DOM elements on the page.

Example

Element.include({
myMethod: function() {....}
});

$('my_element').myMethod();

top ↑initialize

initialize(String tag_name[, Object options]) -> Element new

Description

The standard constructor which takes two arguments, the tag name and options. Options are generally the element attributes and additionally you can send the following keys to preset your element properties on instance:

• ‘html’ - a source code to fill up the innerHTML property
• ‘class’ - CSS class name(s) for the element
• ‘style’ - a hash (or string) of styles to be preset
• ‘on’ - same as 'observe'

Everything will be handled in one flow.

Example

var element = new Element('div');
var element = new Element('p', {
id: 'some-paragraph',
'class': 'come class',
style: {
padding: '10pt'
},
on: {
mouseover: function() { ... }
}
});

top ↑addClass

addClass(String name) -> Element self

Description

Adds the given CSS class name to the element class names list.

Example

var element = document.getElementById('element');
element.className = 'foo';

$(element).addClass('bar');

element.className; // -> 'foo bar'

top ↑append

append(element1[, elment2, ...]) -> Element self

Description

A shortcut to insert several elements to the bottom of the current one

Example

element.append(
$('element-1'), $('element-2'), $('element-3')
);

// same as
element.insert([
$('element-1'), $('element-2'), $('element-3')
], 'bottom');

top ↑children

children([String css_rule]) -> Array of elements

Description

Returns a list of the immediate descendants from the element, optionally filtered by the given CSS rule.

Example

/*
<div id="one">
<div id="two"></div>
<div id="three"></div>
</div>
*/

$('one').children(); // -> [div#two, div#three]
$('one').children('#two'); // -> [div#two]

top ↑clean

clean() -> Element self

Description

Removes all child nodes from the element.

Example

$('element').clean();
$('element').html(); // -> ''

top ↑clone

clone() -> Element new

Description

Creates a complete clone of the current element with the same content

Example

var element = $('element');
var clone = element.clone();

element != clone;
element._ != clone._;
element.html() == clone.html();

top ↑data

data(String key) -> mixed data
data(Object values) -> Element self
data(String key, mixed value) -> Element self

Description

HTML5 datasets access method

Example

element.data('something'); // -> the 'data-something' attribute data
element.data('something', 'something'); // -> sets 'data-something' attribute
element.data('something', null); // -> removes 'data-something' attribute
element.data({
one: 1, two: 2
}); // -> sets 'data-one' and 'data-two'

// HTML5 datasets access
element.set('data-name-one', '1');
element.set('data-name-two', '2');
element.data('name'); // -> {one: 1, two: 2}

// HTML5 datasets setting
element.data('name', {one: 1, two: 2});
element.get('data-name-one'); // -> '1'
element.get('data-name-two'); // -> '2'

top ↑delegate

delegate(String event, String css_rule, Function callback) -> Element self
delegate(String event, String css_rule, String callback) -> Element self
delegate(String event, Object css_rules_and_callbacks) -> Element self

Description

Delegates events handling to subelements that match the given css-rule.

NOTE: Callbacks will be called in the context of matching elements

Example

$(element).delegate('click', 'div.blue', func_1);
$(element).delegate('click', 'div.green', func_2);

$(element).delegate('click', 'div.blue', 'addClass', 'was-blue');
$(element).delegate('click', 'div.green', 'addClass', 'was-green');

$(element).delegate('click', {
'div.blue': func_1,
'div.green': func_2
});

top ↑delegates

delegates(String event[, String css_rule[, Function callback]]) -> boolean
delegates(String event[, Object rules_and_callback]) -> boolean

Description

Checks if this element delegates certain events to certain types of sub-elements

Example

$(element).delegates('click');
$(element).delegates('click', 'div.red');
$(element).delegates('click', 'div.red', callback);

$(element).delegates('click', {
'div.red': callback_1,
'div.blue': callback_2
});

top ↑dimensions

dimensions() -> Object

Description

Returns the dimensions of the element in a single hash. Includes the width, height, top and left positions as well as scrollLeft and scrollTop values.

Example

$('element').dimensions();

top ↑doc

doc() -> Document document

Description

Returns a wrapped Document object to which this element belongs to

Example

$(element).doc().find('div.class');

top ↑empty

empty() -> boolean

Description

Checks if the element has no internal text or elements.

Example

$('element').empty();

top ↑erase

erase(String name) -> Element self

Description

Erases the attribute with the given name from an element.

Example

// <div id="div" title="some title"></div>

$('div').has('title'); // -> true

$('div').erase('title');

$('div').has('title'); // -> false

top ↑find

find(String css_rule[, boolean raw]) -> Array of elements

Description

Finds all matching elements from the internal structure of the element.

NOTE: if the second attribute is set to true, then the method won’t wrap the elements into the Element class instances and returns an array of raw dom-elements instead.

Example

/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/

$('one').find('div'); // -> [div#two, div#three]
$('one').find('#three'); // -> [div#three]

top ↑first

first(String css_rule) -> Element or null

Description

Returns the first node in the internal structure that matches the given CSS rule.

Example

/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/

$('one').first('div'); // -> div#two
$('one').first('#three'); // -> div#three

top ↑get

get(String name) -> String value or null if empty

Description

Reads an element attribute. Returns null if the attribute is not set.

Example

// <div id="div" title="some title"></div>

$('div').get('title'); // -> 'some title'

top ↑getClass

getClass() -> String className

Description

A simple className property getter

Example

$('element').setClass('foo bar');
$('element').getClass(); // -> 'foo bar'

top ↑getStyle

getStyle(String name) -> String value or null

Description

Requests the element style by name. Supports both camelized and dasherized names.

NOTE: Checks both element styles as well as the computed (CSS) styles.

Example

$('element').hide();

$('element').getStyle('dispaly'); // -> 'none'

top ↑has

has(String name) -> boolean

Description

Checks if an element has a non-empty attribute with that name.

Example

// <div id="div" title="some title"></div>

$('div').has('title'); // -> true
$('div').has('rel'); // -> false

top ↑hasClass

hasClass(String class) -> boolean

Description

Checks if the element is assigned to the given CSS class name.

Example

$(element).setClass('foo bar');

$(element).hasClass('foo'); // -> true
$(element).hasClass('bar'); // -> true
$(element).hasClass('boo'); // -> false

top ↑hidden

hidden() -> boolean

Description

Checks if the element has style ‘display’ set to ‘none’.

NOTE: Checks both element styles as well as the computed (CSS) styles.

Example

/*
<style type="text/css">
#second { display: none }
</style>

<div id="first" style="display: none"></div>
<div id="second"></div>
<div id="third"></div>
*/

$('first').hidden(); // -> true
$('second').hidden(); // -> true
$('third').hidden(); // -> false

top ↑hide

hide([String effect[, Object options]]) -> Element self

Description

Hides the element. If a valid effect name was specified and the Fx module is available, the effect will be used to perform the hiding.

Example

$('some-element').hide();

$('some-element').hide('slide');
$('some-element').hide('slide', {duration: 'long'});

top ↑html

html() -> String innerHTML
html(mixed content); -> Element self

Description

A bidirectional method to work with the element’s innerHTML property.

Example

$('element').html('bla bla bla');
$('element').html(); // -> 'bla bla bla'

top ↑index

index() -> Integer element's index

Description

Returns the integer index of the element among his siblings

Example

/*
<div>
<div id="one">one</div>
<div id="two">two</div>
</div>
*/

$('one').index(); // -> 0
$('two').index(); // -> 1

top ↑insert

insert(mixed content[, String position]) -> Element self

Description

Inserts the given content into the element at the given position.

The content can be one of the following:

• an element instance
• a string with HTML code (scripts will be evaluated)
• a list of elements (array, or NodeList or something iterable)

Position can be one of the following: top / bottom / before / after / instead

The bottom value is used by default.

Example

var element = $('some-element');

element.insert(new Element('div', {html: 'new-div'}));

element.insert(new Element('div'), 'top');

element.insert([element1, element2, element3], 'before');

top ↑insertTo

insertTo(Element destination[, String position]) -> Element self

Description

Inserts the current element into the given one, optionally at the given position.

Example

var element1 = $('element1');
var element2 = $('element2');

element1.insertTo(element2, 'top');

element2.first() === element1;

top ↑listeners

listeners() -> Array of functions
listeners(String name) -> Array of functions

Description

Returns a list of element event listeners which can optionally be narrowed down by an event name scope.

Example

var func = function() {};

element.on('click', func);

element.listeners(); // -> [func]
element.listeners('click'); // -> [func]
element.listeners('mouseover'); // -> []

top ↑load

load(String url[, Object options]) -> Element self

Description

This method loads the given URL and updates the innerHTML property of the element with the response body.

Takes all the standard Xhr class options as the second parameter.

If there is any JavaScript code in the response, it will by default be automatically evaluated after the element body was updated.

NOTE: Will perform a GET request by default.

Example

element.load('/something');

element.load('/something', {
method: 'post',
spinner: 'spinner-id'
});

top ↑match

match(String css_rule) -> boolean

Description

Checks if the element matches the given CSS rule.

Example

// <div id="some-element"></div>

$('some-element').match('div'); // -> true
$('some-element').match('span'); // -> false

top ↑moveTo

moveTo(number left, number top) -> Element self
moveTo({x: number, y: number}) -> Element self

Description

Move the element to the given position.

Example

element.moveTo(100, 100);
element.moveTo({x: 100, y: 100});

top ↑next

next([String css_rule]) -> Element or null

Description

Returns the next sibling of the element or if a CSS rule is specified the next sibling that matches the rule.

Example

/*
<div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
</div>
*/

$('one').next(); // -> div#two
$('one').next('#three'); // -> div#three

top ↑nextSiblings

nextSiblings([String css_rule]) -> Array of elements

Description

Collects later siblings of the element, optionally filtered by the given CSS rule.

Example

/*
<div>
<div id="some"></div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
</div>
*/

$('one').nextSiblings(); // -> [div#two, div#three]
$('one').nextSiblings('#three'); // -> [div#three]

top ↑observes

observes(Function listener) -> boolean
observes(String name, Function listener) -> boolean

Description

Checks if the given listener observers the element events. You can do either a general check or against a specific event name.

Example

var func = function() {};

element.on('click', func);

element.observes(func); // -> true
element.observes('mouseover', func); // -> false

top ↑on

on(String eventName, Function listener) -> Element self
on(String eventName, String method[, argument,...]) -> Element self
on(String eventName, Array list_list_of_callbacks) -> Element self
on(Object event_listeners_hash) -> Element self

Description

Binds an event listener to the element.

Example

$('element').on('click', function() {
// do something about it
});

$('element').on('click', 'addClass', 'clicked');

$('element').on('click', [function1, function2]);

$('element').on({
click: function1,
dblclick: function2
});

top ↑parent

parent([String css_rule]) -> Element parent or null

Description

Selects the parent element. The first one if there is no CSS rule or the first one that matches the rule.

Example

/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/

$('three').parent(); // -> div#two
$('three').parent('#one'); // -> div#one

top ↑parents

parents([String css_rule]) -> Array of elements

Description

Returns the list of parent nodes of the element (from bottom up). If a CSS rule was specified, the list will be filtered by that rule

Example

/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/

$('three').parents(); // -> [div#two, div#one]
$('three').parents('#one'); // -> [div#one]

top ↑position

position() -> Object {x: NN , y: NN }

Description

Returns the absolute position of the element on the page.

Example

var top = $('element').position().y;
var left = $('element').position().x;

top ↑prev

prev([String css_rule]) -> Element or null

Description

Returns the previous sibling of the element or if a CSS rule is specified the previous sibling that matches the rule.

Example

/*
<div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
</div>
*/

$('three').prev(); // -> div#two
$('three').prev('#one'); // -> div#one

top ↑prevSiblings

prevSiblings([String css_rule]) -> Array of elements

Description

Returns the element previous siblings. Optionally filtered out by the given css-rule.

Example

/*
<div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
<div id="some"></div>
</div>
*/

$('three').nextSiblings(); // -> [div#two, div#one]
$('three').nextSiblings('#one'); // -> [div#one]

top ↑radio

radio([String effect[, Object options]]) -> Element self

Description

Hides all the sibling elements and shows itself. If a valid effect name was specified, the effect will be used to perform the showing.

Example

$('some-element').radio();

$('some-element').radio('slide');
$('some-element').radio('slide', {duration: 'long'});

top ↑radioClass

radioClass(String name) -> Element self

Description

Removes the CSS class name from all siblings of the element and adds it to the element.

Example

$('element').radioClass('boo');

top ↑remove

remove() -> Element self

Description

Removes the element from its parent element.

Example

$('some-element').remove();

top ↑removeClass

removeClass(String name) -> Element self

Description

Removes the given CSS class name from the element class names list.

Example

var element = document.getElementById('element');
element.className = 'foo bar';

$(element).removeClass('bar');

element.className; // -> 'foo'

top ↑replace

replace(mixed content) -> Element self

Description

Replaces the current element with the given content.

Example

// <div id="one"><div id="two"></div></div>

$('two').replace('boo boo boo');
$('one').html() === 'boo boo boo';

top ↑resize

resize(number width, number height) -> Element self
resize({x: number, y: number}) -> Element self

Description

Sets the size of the element.

NOTE: This method will automatically adjust the actual style for existing paddings and borders so the end result will be exactly as requested.

Example

var element = new Element('div', {
style: {
border: '10px solid gray',
padding: '10px'
}
});

element.resize(100, 100);

element._.offsetHeight; // -> 100
element._.offsetWidth; // -> 100
element._.style.width; // -> 80px
element._.style.height; // -> 80px

top ↑scrollThere

scrollThere() -> Element self

Description

Scrolls the window to the element.

Example

element.scrollThere();

top ↑scrollTo

scrollTo(number left, number top) -> Element self
scrollTo({x: number, y: number}) -> Element self

Description

Sets the scrolling position of the element.

Example

element.scrollTo(100, 100);
element.scrollTo({x: 100, y: 100});

top ↑scrolls

scrolls() -> Object {x: NN , y: NN }

Description

Returns the scroll values of the element in a hash.

Example

var scroll_top = $('element').scrolls().y;
var scroll_left = $('element').scrolls().x;

top ↑set

set(String name, String value) -> Element self
set(Object properties_hash) -> Element self

Description

Assigns the given attribute(s) to the element.

Example

$('element').set('title', 'some title');

$('element').set({
title: 'some title',
id: 'some-id'
});

top ↑setClass

setClass(String name) -> Element self

Description

Replaces all the element CSS class names with the given one.

Example

var element = document.getElementById('element');
element.className = 'foo bar';

$(element).setClass('boo');

element.className; // -> 'boo'

top ↑setHeight

setHeight(number pixels) -> Element self

Description

Sets the height of the element to the given size.

NOTE: This method will automatically adjust the actual style.height for existing paddings and borders so the end result will be exactly as requested.

Example

var element = new Element('div', {
style: {
border: '10px solid gray',
padding: '10px'
}
});

element.setWidth(100);

element._.offsetWidth; // -> 100
element._.style.width; // -> 80px

top ↑setStyle

setStyle(String key, String value) -> Element self
setStyle(Object styles) -> Element self
setStyle(String styles_def) -> Element self

Description

Assigns a style to the element.

Example

$('element').setStyle('display', 'block');

$('element').setStyle({
display: 'block',
border: '1px solid gray'
});

$('element').setStyle('display:block;color:red');

top ↑setWidth

setWidth(number pixels) -> Element self

Description

Sets the element width to the given size.

NOTE: This method will automatically adjust the actual style.width for existing paddings and borders so the end result will be exactly as requested.

Example

var element = new Element('div', {
style: {
border: '10px solid gray',
padding: '10px'
}
});

element.setWidth(100);

element._.offsetWidth; // -> 100
element._.style.width; // -> 80px

top ↑show

show([String effect[, Object options]]) -> Element self

Description

Shows (un-hides) the element. If a valid effect name was specified and the Fx module is available, the effect will be used to perform the showing.

Example

$('some-element').show();

$('some-element').show('slide');
$('some-element').show('slide', {duration: 'long'});

top ↑siblings

siblings([String css_rule]) -> Array of eleemnts

Description

Returns a list of the siblings, optionally filtered by the given CSS rule.

Example

/*
<div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
</div>
*/

$('two').siblings(); // -> [div#one, div#three]
$('two').siblings('#one'); // -> [div#one]

top ↑size

size() -> Object {x: NN , y: NN}

Description

Returns the element sizes hash.

Example

var width = $('element').size().x;
var height = $('element').size().y;

top ↑stop

stop() -> Element self

Description

Immediately stops and cancels all active visual effects on the element

Example

$('element').slide().fade().stop();

top ↑stopObserving

stopObserving(Function listener) -> Element self
stopObserving(String name[, listener]) -> Element self

Description

Unsubscribes the event listener. This can be done globally for a particular event name, for some particular listener or for some particular listener and event name.

Example

var listener = function() {};

$('element').on('click', listener);

$('element').stopObserving('click');

$('element').stopObserving(listner);

$('element').stopObserving('click', listner);

top ↑text

text() -> String innerHTML without tags
test(String content) -> Element self

Description

A bidirectional method to work with element’s innerHTML property as text

Example

$('element').text('<b>boo hoo!</b>');
$('element').html(); // -> '<b>boo hoo!</b>'

$('element').html('<b>boo hoo!</b>');
$('element').text(); // -> 'boo hoo!'

top ↑toggle

toggle([String effect[, Object options]]) -> Element self

Description

Toggles the element’s visibility status. If a valid effect name was specified, the effect will be used to perform the toggling.

Example

$('some-element').toggle();

$('some-element').toggle('slide');
$('some-element').toggle('slide', {duration: 'long'});

top ↑toggleClass

toggleClass(String name) -> Element self

Description

Toggles the CSS class name presence on the element class names list.

Example

var element = document.getElementById('element');
element.className = 'foo';

$(element).toggleClass('bar')
element.className; // -> 'foo bar';

$(element).toggleClass('bar')
element.className; // -> 'foo';

top ↑undelegate

undelegate(String event[, String css_rule[, Function callback]]) -> Element
undelegate(String event[, Object rules_and_callback]) -> Element

Description

Switches off events delegation attached by the delegate method.

Example

$(element).undelegate('click');
$(element).undelegate('click', 'div.blue');
$(element).undelegate('click', 'div.blue', callback);

$(element).undelegate('click', {
'div.red': callback_1,
'div.blue': callback_2
});

top ↑update

update(mixed content) -> Element self

Description

Replaces the internal structure of the element with the given content.

NOTE: All scripts will be evaluated after the update.

Example

// <div id="one">foo bar</div>

$('one').update('something else');

$('one').html() === 'something else';

top ↑visible

visible() -> boolean

Description

Checks if the element is visible. See the hidden method for more details.

Example

$('some-element').visible();

top ↑win

win() -> Window window

Description

Returns a wrapped Window object to which this element belongs to

Example

$(element).win().size();

top ↑wrap

wrap(Element wrapper) -> Element self

Description

Wraps the current element with the given one.

Example

// <div id="one"><div id="two"></div></div>

$('two').wrap(new Element('div', {id: 'three'}));

$('one').html() == '<div id="three"><div id="two"></div></div>';