PrototypeElementFunctions
These functions make it easier for manipulating Dom Elements
Created by: Will, Last modification: 27 Dec 2005 (18:09 UTC)
The following are objects and functions of the Prototype library that simplify the tricky code that is involved in manipulating Dom Elements, such as text, divs, forms, fields, etc.
These functions are great for changing text on a page, monitoring changes made to forms, and adding and removing addition page parts.
Also see the PrototypeUtilityFunctions, some of which are handy to use when manipulating Elements.
This object provides some utility functions for manipulating elements in the DOM.
This object serves as the root for other classes in the library. It does not have any properties or methods. The classes defined in this object are also treated as traditional abstract classes.
This class is used as the base class for the other classes that will provide dynamic content insertion. This class is used like an abstract class.
This object serves as the root for other classes in the library. It does not have any properties or methods. The classes defined in this object are also treated as traditional abstract classes.
Inherits from Abstract.Insertion
Inserts HTML before an element.
The following code
Will change the HTML to
Inherits from Abstract.Insertion
Inserts HTML as the first child under an element. The content will be right after the opening tag of the element.
The following code
Will change the HTML to
Inherits from Abstract.Insertion
Inserts HTML as the last child under an element. The content will be right before the element's closing tag.
The following code
Will change the HTML to
Inherits from Abstract.Insertion
Inserts HTML right after the element's closing tag.
The following code
Will change the HTML to
This object provides a host of functions that help when working with element positioning.
This object provides some utility functions for working with input fields in forms.
This object provides some utility functions for working with data entry forms and their input fields.
This object provides some utility functions for working with form elements, visible or not.
This object provides some utility functions that are used internally in the library to assist extracting the current value of the form elements.
This class is used as the base class for the other classes that will monitor one element until its value (or whatever property the derived class defines) changes. This class is used like an abstract class.
Subclasses can be created to monitor things like the input value of an element, or one of the style properties, or number of rows in a table, or whatever else you may be interested in tracking changes to.
||Method | Kind | Arguments | Description
ctor(element, frequency, callback) | constructor | element: element object or id, frequency: interval in seconds, callback: function to be called when the element changes | Creates an object that will monitor the element.
These functions are great for changing text on a page, monitoring changes made to forms, and adding and removing addition page parts.
Also see the PrototypeUtilityFunctions, some of which are handy to use when manipulating Elements.
HTML and Basic Element Manipulation
The Element object
This object provides some utility functions for manipulating elements in the DOM.
Method | Kind | Arguments | Description |
toggle(elem1 [, elem2 [, elem3 ...]]) | instance | elemN: element object or id | Toggles the visibility of each passed element. |
hide(elem1 [, elem2 [, elem3 ...]]) | instance | elemN: element object or id | Hides each element by setting its style.display to 'none'. |
show(elem1 [, elem2 [, elem3 ...]]) | instance | elemN: element object or id | Shows each element by resetting its style.display to ''. |
remove(element) | instance | element: element object or id | Removes the element from the document. |
getHeight(element) | instance | element: element object or id | Returns the offsetHeight of the element |
addClassName(element, className) | instance | element: element object or id, className: name of a CSS class | Adds the given class name to the element's class names. |
hasClassName(element, className) | instance | element: element object or id, className: name of a CSS class | Returns true if the element has the given class name as one of its class names. |
removeClassName(element, className) | instance | element: element object or id, className: name of a CSS class | Removes the given class name from the element's class names. |
cleanWhitespace(element) | instance | element: element object or id | Removes any white space text node children of the element |
The Abstract object
This object serves as the root for other classes in the library. It does not have any properties or methods. The classes defined in this object are also treated as traditional abstract classes.
The Abstract.Insertion class
This class is used as the base class for the other classes that will provide dynamic content insertion. This class is used like an abstract class.
Method | Kind | Arguments | Description |
ctor(element, content) | constructor | element: element object or id, content: HTML to be inserted | Creates an object that will help with dynamic content insertion. |
Property | Type | Kind | Description |
adjacency | String | static, parameter | Parameter that specifies where the content will be placed relative to the given element. The possible values are: 'beforeBegin', 'afterBegin', 'beforeEnd', and 'afterEnd'. |
element | Object | instance | The element object that the insertion will be made relative to. |
content | String | instance | The HTML that will be inserted. |
The Insertion object
This object serves as the root for other classes in the library. It does not have any properties or methods. The classes defined in this object are also treated as traditional abstract classes.
The Insertion.Before class
Inherits from Abstract.Insertion
Inserts HTML before an element.
Method | Kind | Arguments | Description |
ctor(element, content) | constructor | element: element object or id, content: HTML to be inserted | Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion. |
The following code
<br>Hello, <span id="person" style="color:red;">Wiggum. How is it going?</span>
<script> new Insertion.Before('person', 'Chief '); </script>
Will change the HTML to
<br>Hello, Chief <span id="person" style="color:red;">Wiggum. How is it going?</span>
The Insertion.Top class
Inherits from Abstract.Insertion
Inserts HTML as the first child under an element. The content will be right after the opening tag of the element.
Method | Kind | Arguments | Description |
ctor(element, content) | constructor | element: element object or id, content: HTML to be inserted | Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion. |
The following code
<br>Hello, <span id="person" style="color:red;">Wiggum. How is it going?</span>
<script> new Insertion.Before('person', 'Mr. '); </script>
Will change the HTML to
<br>Hello, <span id="person" style="color:red;">Mr. Wiggum. How is it going?</span>
The Insertion.Bottom class
Inherits from Abstract.Insertion
Inserts HTML as the last child under an element. The content will be right before the element's closing tag.
Method | Kind | Arguments | Description |
ctor(element, content) | constructor | element: element object or id, content: HTML to be inserted | Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion. |
The following code
<br>Hello, <span id="person" style="color:red;">Wiggum. How is it going?</span>
<script> new Insertion.Before('person', ' What's up?'); </script>
Will change the HTML to
<br>Hello, <span id="person" style="color:red;">Wiggum. How is it going? What's up?</span>
The Insertion.After class
Inherits from Abstract.Insertion
Inserts HTML right after the element's closing tag.
Method | Kind | Arguments | Description |
ctor(element, content) | constructor | element: element object or id, content: HTML to be inserted | Inherited from Abstract.Insertion. Creates an object that will help with dynamic content insertion. |
The following code
<br>Hello, <span id="person" style="color:red;">Wiggum. How is it going?</span>
<script> new Insertion.Before('person', ' Are you there?'); </script>
Will change the HTML to
<br>Hello, <span id="person" style="color:red;">Wiggum. How is it going?</span> Are you there?
The Position object (preliminary documentation)
This object provides a host of functions that help when working with element positioning.
Method | Kind | Arguments | Description |
prepare() | instance | (none) | Adjusts the deltaX and deltaY properties to accommodate changes in the scroll position. Remember to call this method before any calls to withinIncludingScrolloffset after the page scrolls. |
realOffset(element) | instance | element: object | Returns an Array with the correct scroll offsets of the element, including any scroll offsets that affect the element. The resulting array is similar to total_scroll_left, total_scroll_top |
cumulativeOffset(element) | instance | element: object | Returns an Array with the correct positioning offsets of the element, including any offsets that are imposed by positioned parent elements. The resulting array is similar to total_offset_left, total_offset_top |
within(element, x, y) | instance | element: object, x and y: coordinates of a point | Tests if the given point coordinates are inside the bounding rectangle of the given element |
withinIncludingScrolloffsets(element, x, y) | instance | element: object, x and y: coordinates of a point | |
overlap(mode, element) | instance | mode: 'vertical' or 'horizontal', element: object | within() needs to be called right before calling this method. This method will return a decimal number between 0.0 and 1.0 representing the fraction of the coordinate that overlaps on the element. As an example, if the element is a square DIV with a 100px side and positioned at (300, 300), then within(divSquare, 330, 330); overlap('vertical', divSquare); should return 0.10, meaning that the point is at the 10% (30px) mark from the top border of the DIV. |
clone(source, target) | instance | source: element object or id, target: element object or id | Resizes and repositions the target element identically to the source element. |
Form and Field Element Manipulation
The Field object
This object provides some utility functions for working with input fields in forms.
Method | Kind | Arguments | Description |
clear(field1 [, field2 [, field3 ...]]) | instance | fieldN: field element object or id | Clears the value of each passed form field element. |
present(field1 [, field2 [, field3 ...]]) | instance | fieldN: field element object or id | Returns true only if all forms fields contain non-empty values. |
focus(field) | instance | field: field element object or id | Moves the input focus to the given form field. |
select(field) | instance | field: field element object or id | Selects the value in fields that support text selection |
activate(field) | instance | field: field element object or id | Move the focus and selects the value in fields that support text selection |
The Form object
This object provides some utility functions for working with data entry forms and their input fields.
Method | Kind | Arguments | Description |
serialize(form) | instance | form: form element object or id | Returns a url-formatted list of field names and their values, like 'field1=value1&field2=value2&field3=value3' |
getElements(form) | instance | form: form element object or id | Returns an Array containing all the input fields in the form. |
getInputs(form [, typeName , name]) | instance | form: form element object or id, typeName: the type of the input element, name: the name of the input element. | Returns an Array containing all the <input> elements in the form. Optionally, the list can be filtered by the type or name attributes of the elements. |
disable(form) | instance | form: form element object or id | Disables all the input fields in the form. |
enable(form) | instance | form: form element object or id | Enables all the input fields in the form. |
focusFirstElement(form) | instance | form: form element object or id | Activates the first visible, enabled input field in the form. |
reset(form) | instance | form: form element object or id | Resets the form. The same as calling the reset() method of the form object. |
The Form.Element object
This object provides some utility functions for working with form elements, visible or not.
Method | Kind | Arguments | Description |
serialize(element) | instance | element: element object or id | Returns the element's name=value pair, like 'elementName=elementValue' |
getValue(element) | instance | element: element object or id | Returns the value of the element. |
The Form.Element.Serializers object
This object provides some utility functions that are used internally in the library to assist extracting the current value of the form elements.
Method | Kind | Arguments | Description |
inputSelector(element) | instance | element: object or id of a form element that has the checked property, like a radio button or checkbox. | Returns an Array with the element's name and value, like elementName', 'elementValue>'elementName', 'elementValue' |
textarea(element) | instance | element: object or id of a form element that has the value property, like a textbox, button or password field. | Returns an Array with the element's name and value, like elementName', 'elementValue>'elementName', 'elementValue' |
select(element) | instance | element: object or id of a <select> element | Returns an Array with the element's name and all selected options' values or texts, like elementName', 'selOpt1 selOpt4 selOpt9>'elementName', 'selOpt1 selOpt4 selOpt9' |
Element Listening
The Abstract.TimedObserver class
This class is used as the base class for the other classes that will monitor one element until its value (or whatever property the derived class defines) changes. This class is used like an abstract class.
Subclasses can be created to monitor things like the input value of an element, or one of the style properties, or number of rows in a table, or whatever else you may be interested in tracking changes to.
||Method | Kind | Arguments | Description
ctor(element, frequency, callback) | constructor | element: element object or id, frequency: interval in seconds, callback: function to be called when the element changes | Creates an object that will monitor the element.