documentation de la librairie prototype, version 1.4.0 - club d'entraide des développeurs francophones
documentation de la librairie prototype, version 1.4.0 - club d'entraide des développeurs francophones
rechercher:
sur developpez.com
sur les forums
forums | tutoriels | f.a.q's | participez | hébergement | contacts
accueil
tv
conception
java
dotnet
visual basic
c
c++
delphi
pascal
ms-office
sql & sgbd
oracle
4d
club
blogs
emploi
formation
dév. web
php
xml
python
autres
2d-3d-jeux
sécurité
systèmes
windows
linux
accueil javascript
forum javascript
f.a.q javascript
tutoriels javascripts
sources javascript
livres
ajax
documentation de la librairie prototype, version 1.4.0
traduction pour http://www.developpez.com par
spacefrog (steven k. martin),
olivier lance ( accueil )
et denis cabasson ( developpez.com )
du document
developer notes for prototype.js
de sergio pereira.
un grand merci à bisûnûrs pour sa relecture complète de l'article.
date de publication : 24/04/2007 , date de mise à jour : 25/04/2007
par
sergio pereira (sergio pereira)
prototype est une librairie javascript de bas niveau permettant de
faire des manipulations dom ou de l'ajax facilement. elle permet
de faire abstraction complète des différents navigateurs et de
leurs bugs ou spécificités en proposant des méthodes fonctionnant
sur tous les navigateurs.
toutes les opérations les plus courantes sont outillées de façon
appropriée pour pouvoir être utilisées facilement.
ce framework est de plus fortement orienté objet, ce qui en rend
la lecture et l'utilisation d'autant plus aisées et naturelles pour
tous les développeurs habitués à ce type de programmation.
version pdf
(miroir)
version hors-ligne
(miroir)
de quoi s'agit-il ?
1. les fonctions utilitaires
1-a. utilisation de la fonction $()
1-b. utilisation de la fonction $f()
1-c. utilisation de la fonction $a()
1-d. utilisation de la fonction $h()
1-e. utilisation de la fonction $r()
1-f. utilisation de la fonction try.these()
2. l'objet ajax
2-a. utilisation de la classe ajax.request
2-b. utilisation de la classe ajax.updater
3. enumérer... youhou ! super ! génial !
3-a. boucles en syntaxe ruby
3-b. vos tableaux dopés aux stéroïdes
4. des livres que je recommande fortement
5. référence de prototype.js
5-a. extensions des classes javascript existantes
5-a-1. extensions pour la classe object
5-a-2. extensions pour la classe number
5-a-3. extensions pour la classe function
5-a-4. extensions pour la classe string
5-a-5. extensions pour la classe array
5-a-6. extensions pour l'objet dom document
5-a-7. extensions pour l'objet event
5-b. nouveaux objets et classes définis par prototype.js
5-b-1. l'objet periodicalexecuter
5-b-2. l'objet prototype
5-b-3. l'objet enumerable
5-b-4. l'objet hash
5-b-5. la classe objectrange
5-b-6. l'objet class
5-b-7. l'objet ajax
5-b-7-a. l'objet ajax.responders
5-b-7-b. la classe ajax.base
5-b-7-c. la classe ajax.request
5-b-7-d. l'objet/argument options
5-b-7-e. la classe ajax.updater
5-b-7-f. la classe ajax.periodicalupdater
5-b-8. l'objet element
5-b-8-a. la classe element.classnames
5-b-9. l'objet abstract
5-b-9-a. la classe abstract.insertion
5-b-10. l'objet insertion
5-b-10-a. la classe insertion.before
5-b-10-b. la classe insertion.top
5-b-10-c. la classe insertion.bottom
5-b-10-d. la classe insertion.after
5-b-11. l'objet field
5-b-12. l'objet form
5-b-12-a. l'objet form.element
5-b-12-b. l'objet form.element.serializers
5-b-13. la classe abstract.timedobserver
5-b-13-a. la classe form.element.observer
5-b-13-b. la classe form.observer
5-b-14. la classe abstract.eventobserver
5-b-14-a. la classe form.element.eventobserver
5-b-14-b. la classe form.eventobserver
de quoi s'agit-il ?
au cas où vous ne l'auriez pas encore utilisée, prototype.js est
une librairie javascript écrite par sam stephenson. ce code très
bien pensé et bien écrit, conforme aux standards, facilite la
création de pages riches et hautement interactives
en web 2.0.
si vous avez essayé d'utiliser cette librairie récemment, vous
avez pu vous rendre compte que sa documentation n'est pas son
point fort. comme de nombreux développeurs avant moi, j'ai
apprivoisé prototype.js en lisant la source du code et en
l'expérimentant. j'ai pensé qu'il serait sympa de prendre
des notes au fur et à mesure de mon apprentissage et de les
partager avec tout le monde.
je propose également une référence non officielle pour les
objets, classes et extensions fournis par cette librairie.
en lisant les exemples et les références, les développeurs
familiers du langage ruby pourront constater une similitude
intentionnelle entre les classes ruby et de nombreuses extensions
mises en oeuvre dans cette librairie.
1. les fonctions utilitaires
la librairie comporte de nombreux objets prédéfinis et fonctions
utilitaires. le but évident de ces fonctions est de vous
épargner des frappes répétées.
1-a. utilisation de la fonction $()
la fonction $() est un
raccourci pratique pour la fonction
dom très souvent utilisée document.getelementbyid().
tout comme la fonction dom, celle-ci retourne l'élément
dont l'id est passé en paramètre.
contrairement à la fonction dom, celle-ci va plus loin.
vous pouvez lui passer plus d'un seul id et $() retournera
un tableau (array) des éléments requis.
l'exemple ci-dessous illustre cela :
<html>
<head>
<title> page de test </title>
<script type='text/javascript' src="prototype-1.4.0.js"></script>
<script type='text/javascript'>
function test1()
{
var d = $('mondiv');
alert(d.innerhtml);
}
function test2()
{
var divs = $('mondiv','monautrediv');
for(i=0; i<divs.length; i++)
{
alert(divs[i].innerhtml);
}
}
</script>
</head>
<body>
<div id="mondiv">
<p>ceci est un paragraphe</p>
</div>
<div id="monautrediv">
<p>ceci est un autre paragraphe</p>
</div>
<input type="button" value="test1" onclick="test1();"><br>
<input type="button" value="test2" onclick="test2();"><br>
</body>
</html>
une autre chose appréciable avec cette fonction, c'est
que l'on peut aussi lui passer indifféremment l'id de l'élément
ou l'élément lui-même, ce qui la rend très utile lors de la
création d'autres fonctions qui acceptent également l'une ou
l'autre forme de paramètres.
1-b. utilisation de la fonction $f()
la fonction $f() est un
autre raccourci appréciable. elle retourne la valeur de
n'importe quel contrôle de saisie, tel que input type='text'
ou select. la fonction accepte indifféremment en argument
l'id de l'élément ou l'élément lui-même.
<script type='text/javascript'>
function test3()
{
alert( $f('utilisateur') );
}
</script>
<input type="text" id="utilisateur" value="marc assin"><br>
<input type="button" value=test3 onclick="test3();"><br>
1-c. utilisation de la fonction $a()
la fonction $a() convertit
l'unique paramètre qu'elle reçoit en un objet array.
cette fonction, combinée avec les extensions de la classe
array, facilite la conversion de n'importe quelle liste
énumérable en tableau (array) ou sa copie. une suggestion
d'utilisation est de convertir une nodelist dom en un
tableau (array) qui pourra être parcouru plus efficacement.
voir l'exemple ci-dessous :
<script type='text/javascript'>
function montreoptions(){
var lanodelist = $('employes').getelementsbytagname('option');
var noeuds = $a(lanodelist);
noeuds.each(function(noeud){
alert(noeud.nodename + ': ' + noeud.innerhtml);
});
}
</script>
<select id="employes" size="10" >
<option value="5">martin, steven</option>
<option value="8">hauchon, paul </option>
<option value="1">dupré, jean</option>
</select>
<input type="button" value="afficher les options" onclick="montreoptions();" >
1-d. utilisation de la fonction $h()
la fonction $h() convertit les objets en objets hash
énumérables qui s'apparentent à des tableaux associatifs.
<script type='text/javascript'>
function testhash()
{
//creation de l'objet
var a = {
premier: 10,
second : 20,
troisieme : 30
};
// maintenant transformons le en hash
var h = $h(a);
alert(h.toquerystring()); //affiche: premier=10&second=20&troisieme=30
}
</script>
1-e. utilisation de la fonction $r()
la fonction $r() est simplement un raccourci pour
new objectrange(limitebasse,limitehaute, exclurelimites).
se référer à la documentation sur la classe objectrange
pour une explication complète de cette classe. toutefois,
étudions un exemple simple qui montre également l'utilisation
d'itérations au travers de la méthode each. vous trouverez
plus d'informations sur cette méthode dans la documentation
sur l'objet énumérable.
<script type='text/javascript'>
function demodollar_r(){
var indice = $r(10, 20, false);
indice.each( function(valeur, index) {
alert(value);
});
}
</script>
<input type="button" value="comptage count" onclick="demodollar_r();" >
1-f. utilisation de la fonction try.these()
la fonction try.these() facilite l'appel à différentes
fonctions ... heu ... jusqu'à ce que l'une d'entre elles
fonctionne. elle accepte plusieurs fonctions en
paramètre et les appelle l'une après l'autre
dans l'ordre jusqu'à ce que l'une d'entre elles
fonctionne, elle retourne alors le résultat de la
fonction dont l'appel à été fructueux.
dans l'exemple ci-dessous, la fonction xmlnode.text
est implémentée dans certains navigateurs et
xmlnode.textcontent est implémentée dans les autres
navigateurs. en utilisant la fonction try.these()
il nous est possible d'obtenir le résultat de celle
qui fonctionne.
<script>
function getvaleurnoeud(noeudxml){
return try.these(
function() {return noeudxml.text;},
function() {return noeudxml.textcontent;}
);
}
</script>
2. l'objet ajax
les fonctions utilitaires évoquées ci-dessus sont sympathiques,
mais soyons honnêtes elles ne sont pas des plus avancées.
vous pourriez probablement en faire autant, et vous avez
peut-être des fonctions similaires dans vos propres scripts.
mais ces fonctions ne sont que la partie émergée de l'iceberg.
je suis sûr que votre intérêt pour prototype.js est principalement
dirigé vers ses capacités en ajax. alors je vais vous expliquer
en quoi cette librairie va vous faciliter la vie pour implémenter ajax.
l'objet ajax est un objet prédéfini créé par la librairie pour
englober et simplifier le code compliqué nécessaire pour la mise
en oeuvre de la technologie ajax. cet objet comporte de nombreuses
classes qui intègrent les fonctionnalités de la technologie ajax.
passons en revue certaines de ces classes.
2-a. utilisation de la classe ajax.request
si vous n'utilisez pas de librairie, vous devez certainement
avoir recours à un code important pour créer un objet xmlhttprequest,
puis suivre son statut de façon asynchrone, puis en extraire
la réponse et enfin traiter la réponse. et estimez-vous
heureux si vous n'avez pas à implémenter cela pour
plusieurs navigateurs.
pour faciliter les fonctionnalités d'ajax, la bibliothèque
définit la classe ajax.request.
admettons que vous ayez une application qui communique
avec le serveur au travers de l'url
http://votreserveur/application/cherche_ventes?idemploye=1234&annee=1998,
qui retourne une réponse xml comme suit :
<?xml version="1.0" encoding="utf-8" ?>
<reponse-ajax>
<reponse type="object" id="detailsproduit">
<ventes-mensuelles>
<ventes-employe>
<id-employe>1234</id-employe>
<annee-mois>1998-01</annee-mois>
<ventes>$8,115.36</ventes>
</ventes-employe>
<ventes-employe>
<id-employe>1234</id-employe>
<annee-mois>1998-02</annee-mois>
<ventes>$11,147.51</ventes>
</ventes-employe>
</ventes-mensuelles>
</reponse>
</reponse-ajax>
communiquer avec le serveur pour récupérer ce xml
est relativement simple en utilisant l'objet ajax.request.
l'exemple ci-dessous montre comment :
<script>
function rechercheventes() {
var idemploye = $f('listeemployes');
var annee = $f('listeannees');
var url = 'http://votreserveur/application/cherche_ventes';
var parametres = 'idemploye=' + idemploye + '&annee=' + annee;
var myajax = new ajax.request(
url,
{
method: 'get',
parameters: parametres,
oncomplete: affichereponse
}
);
}
function affichereponse(requete) {
//affiche le xml dans le textarea
$('resultat').value = requete.responsetext;
}
</script>
<select id="listeemployes" size="10" onchange="rechercheventes()">
<option value="5">buchanan, steven</option>
<option value="8">callahan, laura</option>
<option value="1">davolio, nancy</option>
</select>
<select id="listeannees" size="3" onchange="rechercheventes()">
<option selected="selected" value="1996">1996</option>
<option value="1997">1997</option>
<option value="1998">1998</option>
</select>
<br>
<textarea id='resultat' cols=60 rows=10 ></textarea>
avez-vous vu le second paramètre passé au constructeur
de l'objet ajax.request ? le paramètre
{method: 'get', parameters: pars, oncomplete: affichereponse}
represente un objet anonyme en notation littérale
(aussi connu sous le nom de json). ce que je veux dire
c'est que nous passons un objet qui possède une propriété
nommée method qui contient le string 'get', une autre propriété
nommée parameters qui contient la chaîne d'interrogation de la requête
http et une propriété/méthode oncomplete qui contient
la fonction affichereponse.
il y a d'autres propriétés que l'on peut renseigner dans
cet objet, telle que asynchronous qui peut prendre
les valeurs true ou false et détermine si l'appel ajax
vers le serveur doit être fait de façon asynchrone
ou non (la valeur par default est true).
ce paramètre définit les options pour l'appel ajax.
dans notre exemple, nous appelons l'url dans le premier
paramètre par une commande http get, en passant la
chaîne d'interrogation contenue dans la variable parameters,
et l'objet ajax.request
appellera la fonction affichereponse
lorsqu'elle aura terminé la récupération de la réponse.
comme vous le savez, xmlhttprequest rend compte de sa
progression au cours de l'appel http. cet avancement
se décompose en quatre étapes différentes :
loading (en chargement), loaded (chargé), interactive (interactif)
ou complete (achevé). on peut demander à l'objet ajax.request
d'appeler une fonction personnelle à n'importe
laquelle de ces étapes, l'étape complete étant la plus utilisée.
pour informer l'objet de la fonction, ajouter simplement
la propriété/méthode appelée onxxxxx dans les options
de requête, tout comme le oncomplete dans notre exemple.
la fonction passée sera appelée par l'objet avec deux
paramètres, le premier sera le xmlhttprequest
(aussi connu sous l'appellation de xhr) lui-même, le second
sera l'évaluation x-json du header http de la réponse
(s'il y en a un).
<script>
var mesgestionnairesglobaux = {
oncreate: function(){
element.show('systemeattente');
},
oncomplete: function() {
if(ajax.activerequestcount == 0){
element.hide('systemeattente');
}
}
};
ajax.responders.register(mesgestionnairesglobaux);
</script>
<div id='systemeattente'>
<img src='sablier.gif'>chargement en cours...
</div>
2-b. utilisation de la classe ajax.updater
si vous avez un script serveur qui peut renvoyer des
informations préformatées en html, alors la bibliothèque
peut vous rendre la vie encore plus facile avec la
classe ajax.updater.
avec celle-ci, vous n'avez qu'à indiquer quel élément doit
être alimenté par le code html renvoyé par l'appel ajax.
un exemple vaut mieux qu'un long discours :
<script>
function cherchehtml() {
var url = 'http://votreserveur/application/cherchehtml';
var parametres = 'unparametre=abcd';
var myajax = new ajax.updater(
'emplacement',
url,
{
method: 'get',
parameters: parametres
}
);
}
</script>
<input type='button' value='cherchehtml' onclick="cherchehtml()">
<div id="emplacement"></div>
comme vous pouvez le voir, le code ressemble beaucoup à
l'exemple précédent, à l'exception de la fonction
oncomplete et de
l'id de l'élément passé au constructeur. changeons un
peu ce code pour montrer comment il est possible de
gérer les erreurs serveur côté client.
nous allons ajouter quelques options supplémentaires à
l'appel, en spécifiant une fonction qui sera appelée en
cas d'erreur. cela se fait grâce à l'option
onfailure. nous
préciserons également que notre élément
emplacement ne doit
être alimenté qu'en cas de succès de l'appel. pour parvenir
à nos fins, nous allons transformer le premier paramètre
d'un simple id d'élément à un objet possédant deux
propriétés, success
(à utiliser quand tout s'est bien passé) et
failure
(à utiliser quand quelque chose se passe mal).
nous n'utiliserons pas la propriété
failure dans notre
exemple, mais uniquement la fonction
rapporteerreur dans
l'option onfailure.
<script>
function cherchehtml() {
var url = 'http://votreserveur/application/cherchehtml';
var parametres = 'unparametre=abcd';
var myajax = new ajax.updater(
'emplacement',
url,
{
method: 'get',
parameters: parametres,
onfailure: rapporteerreur
}
);
}
function rapporteerreur(requete) {
alert('désolé, une erreur s'est produite.');
}
</script>
<input type='button' value='cherchehtml' onclick="cherchehtml()">
<div id="emplacement"></div>
si les balises html renvoyées par votre code côté serveur
sont accompagnées de code javascript, l'objet
ajax.updater peut
évaluer ce dernier. afin que l'objet interprète la
réponse comme du code javascript, ajoutez simplement
evalscripts: true; à
la liste des propriétés du dernier paramètre du constructeur
de l'objet. un avertissement toutefois : ces blocs de script
ne seront pas ajoutés aux scripts de la page. comme l'option
evalscripts le suggère
les scripts seront évalués. quelle est la différence
vous demandez-vous ? imaginons que la requête exécutée
renvoie quelque chose comme :
<script language="javascript" type="text/javascript">
function disbonjour(){
alert('bonjour!');
}
</script>
<input type=button value="clique moi" onclick="disbonjour()">
si vous avez essayé cela auparavant, vous savez que cela
ne fonctionne pas. la raison en est que le bloc de script
sera évalué, et évaluer un script tel que le précédent ne
créera pas de fonction nommée
disbonjour. cela ne fera
rien. pour créer cette fonction nous devons changer notre
script pour créer la fonction. voyez ci-dessous :
<script language="javascript" type="text/javascript">
disbonjour = function(){
alert('bonjour!');
};
</script>
<input type=button value="clique moi" onclick="disbonjour()">
notez que dans l'exemple précédent nous n'utilisons pas le
mot-clef var. si nous
l'avions utilisé, cela aurait créé un objet fonction qui
aurait été local au bloc de script (dans ie tout du moins).
sans le mot-clef var,
l'objet fonction est global à la fenêtre, ce que nous souhaitons.
3. enumérer... youhou ! super ! génial !
nous sommes tous habitués aux boucles for. vous savez,
créer un tableau à la main, le remplir avec des éléments
du même type, créer une boucle de contrôle
(for, foreach, while, repeat, etc), accéder à chaque élément
de manière séquentielle, par son index numérique,
et faire quelque chose avec cet élément.
si vous y réfléchissez bien, chaque fois que vous utilisez
un tableau dans votre code, cela signifie que, tôt ou tard,
vous utiliserez ce tableau dans une boucle.
ne serait-ce pas agréable si ces tableaux offraient plus de
fonctionnalités quant à ces itérations ? oui, ce le serait,
et bon nombre de langages de programmation fournissent de
telles fonctionnalités pour leurs tableaux ou leurs structures
équivalentes (comme les collections et les listes).
eh bien justement prototype.js nous propose
l'objet enumerable,
qui implémente pour nous une pléthore de trucs et astuces à
utiliser lors des itérations sur les données.
la bibliothèque prototype.js va un peu plus loin,
et étend la classe array avec toutes les méthodes de
enumerable.
3-a. boucles en syntaxe ruby
classiquement en javascript, si vous vouliez afficher
les éléments d'un tableau de manière séquentielle, vous
pouviez tout à fait écrire quelque chose comme ceci :
<script>
function montreliste() {
var simpsons = ['homer', 'marge', 'lisa', 'bart', 'meg'];
for(i=0;i<simpsons.length;i++){
alert(simpsons[i]);
}
}
</script>
<input type="button" value="montre la liste" onclick="montreliste();" >
avec notre nouveau meilleur ami, prototype.js, nous pouvons
réécrire la boucle ainsi :
function montreliste(){
var simpsons = ['homer', 'marge', 'lisa', 'bart', 'meg'];
simpsons.each(
function(membredelafamille){
alert(membredelafamille);
}
);
}
vous pensez sans doute "mon dieu... quelle syntaxe étrange
pour faire la même chose". bon, dans l'exemple d'au-dessus,
oui, il n'y a rien de bien extraordinaire. après tout, il
n'y a pas grand chose à modifier dans un exemple aussi
trivial. mais continuez de lire néanmoins.
afin de continuer : vous voyez cette fonction qui est passée
en argument à la méthode each ?
commençons dès maintenant à la désigner comme fonction itératrice.
3-b. vos tableaux dopés aux stéroïdes
comme nous l'avons mentionné auparavant, il est très courant
que tous les éléments de vos tableaux soient du même type,
avec les mêmes propriétés et méthodes. voyons comment nous
pouvons tirer partie des fonctions itératrices avec nos tout
nouveaux tableaux.
trouver un élément suivant un critère :
<script>
function trouveemployeparid(idemploye){
var listebox = $('listeemployes')
var options = listebox.getelementsbytagname('option');
options = $a(options);
var opt = options.find(
function(employe){
return (employe.value == idemploye);
}
);
alert(opt.innerhtml); //affiche le nom de l'employe
}
</script>
<select id="listeemployes" size="10" >
<option value="5">buchanan, steven</option>
<option value="8">callahan, laura</option>
<option value="1">davolio, nancy</option>
</select>
<input type="button" value="trouve laura" onclick="trouveemployeparid(8);" >
maintenant, améliorons-le encore un peu. voyons comment
filtrer des éléments dans des tableaux, pour ne retrouver
qu'un membre de chaque élément.
<script>
function montrelienslocaux(paragraphe){
paragraphe = $(paragraphe);
var liens = $a(paragraphe.getelementsbytagname('a'));
//trouve les liens qui ne commencent pas par 'http'
var lienslocaux = liens.findall( function(lien){
var debut = lien.href.substring(0,4);
return debut !='http';
});
//maintenant, les textes des liens
var textes = lienslocaux.pluck('innerhtml');
//rassemblons les dans une seule chaîne
var resultat = textes.inspect();
alert(resultat);
}
</script>
<p id="dutexte">
ce <a href="http://unautresite.com/page.html">texte</a> a
<a href="#ancrelocal">beaucoup</a> de
<a href="#autreancre">liens</a>. certain sont
<a href="http://ouvousvoulez.com/page.html">externes</a>
et d'autre sont <a href="#uneancre">locaux</a>
</p>
<input type=button value="trouve les liens locaux" onclick="montrelienslocaux('dutexte')">
cela ne demande qu'un peu de pratique pour devenir complètement
dépendant de cette syntaxe. voyez les références des objets
enumerable et
array pour toutes les
fonctions disponibles.
4. des livres que je recommande fortement
certains livres sont tout simplement trop bons pour ne pas passer
le mot. les livres suivants m'ont beaucoup aidé à acquérir
les nouvelles compétences nécessaires pour créer des applications
ajax, et aussi consolider les compétences que je pensais déjà
maîtriser. je pense qu'un bon livre constitue un bon investissement,
qui est vite rentabilisé.
5. référence de prototype.js
5-a. extensions des classes javascript existantes
une des façons pour la bibliothèque prototype.js d'ajouter
des fonctionnalités est d'étendre les classes javascript existantes.
5-a-1. extensions pour la classe object
méthode
type
arguments
description
extend(destination,source)
statique
destination : un objet, source: un objet
propose une solution pour implémenter l'héritage en copiant toutes les propriétés et méthodes de source vers destination.
inspect(objetcible)
statique
objetcible : un objet
retourne une chaîne lisible représentant objetcible. par défaut, retourne la valeur de tostring si l'objet donné n'a pas de définition d'une méthode d'instance inspect.
5-a-2. extensions pour la classe number
méthode
type
arguments
description
tocolorpart()
instance
(aucun)
retourne la représentation hexadécimale de ce nombre. particulièrement utile pour convertir les composants rvb dans leur représentation html.
succ()
instance
(aucun)
retourne le nombre suivant. cette fonction est utilisée dans le cas d'une itération.
times(iterateur)
instance
iterateur: un objet fonction conforme à function(index)
appelle la méthode iterateur de façon répétée en lui passant l'index courant comme argument index.
démonstration de number.times()<script>
function demotimes(){
var n = 10;
n.times(function(index){
alert(index);
});
/***************************
* on aurait également pu utiliser:
* (10).times( .... );
***************************/
}
</script>
<input type=button value="test number.times()" onclick="demotimes()">
5-a-3. extensions pour la classe function
méthode
type
arguments
description
bind(objet)
instance
objet: l'objet qui possède la méthode
retourne une instance de la fonction pré-liée à l'objet propriétaire de la fonction (=méthode). la fonction retournée aura les mêmes arguments que l'originale.
bindaseventlistener(objet)
instance
objet: l'objet qui possède la méthode
retourne une instance de la fonction pré-liée à l'objet propriétaire de la fonction (=méthode). la fonction retournée aura l'objet event courant comme argument.
voyons une des ces extensions en action:
démonstration de function.bindaseventlistener()<input type='checkbox' id='machk' value=1> test?
<script>
//déclaration de la classe
var surveillantcheckbox = class.create();
//définition de l'implémentation de notre classe
surveillantcheckbox.prototype = {
initialise: function(chkbox, message) {
this.chkbox = $(chkbox);
this.message = message;
//assignement de notre méthode à l'évenement
this.chkbox.onclick =
this.montremessage.bindaseventlistener(this);
},
montremessage: function(evt) {
alert(this.message + ' (' + evt.type + ')');
}
};
var surveillant = new surveillantcheckbox('machk', 'changement');
</script>
5-a-4. extensions pour la classe string
méthode
type
arguments
description
striptags()
instance
(aucun)
retourne la chaîne de caractères avec les balises html ou xml supprimées.
stripscripts()
instance
(aucun)
retourne la chaîne de caractères avec les blocs <script /> supprimés.
escapehtml()
instance
(aucun)
retourne la chaîne de caractères avec les caractères spéciaux html propres.
unescapehtml()
instance
(aucun)
l'inverse de escapehtml().
extractscripts()
instance
(aucun)
retourne un objet array contenant tous les blocs <script /> trouvés dans la chaîne de caractères.
evalscripts()
instance
(aucun)
evalue chacun des blocs <script /> trouvés dans la chaîne de caractères.
toqueryparams()
instance
(aucun)
sépare une chaîne d'interrogation en array associatif, indexé par le nom du paramètre (semblable à une table de hachage).
parsequery()
instance
(aucun)
même chose que toqueryparams().
toarray()
instance
(aucun)
sépare la chaîne de caractères en un array de ses caractères.
camelize()
instance
(aucun)
convertit une chaîne délimitée par des tirets en une chaîne en camelcase. cette méthode est utile, par exemple, dans le cas des propriétés de style.
5-a-5. extensions pour la classe array
pour commencer, array hérite de enumerable, si bien
que toutes les méthodes pratiques, définies dans les
objets enumerable, sont disponibles. de plus, les
méthodes ci-dessous sont également implémentées.
méthode
type
arguments
description
clear()
instance
(aucun)
vide ce tableau et le retourne.
compact()
instance
(aucun)
retourne ce tableau sans les éléments qui sont null ou undefined. cette méthode ne modifie pas le tableau lui-même.
first()
instance
(aucun)
retourne le premier élément du tableau.
flatten()
instance
(aucun)
retourne une version plate, à une dimension du tableau. cet aplatissage se fait en cherchant tous les éléments qui sont eux-mêmes des tableaux et en ajoutant leurs éléments dans le tableau final, récursivement.
indexof(valeur)
instance
valeur : ce que vous recherchez
retourne la position (commençant à 0) de la valeur donnée si elle est présente dans le tableau. retourne -1 si la valeur n'est pas trouvée.
inspect()
instance
(aucun)
surchargée pour retourner une chaîne formatée représentant le tableau et ses éléments.
last()
instance
(aucun)
retourne le dernier élément du tableau.
reverse([asoimeme])
instance
asoimeme : indique si le tableau lui-même doit être inversé
retourne le tableau dans l'ordre inverse. si aucun argument n'est fourni, ou que l'argument est true, le tableau lui-même est inversé. sinon, il reste inchangé.
shift()
instance
(aucun)
retourne le premier élément et le supprime du tableau, réduisant la taille du tableau de 1.
without(valeur1 [, valeur2 [, .. valeurn]])
instance
valeur1 ... valeurn : les valeurs à exclure du tableau si présentes.
retourne le tableau, à l'exception des éléments qui sont dans la liste des arguments.
5-a-6. extensions pour l'objet dom document
méthode
type
arguments
description
getelementsbyclassname(nomclasse [, elementparent])
instance
nomclasse : nom de la classe css associée aux éléments, elementparent : élément ou id de l'élément contenant les éléments recherchés
retourne tous les éléments qui sont associés au nom de classe css donné. si aucun elementparent n'est donné, tout le corps du document sera inspecté.
5-a-7. extensions pour l'objet event
propriété
type
description
key_backspace
number
8 : constante. code pour la touche retour chariot.
key_tab
number
9 : constante. code pour la touche tabulation.
key_return
number
13 : constante. code pour la touche entrée.
key_esc
number
27 : constante. code pour la touche echap.
key_left
number
37 : constante. code pour la touche flèche gauche.
key_up
number
38 : constante. code pour la touche flèche haute.
key_right
number
39 : constante. code pour la touche flèche droite.
key_down
number
40 : constante. code pour la touche flèche vers le bas.
key_delete
number
46 : constante. code pour la touche suppr.
observers
array
liste des observeurs mis en cache. fait partie des détails de l'implémentation interne de l'objet.
méthode
type
arguments
description
isleftclick(evenement)
static
evenement : un objet event
retourne true si le bouton gauche a été cliqué.
pointerx(evenement)
static
evenement : un objet event
retourne la coordonnée x (abscisse) du pointeur de la souris sur cette page.
pointery(evenement)
static
evenement : un objet event
retourne la coordonnée y (ordonnée) du pointeur de la souris sur cette page.
stop(evenement)
static
evenement : un objet event
utilisez cette méthode pour arrêter le comportement par défaut d'un évènement et stopper sa propagation.
findelement(evenement, nombalise)
static
evenement : un objet event, nombalise : nom de la balise désirée
parcourt l'arbre dom vers le haut pour trouver le premier élément ayant la balise donnée, en commençant par l'élément à l'origine de l'évènement.
observe(element, nom, observeur, utilisecapture)
static
element : objet ou id, nom : nom de l'évènement (comme 'click', 'load', ...), observeur : fonction pour traiter l'évènement, utilisecapture : si true, gère l'evenement dans la phase de capture et si false dans la phase de 'bubbling'
ajoute un gestionnaire d'évènement à un élément.
stopobserving(element, nom, observeur, utilisecapture)
static
element : objet ou id, nom : nom de l'évènement (comme 'click', 'load', ...), observeur : fonction pour traiter l'évènement, utilisecapture : si true, gère l'evenement dans la phase de capture et si false dans la phase de 'bubbling'
supprime un gestionnaire d'évènement à un élément.
_observeandcache(element, nom, observeur, utilisecapture)
static
méthode privée. ne vous en souciez pas.
unloadcache()
static
(aucun)
méthode privée. ne vous en souciez pas. supprime tous les observeurs en cache de la mémoire.
voyons comment utiliser cet objet pour ajouter un gestionnaire
d'évènement sur l'évènement 'load' de l'objet window.
<script>
event.observe(window, 'load', montremessage, false);
function montremessage() {
alert('page chargée.');
}
</script>
5-b. nouveaux objets et classes définis par prototype.js
cette bibliothèque vous aide également d'une autre façon en
vous proposant de nombreux objets qui permettent une conception
orientée objet ou qui implémentent des fonctionnalités habituellement
utilisées.
5-b-1. l'objet periodicalexecuter
cet objet propose la logique nécessaire pour appeler
une fonction donnée de façon répétée, à intervalle donné.
méthode
type
arguments
description
[constructeur](rappel, intervalle)
constructeur
rappel : une méthode sans arguments, intervalle : nombre de secondes
créé une instance de cet objet qui appellera la méthode de façon répétée.
propriété
type
description
callback
function()
la méthode à appeler. aucun paramètre ne lui sera passé.
frequency
number
c'est en fait l'intervalle de temps en secondes.
currentlyexecuting
boolean
indique si un appel de la méthode est en cours.
5-b-2. l'objet prototype
l'objet prototype n'a aucun
rôle important, autre que déclarer la version actuelle
de la librairie.
propriété
type
description
version
string
la version de la bibliothèque.
emptyfunction
function()
un objet function vide.
k
function(obj)
un objet function qui retourne le paramètre.
scriptfragment
string
une expression régulière permettant d'identifier les scripts.
5-b-3. l'objet enumerable
l'objet enumerable permet d'écrire du code plus lisible
pour itérer sur les éléments d'une structure de type liste.
beaucoup d'autres objets étendent l'objet enumerable pour
profiter de son interface très utile.
méthode
type
arguments
description
each(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
appelle la méthode iterateur en passant chacun des éléments de la liste comme premier argument et l'indice dans la liste comme second argument.
all([iterateur])
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice), optionnel
cette méthode permet de tester toute une collection de valeurs en utilisant une fonction donnée. all retournera false si la fonction iterateur retourne false ou null pour un des éléments. elle retournera true autrement. si aucun iterateur n'est donné, alors le test sera si l'élément est lui-même différent de false ou null. vous pouvez simplement le penser comme : "vérifie que tous les éléments sont non-faux".
any([iterateur])
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice), optionnel
cette méthode permet de tester toute une collection de valeurs en utilisant une fonction donnée. any retournera true si la fonction iterateur ne retourne pas false ou null pour un des éléments. elle retournera false autrement. si aucun iterateur n'est donné, alors le test sera si l'élément est lui-même différent de false ou null. vous pouvez simplement le penser comme : "vérifie que tous les éléments sont non-faux".
collect(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
appelle la méthode iterateur pour chacun des éléments de la collection et retourne tous les résultats dans un array, un élément résultat pour chaque élément dans la collection, dans le même ordre.
detect(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
appelle la méthode iterateur pour chacun des éléments de la collection et retourne le premier élément qui a provoqué le retour de true par l'iterateur (ou plus précisément, non-faux). si aucun des éléments ne retourne vrai, detect retourne null.
entries()
instance
(aucun)
idem que toarray().
find(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
idem que detect().
findall(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
appelle la méthode iterateur pour chacun des éléments de la collection et retourne un array de tous les éléments pour lesquels l'iterateur a retourné une valeur équivalente à true. cette méthode est le complémentaire de reject().
grep(motif [, iterateur])
instance
motif : une expression régulière utilisée pour tester les éléments, iterateur : un objet fonction se conformant à la signature function(valeur, indice)
teste la valeur en string de chacun des éléments de la collection contre le motif de l'expression régulière. cette méthode retourne un array contenant tous les éléments qui correspondent à l'expression régulière. si une méthode iterateur est donnée, l'array contiendra le résultat de l'appel à l'iterateur avec chacun des éléments qui étaient conformes à l'expression régulière.
include(obj)
instance
obj : un objet
cherche l'objet dans la collection courante. retourne true si l'objet est trouvé, false autrement.
inject(valeurinitiale, iterateur)
instance
valeurinitiale : n'importe quel objet, faisant office de valeur initiale, iterateur : un objet fonction se conformant à la signature function(accumulateur, valeur, indice)
combine tous les éléments de la collection en utilisant la méthode iterateur. l'iterateur est appelé en passant le résultat de l'appel précédent via l'argument accumulateur. le premier appel utilise valeurinitiale comme argument accumulateur. le dernier résultat est le retour de la méthode.
invoke(nommethode [, arg1 [, arg2 [...]]])
instance
nommethode: nom de la méthode qui va être appelée dans chaque élément, arg1..argn: arguments qui seront passés en paramètres de l'appel.
appelle la méthode spécifiée par nommethode dans chaque élément de la collection, en passant les arguments donnés (arg1 à argn), et retourne les résultats dans un objet array.
map(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
idem que collect().
max([iterateur])
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
retourne l'élément avec la plus grande valeur dans la collection ou avec le plus grand résultat de l'appel à l'iterateur pour chacun des éléments de la collection, si un iterateur est donné.
member(obj)
instance
obj : un objet
idem que include().
min([iterateur])
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
retourne l'élément avec la plus petite valeur dans la collection ou avec le plus petit résultat de l'appel à l'iterateur pour chacun des éléments de la collection, si un iterateur est donné.
partition([iterateur])
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
retourne un array contenant deux autres vecteurs. le premier vecteur contiendra tous les éléments pour lesquels l'iterateur a retourné true et le second vecteur contiendra les éléments restants. si aucun iterateur n'est donné, le premier vecteur contiendra tous les éléments équivalents à true et l'autre vecteur, les éléments restant.
pluck(nompropriété)
instance
nompropriété : nom de la propriété qui sera lue dans chacun des éléments. peut également être l'indice de la propriété.
recherche la valeur de la propriété passée en argument dans chacun des éléments de la collection et retourne le résultat dans un objet array.
reject(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
appelle la méthode iterateur sur chacun des éléments de la collection et retourne un array avec tous les éléments pour lesquels la fonction iterateur a retourné une valeur équivalente à false. cette méthode est l'opposé de findall().
select(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
idem que findall().
sortby(iterateur)
instance
iterateur : un objet fonction se conformant à la signature function(valeur, indice)
retourne un array contenant les éléments triés selon le résultat de l'appel à l'iterateur.
toarray()
instance
(aucun)
retourne un array avec tous les éléments de la collection.
zip(collection1[, collection2 [, ... collectionn]] [,transformation])
instance
collection1 .. collectionn: énumérations qui seront fusionnées, transformation : un objet fonction se conformant à la signature function(valeur, indice)
fusionne chacune des collections données avec la collection courante. la fusion retourne un nouveau vecteur, avec le même nombre d'éléments que la collection courante et chacun des éléments de ce vecteur est un vecteur (appelons les sous-vecteur) constitué des éléments avec le même indice dans chacune des collections fusionnées. si une fonction transformation est donnée, chaque sous-vecteur sera transformé par cette fonction avec d'être fusionné. exemple rapide : [1,2,3].zip([4,5,6], [7,8,9]).inspect() retourne "[ [1,4,7],[2,5,8],[3,6,9] ]".
5-b-4. l'objet hash
l'objet hash implémente une structure
de type table de hachage, c'est-à-dire une collection de
paires clés/valeur.
chacun des éléments d'un objet hash
est un vecteur avec deux éléments : d'abord la clé, puis la valeur.
chaque élément a également deux propriétés, key
et value qui sont assez explicites.
méthode
type
arguments
description
keys()
instance
(aucun)
retourne un hash avec les clés de tous les éléments.
values()
instance
(aucun)
retourne un hash avec les valeurs de tous les éléments.
merge(autrehash)
instance
autrehash : un objet hash
combine l'objet hash avec un autre objet hash passé en argument et retourne l'objet hash résultant.
toquerystring()
instance
(aucun)
retourne tous les éléments de la table de hachage dans une chaîne formatée comme une chaîne de paramètres, i.e. 'cle1=valeur1&cle2=valeur2&cle3=valeur3'.
inspect()
instance
(aucun)
surchargée pour retourner une chaîne formatée représentant l'objet hash avec ses paires clé/valeur.
5-b-5. la classe objectrange
hérite de enumerable
représente une plage de valeurs avec les limites inférieures et supérieures.
propriété
type
description
start
(tous)
la borne inférieure de la plage de valeurs.
end
(tous)
la borne supérieure de la plage de valeurs.
exclusive
booléen
détermine si les limites sont dans la plage de valeurs.
méthode
type
arguments
description
[constructeur](debut, fin, exclusif)
constructeur
debut: la borne inférieur, fin: la borne supérieure, exclusif: inclure les limites dans la plage?
créé un objet plage de valeurs, allant de debut à fin. il est important de noter que debut et fin doivent être des objets du même type, ayant une méthode succ().
include(valeurrecherchee)
instance
valeurrecherchee: la valeur qu'on recherche
vérifie si la valeur donnée fait partie de la plage de valeur. retourne true ou false.
5-b-6. l'objet class
l'objet class est utilisé pour déclarer les autres classes de cette
bibliothèque. utiliser cet objet en créant une nouvelle classe
permet à la nouvelle classe d'avoir une méthode initialize()
qui fait office de constructeur.
voir l'exemple ci-dessous :
//déclaration de la classe
var maclasseexemple = class.create();
//définition du reste de l'implémentation de la classe
maclasseexemple.prototype = {
initialize: function(message) {
this.message = message;
},
affichemessage: function() {
alert(this.message);
}
};
//maintenant, utilisons un de ces objets
var monbavard = new maclasseexemple('bonjour tout le monde.');
monbavard.affichemessage(); //affiche l'alert
méthode
type
arguments
description
create(*)
instance
(tous)
définit le constructeur pour la nouvelle classe.
5-b-7. l'objet ajax
cet objet sert de base et d'espace de nom pour plusieurs autres classes
qui apportent des fonctionnalités ajax.
propriété
type
description
activerequestcount
number
le nombre de requêtes ajax en cours.
méthode
type
arguments
description
gettransport()
instance
(aucun)
retourne un nouvel objet xmlhttprequest.
5-b-7-a. l'objet ajax.responders
hérite de enumerable
cet objet maintient une liste d'objets qui vont être appelés
quand un évènement de type ajax sera déclenché.
vous pouvez utiliser cet objet, par exemple,
pour définir un gestionnaire d'erreur global pour les
opérations ajax.
propriété
type
description
responders
array
le tableau des objets enregistrés pour les notifications ajax.
méthode
type
arguments
description
register(repondeurajoute)
instance
repondeurajoute : objet avec les méthodes qui vont être appelées
l'objet passé dans l'argument repondeurajoute doit contenir des méthodes nommées d'après les évènements ajax (c.a.d. oncreate, oncomplete, onexception, etc.) quand l'évènement correspondant est déclenché tous les objets enregistrés qui possèdent la méthode avec le nom approprié verront cette méthode appelée.
unregister(repondeursupprime)
instance
repondeursupprime : objet à supprimer de la liste
l'objet passé dans l'argument repondeursupprime sera supprimé de la liste des objets enregistrés.
dispatch(evenementretour, requete, transport, json)
instance
evenementretour : nom de l'évènement ajax déclenché, requete : l'objet ajax.request responsable de l'évènement, transport: l'objet xmlhttprequest qui a véhiculé (ou vehicule) l'appel ajax, json: l'entete x-json de la réponse (si présent)
parcourt la liste des objets enregistrés, cherchant ceux qui ont la méthode donnée par l'argument evenementretour. ensuite, chacune de ces méthodes est appelée en passant en arguments les 3 autres paramètres. si la réponse ajax contient une entête http x-json avec du contenu json, alors il sera évalué et passé dans l'argument json. si l'évènement est onexception l'argument transport contiendra l'exception et l'argument json ne sera pas utilisé.
5-b-7-b. la classe ajax.base
cette classe est utilisée comme classe parente de la plupart des autres classes définies par l'objet ajax.
méthode
type
arguments
description
setoptions(options)
instance
options : options ajax
met en place les options demandées pour l'opération ajax.
responseissuccess()
instance
(aucun)
renvoie true si l'opération ajax a réussi, false sinon.
responseisfailure()
instance
(aucun)
l'inverse de responseissuccess().
5-b-7-c. la classe ajax.request
hérite de ajax.base
encapsule les opérations ajax.
propriété
type
nature
description
events
array
statique
liste des statuts/évènements possibles reportés pendant une requête ajax. cette liste contient: 'uninitialized', 'loading', 'loaded', 'interactive', et 'complete'.
transport
xmlhttprequest
instance
l'objet xmlhttprequest qui véhicule l'opération ajax.
url
string
instance
l'url cible de la requête.
méthode
type
arguments
description
[constructeur](url, options)
constructeur
url: l'url à appeler, options: options ajax
créé une instance de cet objet qui appellera l'url donnée en utilisant les options données. l'évènement oncreate sera appelé pendant l'appel au constructeur. important : il est bon de noter que l'url choisie est sujette à la politique de sécurité du navigateur. dans beaucoup de cas, les navigateurs ne chercheront pas une url sur un autre domaine que celui de la page courante. idéalement, vous devez utiliser uniquement des urls locales pour éviter d'avoir à modifier la configuration du navigateur de l'utilisateur. (merci clay).
evaljson()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne pour évaluer le contenu d'un éventuel header http x-json présent dans la réponse ajax.
evalresponse()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. si la réponse ajax a un header content-type text/javascript, le contenu de la réponse sera évalué par cette méthode.
header(nom)
instance
nom : nom du header http
retourne le contenu d'un header http de la réponse ajax. appelez cette méthode quand la requête ajax est terminée.
onstatechange()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est appelée par l'objet lui-même quand le statut de l'objet ajax change.
request(url)
instance
url : url de l'appel ajax
cette méthode ne doit pas être utilisée en externe. elle est appelée par le constructeur.
respondtoreadystate(readystate)
instance
readystate : numéro de l'état (1 à 4)
cette méthode ne doit pas être utilisée en externe. elle est appelée par l'objet lui-même quand le statut de l'objet ajax change.
setrequestheaders()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est appelée par l'objet lui-même pour mettre en place les entêtes http envoyés dans la requête http.
5-b-7-d. l'objet/argument options
une partie importante des opérations ajax provient de l'argument options.
il n'y a pas de classe options à proprement parler.
tout objet peut être utilisé, tant qu'il a les propriétés voulues.
il est courant de créer un objet anonyme pour les appels ajax.
propriété
type
défaut
description
parameters
string
''
la liste des valeurs (formatées pour l'url) passée à la requête.
asynchronous
boolean
true
indique que l'appel ajax va être asynchrone.
postbody
string
indéfini
contenu passé dans le corps de la requête dans le cas d'une requête post.
requestheaders
array
indéfini
liste des entêtes http passés à la requête. cette liste doit avoir un nombre pair d'éléments, chaque élément impair est le nom d'un entête et l'élément suivant est la valeur de cet entête. exemple :['mon-entete1', 'voici la valeur', 'mon-autre-entete', 'autre valeur'].
onxxxxxxxx
function(xmlhttprequest, object)
indéfini
fonction personnalisée à appeler quand l'évènement/statut correspondant est atteint durant un appel ajax. par exemple var mesoptions = {oncomplete: affichereponse, onloaded: enregistrecharge};. la méthode utilisée recevra un argument contenant l'objet xmlhttprequest qui transporte l'opération ajax et un second argument contenant les entêtes http x-json évalués.
onsuccess
function(xmlhttprequest, object)
indéfini
fonction personnalisée à appeler quand l'appel ajax finit normalement. la méthode utilisée recevra un argument contenant l'objet xmlhttprequest qui transporte l'opération ajax et un second argument contenant les entêtes http x-json évalués.
onfailure
function(xmlhttprequest, object)
indéfini
fonction personnalisée à appeler quand l'appel ajax finit avec un échec. la méthode utilisée recevra un argument contenant l'objet xmlhttprequest qui transporte l'opération ajax et un second argument contenant les entêtes http x-json évalués.
onexception
function(ajax.request, exception)
indéfini
fonction personnalisée à appeler quand une exception survient du côté client de l'appel ajax, comme une réponse non valide ou des arguments non valides. la méthode utilisée recevra deux arguments contenant l'objet ajax.request qui englobe l'opération ajax ainsi que l'exception.
insertion
une classe insertion
indéfini
une classe qui détermine comment le nouveau contenu sera inséré. cela peut être insertion.before, insertion.top, insertion.bottom ou insertion.after. s'applique uniquement aux objets ajax.updater.
evalscripts
boolean
indéfini, faux
détermine si les blocs de script seront évalués au retour de la réponse. s'applique uniquement aux objets ajax.updater.
decay
number
indéfini, 1
détermine le ralentissement progressif dans la vitesse de rafraichissement de l'objet ajax.periodicalupdater quand la réponse reçue est la même que la précédente. par exemple, si vous mettez 2, après qu'une mise à jour produise le même résultat que la précédente, l'objet attendra deux fois plus avant la prochaine mise à jour. si cela se répète à nouveau, l'objet attendra quatre fois plus longtemps, et ainsi de suite. laissez-le indéfini ou mettez 1 pour empêcher le ralentissement.
frequency
number
indéfini, 2
intervalle (pas fréquence) entre les rafraichissements, en secondes. s'applique uniquement aux objets ajax.periodicalupdater.
5-b-7-e. la classe ajax.updater
hérite de ajax.request
utilisée quand l'url requêtée retourne du html que vous voulez injecter directement dans un élément donné de votre page. vous pouvez également utiliser cet objet quand l'url retourne des blocs <script> qui seront évalués au retour. utilisez l'option evalscripts pour utiliser les scripts.
propriété
type
description
containers
objet
cet objet contient deux propriétés: containers.success sera utilisé quand l'appel ajax sera un succès, et containers.failure utilisé autrement.
méthode
type
arguments
description
[constructeur](conteneur, url, options)
constructeur
conteneur: peut être l'id d'un élément, l'élément lui-même, ou un objet avec deux propriétés : un élément (ou id) object.success qui sera utilisé en cas de succès de l'appel ajax et un élément (ou id) object.failure qui sera utilisé autrement. url: l'url à appeler, options: options ajax
créé une instance de cet objet qui appelera l'url donnée en utilisant les options données.
updatecontent()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne au retour de la réponse. elle met à jour l'élément approprié avec le contenu html ou appellera la fonction passée dans l'option insertion. la méthode sera appelée avec deux arguments, l'élément à mettre à jour et la réponse texte.
5-b-7-f. la classe ajax.periodicalupdater
hérite de ajax.base
cette classe instancie et utilise un objet ajax.updater pour rafraichir un élément de la page ou pour effectuer tout autre tâche de ajax.updater. vérifiez la référence de ajax.updater pour plus d'informations.
propriété
type
description
container
objet
cette valeur sera passée directement au constructeur de ajax.updater.
url
string
cette valeur sera passée directement au constructeur de ajax.updater.
frequency
number
intervalle (pas fréquence) entre les mises à jour, en secondes. le défaut est de 2 secondes. ce nombre sera multiplié par le decay courant en appelant l'objet ajax.updater.
decay
number
conserve le niveau de pourrissement (decay) courant quand la tache est ré-éxecutée.
updater
ajax.updater
le dernier objet ajax.updater utilisé.
timer
object
le timer javascript utilisé pour notifier à cet objet l'instant de la prochaine mise à jour.
méthode
type
arguments
description
[constructeur](conteneur, url, options)
constructeur
conteneur: peut être l'id d'un élément, l'élément lui-même ou un objet avec deux propriétés : un élément (ou id) object.success qui sera utilisé en cas de succès de l'appel ajax et un élément (ou id) object.failure qui sera utilisé autrement. url: l'url à appeler, options: options ajax
créé une instance de cet objet qui appellera l'url donnée en utilisant les options données.
start()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne pour démarrer les tâches périodiques.
stop()
instance
(aucun)
arrête l'exécution des tâches périodiques de l'objet. après son arrêt, l'objet appellera la méthode donnée dans l'option oncomplete (le cas échéant).
updatecomplete()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est appelée par l'objet ajax.updater courant à la fin de sa requête. elle permet de prévoir la prochaine exécution.
ontimerevent()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne à l'instant d'une nouvelle mise à jour.
5-b-8. l'objet element
cet objet propose des méthodes utilitaires pour manipuler les éléments du dom.
méthode
type
arguments
description
addclassname(element, nomclasse)
instance
element: un élément ou son identifiant, nomclasse : nom d'une classe css
ajoute le nom de classe donné aux classes appliquées à l'élément donné.
classnames(element)
instance
element: un élément ou son identifiant
retourne un objet element.classnames représentant les noms de classes css associées à l'élément donné.
cleanwhitespace(element)
instance
element: un élément ou son identifiant
supprime tous les noeuds texte enfants de l'élément avec un contenu blanc.
empty(element)
instance
element: un élément ou son identifiant
retourne une valeur boolean indiquant si le corps de l'élément est blanc.
getdimensions(element)
instance
element: un élément ou son identifiant
retourne les dimensions de l'élément. la valeur retournée est un objet avec deux propriétés : height (hauteur) et width (largeur).
getheight(element)
instance
element: un élément ou son identifiant
retourne la hauteur (offsetheight) de l'élément.
getstyle(element, proprietecss)
instance
element: un élément ou son identifiant, proprietecss : le nom d'une propriété css (les formats prop-nom et propnom fonctionnent)
retourne la valeur de la propriété css donnée pour l'élément ou null si la propriété est absente.
hasclassname(element, nomclasse)
instance
element: un élément ou son identifiant, nomclasse : nom d'une classe css
retourne true (vrai) si l'élément a le nom de classe donnée dans les classes qui lui sont appliquées.
hide(elem1 [, elem2 [, elem3 [...]]])
instance
elemn: un élément ou son identifiant
cache chacun des éléments en mettant style.display à 'none'.
makeclipping(element)
instance
element: un élément ou son identifiant
supprime le défilement de l'élément donné.
makepositioned(element)
instance
element: un élément ou son identifiant
change la propriété style.position de l'élément à 'relative'.
remove(element)
instance
element: un élément ou son identifiant
supprime l'élément du document.
removeclassname(element, nomclasse)
instance
element: un élément ou son identifiant, nomclasse : nom d'une classe css
supprime le nom de classe des classes appliquées à l'élément.
scrollto(element)
instance
element: un élément ou son identifiant
fait défiler la fenêtre jusqu'à l'élément donné.
setstyle(element, hashproprietecss)
instance
element: un élément ou son identifiant, hashproprietecss : objet hash avec les styles à appliquer
change les propriétés css de l'élément d'après les valeurs de l'argument hashproprietecss.
show(elem1 [, elem2 [, elem3 [...]]])
instance
elemn: un élément ou son identifiant
affiche chacun des éléments en mettant style.display à ''.
toggle(elem1 [, elem2 [, elem3 [...]]])
instance
elemn: un élément ou son identifiant
inverse la visibilité de chacun des éléments donnés.
undoclipping(element)
instance
element: un élément ou son identifiant
rétablit le défilement de l'élément donné qui avait été supprimé avec makeclipping().
undopositioned(element)
instance
element: un élément ou son identifiant
vide la propriété style.position de l'élément à ''.
update(element, html)
instance
element: un élément ou son identifiant, html : contenu html
remplace le contenu html interne de l'élément avec l'argument html donné. si le html donné contient des blocs <script>, ils ne seront pas inclus, mais évalués.
visible(element)
instance
element: un élément ou son identifiant
retourne une valeur boolean indiquant si l'élément est visible.
5-b-8-a. la classe element.classnames
hérite de enumerable
représente la collection des noms de classes css associées à un élément.
méthode
type
arguments
description
[constructeur](element)
constructeur
element: un élément de l'arbre dom ou son id
créé une instance de cet objet représentant les noms de classes css de l'élément donné.
add(nomclasse)
instance
nomclasse: un élément de l'arbre dom ou son id
ajoute le nom de classe css à la liste des classes appliquées à l'élément.
remove(nomclasse)
instance
nomclasse: un élément de l'arbre dom ou son id
supprime le nom de classe css de la liste des classes appliquées à l'élément.
set(nomclasse)
instance
nomclasse: un élément de l'arbre dom ou son id
associe le classe css à l'élément en supprimant toutes les autres classes css appliquées.
5-b-9. l'objet abstract
cet objet sert de base pour d'autres classes de la bibliothèque. il n'a ni propriétés, ni méthodes. les classes définies dans cet objet sont également traitées comme des classes abstraites traditionnelles.
5-b-9-a. la classe abstract.insertion
cette classe est utilisée comme classe de base pour d'autres classes qui proposent de l'insertion dynamique d'éléments. cette classe est utilisée comme une classe abstraite.
méthode
type
arguments
description
[constructeur](element, contenu)
constructeur
element: un objet élément ou son id, contenu : html à insérer
créé une instance de cet objet qui aidera à l'insertion dynamique du contenu.
contentfromanonymoustable()
instance
(aucun)
propriété
type
nature
description
adjacency
string
statique, paramètre
paramètre qui spécifie comment le contenu sera placé par rapport à l'élément. les valeurs possibles sont : 'beforebegin' (avant le début), 'afterbegin' (après le début), 'beforeend' (avant la fin) et 'afterend' (après la fin).
element
object
instance
l'objet élément par rapport à qui l'insertion sera effectuée.
content
string
instance
le contenu html qui sera inséré.
5-b-10. l'objet insertion
cet objet sert de base pour d'autres classes de la bibliothèque. il n'a ni propriétés, ni méthodes.
5-b-10-a. la classe insertion.before
hérite de abstract.insertion
insère du contenu html avant un élément.
méthode
type
arguments
description
[constructeur](element, contenu)
constructeur
element: un objet élément ou son id, contenu : html à insérer
hérité de abstract.insertion. créé une instance de cet objet qui aidera à l'insertion dynamique du contenu.
le code suivant :
<br>bonjour, <span id="personne" style="color:red;">wiggum. comment ça va?</span>
<script> new insertion.before('personne', 'chef '); </script>
produira le html suivant :
<br>bonjour, chef <span id="personne" style="color:red;">wiggum. comment ça va?</span>
5-b-10-b. la classe insertion.top
hérite de abstract.insertion
insère du contenu html comme premier enfant de l'élément. le contenu sera directement après la balise d'ouverture de l'élément.
méthode
type
arguments
description
[constructeur](element, contenu)
constructeur
element: un objet élément ou son id, contenu : html à insérer
hérité de abstract.insertion. créé une instance de cet objet qui aidera à l'insertion dynamique du contenu.
le code suivant :
<br>bonjour, <span id="personne" style="color:red;">wiggum. comment ça va?</span>
<script> new insertion.top('personne', 'm. '); </script>
produira le html suivant :
<br>bonjour, <span id="personne" style="color:red;">m. wiggum. comment ça va?</span>
5-b-10-c. la classe insertion.bottom
hérite de abstract.insertion
insère du contenu html comme dernier enfant de l'élément. le contenu sera juste avant la balise fermante de l'élément.
méthode
type
arguments
description
[constructeur](element, contenu)
constructeur
element: un objet élément ou son id, contenu : html à insérer
hérité de abstract.insertion. créé une instance de cet objet qui aidera à l'insertion dynamique du contenu.
le code suivant :
<br>bonjour, <span id="personne" style="color:red;">wiggum. comment ça va?</span>
<script> new insertion.after('personne', ' que ce passe-t-il?'); </script>
produira le html suivant :
<br>bonjour, <span id="personne" style="color:red;">wiggum. comment ça va? que ce passe-t-il?</span>
5-b-10-d. la classe insertion.after
hérite de abstract.insertion
insère du contenu html après la balise de fermeture de l'élément.
méthode
type
arguments
description
[constructeur](element, contenu)
constructeur
element: un objet élément ou son id, contenu : html à insérer
hérité de abstract.insertion. créé une instance de cet objet qui aidera à l'insertion dynamique du contenu.
le code suivant :
<br>bonjour, <span id="personne" style="color:red;">wiggum. comment ça va?</span>
<script> new insertion.after('personne', ' etes-vous là?'); </script>
produira le html suivant :
<br>bonjour, <span id="personne" style="color:red;">wiggum. comment ça va?</span> etes-vous là?
5-b-11. l'objet field
cet objet propose des méthodes utilitaires pour travailler avec les champs des formulaires.
méthode
type
arguments
description
clear(champ1 [, champ2 [, champ3 [...]]])
instance
champn: un element champ de formulaire ou son id
supprime la valeur de chacun des champs de formulaire passés.
present(champ1 [, champ2 [, champ3 [...]]])
instance
champn: un element champ de formulaire ou son id
retourne true uniquement si tous les champs de formulaire passés contiennent des valeurs non vides.
focus(champ)
instance
champ: un element champ de formulaire ou son id
déplace le focus sur le champ donné.
select(champ)
instance
champ: un element champ de formulaire ou son id
sélectionne la valeur du champ, si le champ supporte la sélection.
activate(champ)
instance
champ: un element champ de formulaire ou son id
déplace le focus et sélectionne la valeur du champ, si le champ supporte la sélection.
5-b-12. l'objet form
cet objet propose des méthodes utilitaires pour travailler avec les formulaires et leurs champs.
méthode
type
arguments
description
serialize(formulaire)
instance
formulaire: un élément formulaire ou son id
retourne une liste des champs et de leurs valeurs, formatés pour une url, du type 'champ1=valeur1&champ2=valeur2&champ3=valeur3'.
findfirstelement(formulaire)
instance
formulaire: un élément formulaire ou son id
retourne le premier élément champ (non inactif) du formulaire.
getelements(formulaire)
instance
formulaire: un élément formulaire ou son id
retourne une array contenant tous les champs de saisie du formulaire.
getinputs(formulaire[,nomtype[,nom]])
instance
formulaire: un élément formulaire ou son id, nomtype : le type des champs input, nom : le nom du champ
retourne une array contenant tous les éléments <input> du formulaire. la liste peut être éventuellement filtrée sur les attributs type et name.
disable(formulaire)
instance
formulaire: un élément formulaire ou son id
désactive tous les champs du formulaire.
enable(formulaire)
instance
formulaire: un élément formulaire ou son id
active tous les champs du formulaire.
focusfirstelement(formulaire)
instance
formulaire: un élément formulaire ou son id
place le focus sur le premier élément visible et actif du formulaire.
reset(formulaire)
instance
formulaire: un élément formulaire ou son id
réinitialise le formulaire. identique à l'appel de la méthode reset() de l'élément form.
5-b-12-a. l'objet form.element
cet objet propose des méthodes utilitaires pour travailler avec les éléments de formulaires, visibles ou non.
méthode
type
arguments
description
serialize(element)
instance
element: un objet élément ou son id
retourne la paire nom/valeur de l'élément, de type 'nomelement=valeurelement'.
getvalue(element)
instance
element: un objet élément ou son id
retourne la valeur de l'élément.
5-b-12-b. l'objet form.element.serializers
cet objet propose des méthodes utilitaires utilisées en interne pour extraire les valeurs courantes des éléments de formulaire.
méthode
type
arguments
description
inputselector(element)
instance
element: un objet ou son id d'un élément de formulaire ayant la propriété checked comme un bouton radio ou une case à cocher
retourne un array avec le nom et la valeur de l'élément du type ['nomelement', 'valeurelement'].
textarea(element)
instance
element: un objet ou son id d'un élément de formulaire ayant la propriété value comme un champ texte, un bouton ou un champ mot de passe
retourne un array avec le nom et la valeur de l'élément du type ['nomelement', 'valeurelement'].
select(element)
instance
element: un objet élément représentant un select
retourne un array avec le nom de l'élément et toutes les valeurs sélectionnées de l'élément du type ['nomelement', 'optselec1 optselec4 optselec9'].
5-b-13. la classe abstract.timedobserver
cette classe est utilisée comme classe de base pour les autres classes qui surveillent un élément jusqu'à ce que sa valeur (ou toute autre propriété que la classe dérivée définie) change. cette classe est utilisée comme une classe abstraite.
des surclasses peuvent être créées pour surveiller des choses comme la valeur entrée dans un élément ou une des propriétés de style, ou le nombre de lignes dans une table ou tout ce dont vous voulez suivre les changements.
les classes dérivées doivent implémenter la méthode getvalue() pour déterminer la valeur courante surveillée dans cet élément.
méthode
type
arguments
description
[constructeur](element, frequence, rappel)
constructeur
element: un objet élément ou son id, frequence : intervalle en secondes, rappel : méthode appellée quand l'élément change.
créé un objet qui surveillera l'élément.
registercallback()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est appelée par l'objet lui-même pour débuter la surveillance de l'élément.
ontimerevent()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne pour vérifier périodiquement la valeur de l'élément.
propriété
type
description
element
objet
l'élément qui est surveillé.
frequency
number
c'est en fait l'intervalle en secondes entre deux vérifications.
callback
function(object, string)
cette méthode est appelée quand la valeur de l'objet change. elle recevra l'élément et sa nouvelle valeur.
lastvalue
string
la valeur lors de la dernière vérification de l'objet.
5-b-13-a. la classe form.element.observer
hérite de abstract.timedobserver
implémentation d'un abstract.timedobserver qui surveille la valeur des champs d'entrées d'un formulaire. utilisez cette classe quand vous voulez surveiller un élément qui n'a pas d'évènement qui signale le changement de valeur. sinon, vous pouvez utiliser la classe form.element.eventobserver à la place.
méthode
type
arguments
description
[constructeur](element, frequence, rappel)
constructeur
element: un objet élément ou son id, frequence : intervalle en secondes, rappel : méthode appellée quand l'élément change.
hérité de abstract.timedobserver. créé un objet qui surveille la propriété value de l'élément.
getvalue()
instance
(aucun)
retourne la valeur de l'élément.
5-b-13-b. la classe form.observer
hérite de abstract.timedobserver
implémentation d'un abstract.timedobserver qui surveille la valeur de tous les champs d'entrées d'un formulaire. utilisez cette classe quand un des éléments du formulaire n'a pas d'évènement qui signale le changement de valeur. sinon, vous pouvez utiliser la classe form.eventobserver à la place.
méthode
type
arguments
description
[constructeur](element, frequence, rappel)
constructeur
element: un objet élément ou son id, frequence : intervalle en secondes, rappel : méthode appellée quand l'élément change.
hérité de abstract.timedobserver. créé un objet qui surveillera les valeurs des champs de formulaire.
getvalue()
instance
(aucun)
retourne la sérialisation de tous les éléments du formulaire.
5-b-14. la classe abstract.eventobserver
cette classe est utilisée comme classe de base pour d'autres classes qui doivent exécuter une méthode quand un évènement de type changement de valeur survient sur un élément.
plusieurs objets de type abstract.eventobserver peuvent être liés à un même élément, sans qu'ils se détruisent l'un l'autre. les méthodes seront exécutées dans l'ordre d'assignation à l'élément.
l'évènement déclenchant est onclick pour les boutons radio et les checkboxes, onchange pour les champs texte en général et les listes déroulantes.
les classes dérivées doivent implémenter la méthode getvalue() pour déterminer la valeur courante surveillée dans cet élément.
méthode
type
arguments
description
[constructeur](element, rappel)
constructeur
element: un objet élément ou son id, rappel : méthode appelée quand l'élément change.
créé un objet qui surveillera les valeurs des champs de formulaire.
registercallback()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne pour lier l'objet au gestionnaire d'évènement de l'élément.
registerformcallbacks()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. elle est utilisée en interne pour lier l'objet à chacun des éléments du formulaire.
onelementevent()
instance
(aucun)
cette méthode ne doit pas être utilisée en externe. c'est la méthode qui est liée au gestionnaire d'évènement de l'élément.
propriété
type
description
element
objet
l'élément qui est surveillé.
callback
function(object, string)
cette méthode est appelée quand la valeur de l'objet change. elle recevra l'élément et sa nouvelle valeur.
lastvalue
string
la valeur lors de la dernière vérification de l'objet.
5-b-14-a. la classe form.element.eventobserver
hérite de abstract.eventobserver
implémentation d'un abstract.eventobserver qui exécute une méthode sur l'évènement approprié d'un champ de formulaire pour détecter les changements de cet élément. si l'élément n'expose pas de gestionnaire d'évènement qui signale les changements, vous pouvez utiliser la classe form.element.observer à la place.
méthode
type
arguments
description
[constructeur](element, rappel)
constructeur
element: un objet élément ou son id, rappel : méthode appelée quand l'évènement survient.
hérité de abstract.eventobserver. créé un objet qui surveillera la propriété value de l'élément.
getvalue()
instance
(aucun)
retourne la valeur de l'élément.
5-b-14-b. la classe form.eventobserver
hérite de abstract.eventobserver
implémentation d'un abstract.eventobserver qui surveille l'ensemble des champs d'un formulaire à travers leurs gestionnaires d'évènements. si le formulaire contient des champs n'ayant pas de gestionnaire qui signale les changements, vous pouvez utiliser la classe form.observer à la place.
méthode
type
arguments
description
[constructeur](form, rappel)
constructeur
form: un objet formulaire ou son id, rappel : méthode appelée quand l'évènement survient.
hérité de abstract.eventobserver. créé un objet qui surveillera les changements du formulaire.
getvalue()
instance
(aucun)
retourne la sérialisation de tous les champs du formulaire.
version pdf
(miroir)
version hors-ligne
(miroir)
phpmyvisites | open source web analytics
traduction pour http://www.developpez.com par steven k. martin, olivier lance et denis cabasson
du document
developer notes for prototype.js
de sergio pereira.
cet article reste la propriété de l'auteur original.
la copie, modification et/ou distribution par quelque moyen que
ce soit est soumise à l'obtention préalable de l'autorisation de l'auteur.
responsables bénévoles de la rubrique javascript : denis cabasson et brice franzoia - contacter par email :
vos questions techniques : forum d'entraide javascript - publiez vos articles, tutoriels et cours
et rejoignez-nous dans l'équipe de rédaction du club d'entraide des développeurs francophones nous contacter
- copyright © 2000-2007 www.developpez.com - legal informations.
documentation de la librairie prototype, version 1.4.0 - club d'entraide des développeurs francophones Précédent 645 Précédent 644 Précédent 643 Précédent 642 Précédent 641 Précédent 640 Précédent 639 Précédent 638 Précédent 637 Précédent 636 Précédent 635 Précédent 634 Précédent 633 Précédent 632 Précédent 631 Précédent 630 Précédent 629 Précédent 628 Précédent 627 Précédent 626 Précédent 625 Précédent 624 Précédent 623 Précédent 622 Précédent 621 Précédent 620 Précédent 619 Précédent 618 Précédent 617 Précédent 616 Suivant 647 Suivant 648 Suivant 649 Suivant 650 Suivant 651 Suivant 652 Suivant 653 Suivant 654 Suivant 655 Suivant 656 Suivant 657 Suivant 658 Suivant 659 Suivant 660 Suivant 661 Suivant 662 Suivant 663 Suivant 664 Suivant 665 Suivant 666 Suivant 667 Suivant 668 Suivant 669 Suivant 670 Suivant 671 Suivant 672 Suivant 673 Suivant 674 Suivant 675 Suivant 676