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



Will change the HTML to

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



Will change the HTML to

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



Will change the HTML to

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



Will change the HTML to

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.
<tr class="privateMember> <td>getValue()</td><td>instance, abstract</td> <td>(none)</td> <td class="refDescription">Derived classes have to implement this method to determine what is the current value being monitored in the element.
registerCallback()	instance	(none)	This method is typically not called externally. It is called by the object itself to start monitoring the element.
onTimerEvent()	instance	(none)	This method is typically not called externally. It is called by the object itself periodically to check the element.

Property	Type	Description
element	Object	The element object that is being monitored.
frequency	Number	This is actually the interval in seconds between checks.
callback	Function(Object, String)	The function to be called whenever the element changes. It will receive the element object and the new value.
lastValue	String	The last value verified in the element.

The Form.Element.Observer class

Inherits from Abstract.TimedObserver

Implementation of an Abstract.TimedObserver that monitors the value of form input elements. Use this class when you want to monitor an element that does not expose an event that reports the value changes. In that case you can use the Form.Element.EventObserver class instead.

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	Inherited from Abstract.TimedObserver. Creates an object that will monitor the element's value property.
getValue()	instance	(none)	Returns the element's value.

The Form.Observer class

Inherits from Abstract.TimedObserver

Implementation of an Abstract.TimedObserver that monitors any changes to any data entry element's value in a form. Use this class when you want to monitor a form that contais a elements that do not expose an event that reports the value changes. In that case you can use the Form.EventObserver class instead.

Method	Kind	Arguments	Description
ctor(form, frequency, callback)	constructor	form: form object or id, frequency: interval in seconds, callback function to be called when any data entry element in the form changes	Inherited from Abstract.TimedObserver. Creates an object that will monitor the form for changes.
getValue()	instance	(none)	Returns the serialization of all form's data.

The Abstract.EventObserver class

This class is used as the base class for the other classes that execute a callback function whenever a value-changing event happens for an element.

Multiple objects of type Abstract.EventObserver can be bound to the same element, without one wiping out the other. The callbacks will be executed in the order they are assigned to the element.

The triggering event is onclick for radio buttons and checkboxes, and onchange for textboxes in general and listboxes/dropdowns.

Method	Kind	Arguments	Description
ctor(element, callback)	constructor	element: element object or id, callback: function to be called when the event happens	Creates an object that will monitor the element.
<tr class="privateMember> <td>getValue()</td><td>instance, abstract</td> <td>(none)</td> <td class="refDescription">Derived classes have to implement this method to determine what is the current value being monitored in the element.
registerCallback()	instance	(none)	This method is typically not called externally. It is called by the object to bind itself to the element's event.
registerFormCallbacks()	instance	(none)	This method is typically not called externally. It is called by the object to bind itself to the events of each data entry element in the form.
onElementEvent()	instance	(none)	This method is typically not called externally. It will be bound to the element's event.

Property	Type	Description
element	Object	The element object that is being monitored.
callback	Function(Object, String)	The function to be called whenever the element changes. It will receive the element object and the new value.
lastValue	String	The last value verified in the element.

The Form.Element.EventObserver class

Inherits from Abstract.EventObserver

Implementation of an Abstract.EventObserver that executes a callback function to the appropriate event of the form data entry element to detect value changes in the element. If the element does not expose any event that reports changes, then you can use the Form.Element.Observer class instead.

Method	Kind	Arguments	Description
ctor(element, callback)	constructor	element: element object or id, callback: function to be called when the event happens	Inherited from Abstract.EventObserver. Creates an object that will monitor the element's value property.
getValue()	instance	(none)	Returns the element's value

The Form.EventObserver class

Inherits from Abstract.EventObserver

Implementation of an Abstract.EventObserver that monitors any changes to any data entry element contained in a form, using the elements' events to detect when the value changes. If the form contains elements that do not expose any event that reports changes, then you can use the Form.Observer class instead.

Method	Kind	Arguments	Description
ctor(form, callback)	constructor	form: form object or id, callback: function to be called when any data entry element in the form changes	Inherited from Abstract.EventObserver. Creates an object that will monitor the form for changes.
getValue()	instance	(none)	Returns the serialization of all form's data.