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 œuvre dans cette librairie.
I. 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.
I-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.
I-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.
I-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();" >I-D. Utilisation de la fonction $H()▲
La fonction $H() convertit les objets en objets Hash énumérables qui s'apparentent à des tableaux associatifs.
I-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.
I-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 a é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.
II. 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 œuvre 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.
II-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} représente 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>II-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.
III. Énumé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.
III-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.
III-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 parti 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.
IV. 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é.
|
|
|
|
|
V. Référence de prototype.js▲
V-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.
V-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. |
V-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. |
<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()">V-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:
<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>V-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) |
évalue 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. |
V-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. |
V-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é. |
V-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.
V-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.
V-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. |
V-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. |
V-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] ] ». |
V-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. |
V-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érieure, 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. |
V-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. |
V-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. |
V-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é. |
V-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(). |
V-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. |
V-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. |
V-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 appellera 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. |
V-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 toute 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 |
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. |
V-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 nœuds 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. |
V-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. |
V-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.
V-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é. |
V-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.
V-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 :
V-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 :
V-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ée 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 :
V-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ée 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 :
V-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. |
V-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. |
V-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. |
V-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']. |
V-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 appelé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. |
V-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 appelé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. |
V-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 appelé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. |
V-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. |
V-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. |
V-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. |