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.

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.