Prototype.js

Dimiter Kunchev

About Prototype Library

JavaScript library written by Sam Stephenson http://prototypejs.org

Adds object oriented techniques

Provides many utility functions

Extends JavaScript methods and objects

Hides cross-browser problems

Simplifies developing of heavy web applications

Utility Functions $() – literal form for

document.getElementById

Returns reference to the element with that ID

If specified multiple arguments, returns an array with the corresponding elements

$F() – returns the value of input form field

Works with text boxes, check boxes, radio buttons, buttons, etc

var myDiv = $('myDiv');var myDiv = $('myDiv');

var inputValue = $F('myInput');var inputValue = $F('myInput');

Utility Functions $$() – returns elements matching the given CSS filter rule

Try.these – takes multiple function calls as arguments and returns the value of the first that worked

var arr = $$('div#login_form input');var arr = $$('div#login_form input');

Try.these (function () {return XMLNode.text},function () {return XMLNode.textContent}

);

Try.these (function () {return XMLNode.text},function () {return XMLNode.textContent}

);

Utility Functions

$A() – converts it's single argument into an Array object

Extends the array with some usefl

methods

$H() – converts it's argument into an enumerable hash object

Also adds some methods

var arr = $A(["a", "b", "c"]);arr.each(function(elem) {alert (elem);});

var arr = $A(["a", "b", "c"]);arr.each(function(elem) {alert (elem);});

var obj = $H( {"id":5, name:"test"} );alert (obj.toQueryString()); //produces

id=5&name=test

var obj = $H( {"id":5, name:"test"} );alert (obj.toQueryString()); //produces

id=5&name=test

Function Class Extensions

bindAsEventListener (object, optinal arguments) – returns anonymous function

Can be used to attach object's method as

event handler

The event handler receives the event

object and all arguments passed to the

bindAsEventListener methodthis.btn.onclick =

this.onBtnClick.bindAsEventListener(this, 'btn');…onBtnClick: function (event, some_string) {}

this.btn.onclick = this.onBtnClick.bindAsEventListener(this, 'btn');

…onBtnClick: function (event, some_string) {}

Function Class Extensions

bind – similar to bindAsEventListener

Passes to the method all arguments, specified by the caller and to the bind method

Useful for attaching handlers of Ajax requests and timers

setTimeout(this.onTimer.bind(this, 'timer'), 1000);…onTimer: function (caller) {

// caller will be 'timer'}

setTimeout(this.onTimer.bind(this, 'timer'), 1000);…onTimer: function (caller) {

// caller will be 'timer'}

The Object Object Extensions to the Object object

extend (destination, source) – copies all properties and methods from source object to destination object Used for class inheritance

keys – returns array with the names of all properties and methods of the object

values – returns array with the values of all properties and methods of the object

clone – creates shadow copy of the object

The Ajax Object Prototype.js AJAX classes and methods are capsulated in single object, named Ajax Ajax.Request Ajax.Updater Ajax.PeriodicalUpdater Ajax.Responders

Ajax.Request

Simplifies the use of XMLHttpRequest

Hides browser differences

Object constructor takes two arguments

URL to send the request to

Associative array with optionsnew Ajax.Request ('get-data.html', {

method:"get",onSucccess: showData, // function to handle resultparameters: $H({id:5, kw:'abc'}).toQueryString()

});

new Ajax.Request ('get-data.html', {method:"get",onSucccess: showData, // function to handle resultparameters: $H({id:5, kw:'abc'}).toQueryString()

});

Ajax.Request Options Options that can be passed to the constructor: method: 'get' or 'post'

parameters: string data to append to the URL

New versions of prototype support associative array as parameters

toQueryString is executed

postBody: string – the contents to send over HTTP POST request

Ajax.Request Options onSuccess: function to be called when data is read from server The function takes one parameter –

the XHMLHttpRequest object contentType: string – sets the HTTP Content-Type header of the request

encoding: string – sets the encoding of the request body for POST method By default it is 'UTF-8'

Ajax.Updater

Extension of Ajax.Request Constructor takes one more

parameter – id of element to place the fetched data in

Doesn't need onSuccess handler methodnew Ajax.Updater ( 'result', // element ID 'get-data.html', { method:"get", parameters: $H({id:5,kw:'abc'}). toQueryString() });

new Ajax.Updater ( 'result', // element ID 'get-data.html', { method:"get", parameters: $H({id:5,kw:'abc'}). toQueryString() });

Ajax.PeriodicalUpdater

Extension of Ajax.Updater class Constructor takes the same

arguments as Ajax.Updater one

You can specify the frequency and decay of the requests in the options

new Ajax.PeriodicalUpdater ('result', // element ID'get-data.html', { method:"get",

frequency: 100, decay: 1}

);

new Ajax.PeriodicalUpdater ('result', // element ID'get-data.html', { method:"get",

frequency: 100, decay: 1}

);

Extensions to the DOM API

Prototype.js introduces the Element object Contains methods to work with the

DOM

All methods are also copied as extensions to the element references, accessed by the $() functionElement.show('my_div');

// The above is the same as:

$('my_div').show();

Element.show('my_div');

// The above is the same as:

$('my_div').show();

Element Methods

addClassName(element, className)

Adds the given class name(s) to the className property of the element

removeClassName(element, className)

Respectively removes the class name from the element

ancestors(element)

Returns array with all parent nodes of the element (from the element towards the root)

Element Methods childOf (element, ancestor)

Returns boolean – if the element is descendant of ancestor

desendantOf method is the same

descendants (element) Returns array with all child nodes

(recursively) of the element

getElementsByClassName(element, className) Returns array with all child elements that

have the given className in their classes

The Form Object Methods

serialize(form) – returns url-formated list of field names and their values

Useful for sending the data over Ajax

getElements(form) – returns array with the input fields in the form

disable(form), enable(form) – disable / enable all the inputs in the form

The Event Object Contains methods for working with events element(event) – returns reference

to the element that fired the event

isLeftClick(event) – returns true if the left mouse button was clicked

pointerX(event), pointerY(event) – return the X/Y coordinate of mouse event

stop(event) – abort event execution and stop its propagation

Event Observing Event.observe(element, name, observer,

useCapture) – attach event listener to element

element is id or element reference

name is the event type – "load", "click",

etc.

observer is the function that will handle

the event

useCapture – specify whether to use

capture or bubbling event flow models

Event.stopObserving – remove event handler

Parameters must be exactly the same as

specified in Event.observer