The DOM element unit in RightJS is called Element and it handles all the DOM element extensions.
If you use RightJS’ own methods and functions to navigate around elements, all the extensions on selected elements will be available automatically and immediately.
The only exceptions are cases when you take an element from outside the RightJS stack, say you assign an event handler directly in an element attribute or you receive a DOM element that was found by another script. In these cases you need to call the $() function on those elements at least once to make all the additional methods available.
All the set-methods in RightJS return a reference to the object they belong to, this way you can easily create chains of calls like:
$('some-element').on("click", function() {})
.setStyle({fontSize: '200%'})
.addClass('marked').update('with text')
.toggle().set('title', 'some-title') ...;
There are a number of methods like parents, siblings and so on to help you navigate in the neighborhood of an element. All the methods can be used as are, or they can receive an optional CSS selector rule which will filter the result.
var element = $('some-element');
element.siblings(); // all the siblings
element.siblings('div'); // all the siblings with tag 'div'
NOTE: RightJS doesn’t use any special interfaces to process node lists but uses simple Array instances. And as they support calls by name, you can take advantage of this working with DOM elements:
$('some-list').select('li')
.filter('hasClass', 'marked')
.each('onClick', function() {...});
The Element unit has all the standard Observer unit interface and handles events binding in the same exact way.
$('some-element').on('click', function() {
call_that_function();
});
$('another-element').on({
click: click_handler,
mouseover: mouseover_handler,
mouseout: mouseout_handler
});
$('that-element').on('click', [
function1, function2, function3
]);
There are also shortcuts for all the standard DOM events. And you can use the name references for callbacks as well:
$('element').onClick('addClass', 'marked');
Finally, you can trigger any event handler manually like this:
element.onClick('addClass', 'clicked');
element.onKeypress('radioClass', 'typing');
element.fire('click', { button: 3 });
element.fire('keypress', { keyCode: 12 });
At the interface level, there is no difference between standard and custom events in RightJS. All of them are handled the exact same way:
element.on('my-event', function() {....});
element.fire('my-event');
include, initialize, addClass, clean, dimensions, empty, erase, first, get, getStyle, has, hasClass, hidden, hide, insert, insertTo, listeners, load, match, moveTo, next, nextSiblings, observe, observes, on, parent, parents, position, prev, prevSiblings, radio, radioClass, remove, removeClass, replace, resize, scrollThere, scrollTo, scrolls, select, set, setClass, setHeight, setStyle, setWidth, show, siblings, sizes, stop, stopObserving, subNodes, toggle, toggleClass, update, visible, wrap
Element.include(Object methods[, boolean don_rewrite])
Registers additional methods for the DOM elements on the page.
Element.include({
myMethod: function() {....}
});
$('my_element').myMethod();
initialize(String tag_name[, Object options]) -> Element new
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:
Everything will be handled in one flow.
var element = new Element(
'div');
var element = new Element('p', {
id: 'some-paragraph',
'class': 'come class',
style: {
padding: '10pt'
},
observe: {
mouseover: function() { ... }
}
});
addClass(String name) -> Element self
Adds the given CSS class name to the element class names list.
element.className =
'foo';
element.addClass('bar');
element.className; // -> 'foo bar'
clean() -> Element self
Removes all child nodes from the element.
$(
'element').clean();
dimensions() -> Object
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.
$(
'element').dimensions();
empty() -> boolean
Checks if the element has no internal text or elements.
$(
'element').empty();
erase(String name) -> Element self
Erases the attribute with the given name from an element.
// <div id="div" title="some title"></div>
$('div').has('title'); // -> true
$('div').erase('title');
$('div').has('title'); // -> false
first(String css_rule) -> Element or null
Returns the first node in the internal structure that matches the given CSS rule.
/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/
$('one').first('div'); // -> div#two
$('one').first('#three'); // -> div#three
get(String name) -> String value or null if empty
Reads an element attribute. Returns null if the attribute is not set.
// <div id="div" title="some title"></div>
$('div').get('title'); // -> 'some title'
getStyle(String name) -> String value or null
Requests the element style by name. Supports both camelized and dasherized names.
NOTE: Checks both element styles as well as the computed (CSS) styles.
$(
'element').hide();
$('element').getStyle('dispaly'); // -> 'none'
has(String name) -> boolean
Checks if an element has a non-empty attribute with that name.
// <div id="div" title="some title"></div>
$('div').has('title'); // -> true
$('div').has('rel'); // -> false
hasClass(String class) -> boolean
Checks if the element is assigned to the given CSS class name.
var element = $(
'element');
element.className = 'foo bar';
element.hasClass('foo'); // -> true
element.hasClass('bar'); // -> true
element.hasClass('boo'); // -> false
hidden() -> boolean
Checks if the element has style ‘display’ set to ‘none’.
NOTE: Checks both element styles as well as the computed (CSS) styles.
/*
<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
hide([String effect[, Object options]]) -> Element self
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.
$(
'some-element').hide();
$('some-element').hide('slide');
$('some-element').hide('slide', {duration: 'long'});
insert(mixed content[, String position]) -> Element self
Inserts the given content into the element at the given position.
The content can be one of the following:
Position can be one of the following: top / bottom / before / after / instead
The bottom value is used by default.
var element = $(
'some-element');
element.insert(new Element('div', {html: 'new-div'}));
element.insert(new Element('div'), 'top');
element.insert([element1, element2, element3], 'before');
element.insert({
before: element1,
after: element2,
top: element3
});
insertTo(Element destination[, String position]) -> Element self
Inserts the current element into the given one, optionally at the given position.
var element1 = $(
'element1');
var element2 = $('element2');
element1.insertTo(element2, 'top');
element2.firstChild === element1;
listeners() -> Array of functions
listeners(String name) -> Array of functions
Returns a list of element event listeners which can optionally be narrowed down by an event name scope.
var func = function() {};
element.on('click', func);
element.listeners(); // -> [func]
element.listeners('click'); // -> [func]
element.listeners('mouseover'); // -> []
load(String url[, Object options]) -> Element self
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.
element.load(
'/something');
element.load('/something', {
method: 'post',
spinner: 'spinner-id'
});
match(String css_rule) -> boolean
Checks if the element matches the given CSS rule.
// <div id="some-element"></div>
$('some-element').match('div'); // -> true
$('some-element').match('span'); // -> false
moveTo(number left, number top) -> Element self
moveTo({x: number, y: number}) -> Element self
Move the element to the given position.
element.moveTo(
100, 100);
element.moveTo({x: 100, y: 100});
next([String css_rule]) -> Element or null
Returns the next sibling of the element or if a CSS rule is specified the next sibling that matches the rule.
/*
<div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
</div>
*/
$('one').next(); // -> div#two
$('one').next('#three'); // -> div#three
nextSiblings([String css_rule]) -> Array of elements
Collects later siblings of the element, optionally filtered by the given CSS rule.
/*
<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]
observe(String eventName, Function listener) -> Element self
observe(String eventName, String method[, argument,...]) -> Element self
observe(String eventName, Array list_list_of_callbacks) -> Element self
observe(Object event_listeners_hash) -> Element self
Binds an event listener to the element.
DEPRECATED: Use the on method instead.
$(
'element').observe('click', function() {
// do something about it
});
$('element').observe('click', 'addClass', 'clicked');
$('element').observe('click', [function1, function2]);
$('element').observe({
click: function1,
dblclick: function2
});
observes(Function listener) -> boolean
observes(String name, Function listener) -> boolean
Checks if the given listener observers the element events. You can do either a general check or against a specific event name.
var func = function() {};
element.on('click', func);
element.observes(func); // -> true
element.observes('mouseover', func); // -> false
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
Binds an event listener to the element.
$(
'element').on('click', function() {
// do something about it
});
$('element').on('click', 'addClass', 'clicked');
$('element').on('click', [function1, function2]);
$('element').on({
click: function1,
dblclick: function2
});
parent([String css_rule]) -> Element parent or null
Selects the parent element. The first one if there is no CSS rule or the first one that matches the rule.
/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/
$('three').parent(); // -> div#two
$('three').parent('#one'); // -> div#one
parents([String css_rule]) -> Array of elements
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
/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/
$('three').parents(); // -> [div#two, div#one]
$('three').parents('#one'); // -> [div#one]
position() -> Object {
x: NN , y: NN }
Returns the absolute position of the element on the page.
var top = $(
'element').position().y;
var left = $('element').position().x;
prev([String css_rule]) -> Element or null
Returns the previous sibling of the element or if a CSS rule is specified the previous sibling that matches the rule.
/*
<div>
<div id="one"></div>
<div id="two"></div>
<div id="three"></div>
</div>
*/
$('three').prev(); // -> div#two
$('three').prev('#one'); // -> div#one
prevSiblings([String css_rule]) -> Array of elements
Returns the element previous siblings. Optionally filtered out by the given css-rule.
/*
<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]
radio([String effect[, Object options]]) -> Element self
Hides all the sibling elements and shows itself. If a valid effect name was specified, the effect will be used to perform the showing.
$(
'some-element').radio();
$('some-element').radio('slide');
$('some-element').radio('slide', {duration: 'long'});
radioClass(String name) -> Element self
Removes the CSS class name from all siblings of the element and adds it to the element.
$(
'element').radioClass('boo');
remove() -> Element self
Removes the element from its parent element.
$(
'some-element').remove();
removeClass(String name) -> Element self
Removes the given CSS class name from the element class names list.
element.className =
'foo bar';
element.removeClass('bar');
element.className; // -> 'foo'
replace(mixed content) -> Element self
Replaces the current element with the given content.
// <div id="one"><div id="two"></div></div>
$('two').replace('boo boo boo');
$('one').innerHTML == 'boo boo boo';
resize(number width, number height) -> Element self
resize({x: number, y: number}) -> Element self
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.
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
scrollThere() -> Element self
Scrolls the window to the element.
element.scrollThere();
scrollTo(number left, number top) -> Element self
scrollTo({x: number, y: number}) -> Element self
Sets the scrolling position of the element.
element.scrollTo(
100, 100);
element.scrollTo({x: 100, y: 100});
scrolls() -> Object {
x: NN , y: NN }
Returns the scroll values of the element in a hash.
var scroll_top = $(
'element').scrolls().y;
var scroll_left = $('element').scrolls().x;
select(String css_rule) -> Array of elements
Selects all matching elements from the internal structure of the element.
/*
<div id="one">
<div id="two">
<div id="three"></div>
</div>
</div>
*/
$('one').select('div'); // -> [div#two, div#three]
$('one').select('#three'); // -> [div#three]
set(String name, String value) -> Element self
set(Object properties_hash) -> Element self
Assigns the given attribute(s) to the element.
$(
'element').set('title', 'some title');
$('element').set({
title: 'some title',
id: 'some-id'
});
setClass(String name) -> Element self
Replaces all the element CSS class names with the given one.
element.className =
'foo bar';
element.setClass('boo');
element.className; // -> 'boo'
setHeight(number pixels) -> Element self
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.
var element = new Element(
'div', {
style: {
border: '10px solid gray',
padding: '10px'
}
});
element.setWidth(100);
element.offsetWidth; // -> 100
element.style.width; // -> 80px
setStyle(String key, String value) -> Element self
setStyle(Object styles) -> Element self
setStyle(String styles_def) -> Element self
Assigns a style to the element.
$(
'element').setStyle('display', 'block');
$('element').setStyle({
display: 'block',
border: '1px solid gray'
});
$('element').setStyle('display:block;color:red');
setWidth(number pixels) -> Element self
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.
var element = new Element(
'div', {
style: {
border: '10px solid gray',
padding: '10px'
}
});
element.setWidth(100);
element.offsetWidth; // -> 100
element.style.width; // -> 80px
show([String effect[, Object options]]) -> Element self
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.
$(
'some-element').show();
$('some-element').show('slide');
$('some-element').show('slide', {duration: 'long'});
siblings([String css_rule]) -> Array of eleemnts
Returns a list of the siblings, optionally filtered by the given CSS rule.
/*
<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]
sizes() -> Object {
x: NN , y: NN}
Returns the element sizes hash.
var width = $(
'element').sizes().x;
var height = $('element').sizes().y;
stop() -> Element self
Immediately stops and cancels all active visual effects on the element
$(
'element').slide().fade().stop();
stopObserving(String name) -> Element self
stopObserving(Function listener) -> Element self
stopObserving(String name, listener) -> Element self
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.
var listener = function() {};
$('element').on('click', listener);
$('element').stopObserving('click');
$('element').stopObserving(listner);
$('element').stopObserving('click', listner);
subNodes([String css_rule]) -> Array of elements
Returns a list of the immediate descendants from the element, optionally filtered by the given CSS rule.
/*
<div id="one">
<div id="two"></div>
<div id="three"></div>
</div>
*/
$('one').subNodes(); // -> [div#two, div#three]
$('one').subNodes('#two'); // -> [div#two]
toggle([String effect[, Object options]]) -> Element self
Toggles the element’s visibility status. If a valid effect name was specified, the effect will be used to perform the toggling.
$(
'some-element').toggle();
$('some-element').toggle('slide');
$('some-element').toggle('slide', {duration: 'long'});
toggleClass(String name) -> Element self
Toggles the CSS class name presence on the element class names list.
element.className =
'foo';
element.toggleClass('bar')
element.className; // -> 'foo bar';
element.toggleClass('bar')
element.className; // -> 'foo';
update(mixed content) -> Element self
Replaces the internal structure of the element with the given content.
NOTE: All scripts will be evaluated after the update.
// <div id="one">foo bar</div>
$('one').update('something else');
$('one').innerHTML == 'something else';