class method Element.addMethods
Element.addMethods(methods) → undefined
Element.addMethods(tagName, methods) → undefined
-
tagName
(String
) – (Optional) The name of the HTML tag for which the methods should be available; if not given, all HTML elements will have the new methods. -
methods
(Object
) – A hash of methods to add.
Element.addMethods
makes it possible to mix your own methods into the
Element
object and extended element instances (all of them, or only ones
with the given HTML tag if you specify tagName
).
You define the methods in a hash that you provide to Element.addMethods
.
Here's an example adding two methods:
Element.addMethods({
// myOwnMethod: Do something cool with the element
myOwnMethod: function(element) {
if (!(element = $(element))) return;
// ...do smething with 'element'...
return element;
},
// wrap: Wrap the element in a new element using the given tag
wrap: function(element, tagName) {
var wrapper;
if (!(element = $(element))) return;
wrapper = new Element(tagName);
element.parentNode.replaceChild(wrapper, element);
wrapper.appendChild(element);
return wrapper;
}
});
Once added, those can be used either via Element
:
// Wrap the element with the ID 'foo' in a div
Element.wrap('foo', 'div');
...or as instance methods of extended elements:
// Wrap the element with the ID 'foo' in a div
$('foo').wrap('div');
Note the following requirements and conventions for methods added to
Element
:
- The first argument is always an element or ID, by convention this
argument is called
element
. - The method passes the
element
argument through$
and typically returns if the result is undefined. - Barring a good reason to return something else, the method returns the extended element to enable chaining.
Our myOwnMethod
method above returns the element because it doesn't have
a good reason to return anything else. Our wrap
method returns the
wrapper, because that makes more sense for that method.
Extending only specific elements
If you call Element.addMethods
with two arguments, it will apply the
methods only to elements with the given HTML tag:
Element.addMethods('DIV', my_div_methods);
// the given methods are now available on DIV elements, but not others
You can also pass an Array
of tag names as the first argument:
Element.addMethods(['DIV', 'SPAN'], my_additional_methods);
// DIV and SPAN now both have the given methods
(Tag names in the first argument are not case sensitive.)
Note: Element.addMethods
has built-in security which prevents you from
overriding native element methods or properties (like getAttribute
or
innerHTML
), but nothing prevents you from overriding one of Prototype's
methods. Prototype uses a lot of its methods internally; overriding its
methods is best avoided or at least done only with great care.
Example 1
Our wrap
method earlier was a complete example. For instance, given this
paragraph:
<p id="first">Some content...</p>
...we might wrap it in a div
:
$('first').wrap('div');
...or perhaps wrap it and apply some style to the div
as well:
$('first').wrap('div').setStyle({
backgroundImage: 'url(images/rounded-corner-top-left.png) top left'
});
Example 2
We can add a method to elements that makes it a bit easier to update them
via Ajax.Updater
:
Element.addMethods({
ajaxUpdate: function(element, url, options) {
if (!(element = $(element))) return;
element.update('<img src="/images/spinner.gif" alt="Loading...">');
options = options || {};
options.onFailure = options.onFailure || defaultFailureHandler.curry(element);
new Ajax.Updater(element, url, options);
return element;
}
});
Now we can update an element via an Ajax call much more concisely than before:
$('foo').ajaxUpdate('/new/content');
That will use Ajax.Updater
to load new content into the 'foo' element,
showing a spinner while the call is in progress. It even applies a default
failure handler (since we didn't supply one).