Dans cette page, je présente la fonction globale de jQuery qui s'écrit soit jQuery() ou plus simplement $(). Elle prend deux arguments: un sélecteur et un contexte et elle créé des objets jQuery. J'explique qu'elle a des fonctions différentes selon la nature du premier argument qui peut être soit un sélecteur, un élément du DOM ou une chaîne de caractères. Finalement, je donne une idée de ce qu'est la chaînabilité.
La bibliothèque jQuery définit une seule fonction globale: jQuery() ou son alias $(). Comme toutes les fonctions JavaScript, elle accepte des paramètres, et renvoie un objet spécial que nous appellerons par la suite "objet jQuery". Cet objet n'est pas un élément du DOM mais bien un tableau d'éléments DOM (même dans le cas où il n'existe qu'un seul) auxquels on peut accéder en utilisant la notation [] des tableaux.
jQuery() ou $()
Elle est au centre de jQuery et peut prendre plusieurs sortes d'arguments: un sélecteur CSS, un élément du DOM ou une chaîne HTML. C'est cette fonction qui cré les objets jQuery. Elle peut prendre deux arguments quoiqu'habituellement, elle soit utilisée avec un seul.
jQuery() et $() sont les deux seuls symboles définis dans l'espace de nom de jQuery.
Note importante
L’utilisation de « jQuery » plutôt que « $ » assure il n’y aura pas de conflits avec d’autres bibliothèques JavaScript.
Voyons maintenant de quelles façons cette fonction globale est utilisée.
$(«sélecteur CSS», [«contexte»])
Lorsqu'elle est appelée avec un sélecteur CSS comme paramètre, elle retourne l'ensemble de tous les éléments du DOM correspondant au sélecteur. jQuery supporte la plupart des sélecteurs CSS3 en plus de quelques extensions qui lui sont propres (voir Les sélecteurs jQuery ou jQuery Selectors pour plus de détails).
Par exemple, voici comment on pourrait sélectionner tous les éléments <div> d'un document:
var divs = $("div");
ou encore comment on pourrait sélectionner tous les éléments <a> ayant la classe "trigger":
var a = $('a.trigger");
Considérons maintenant un autre exemple:
$('p.ext').css("background-color", "blue").show("fast");
dans lequel on sélectionne tous les éléments <p> de classe="ext" du document et on modifie son CSS pour que l'affichage du fond soit bleu. Cependant, on fait plus. Comme on veut faire apparaître l'objet $('p.ext'), on peut enchaîner avec .show("fast"). C'est le chaînage des méthodes.
$() peut aussi accepter un deuxième paramètre optionnel qui peut être un élément du DOM ou un objet jQuery. La fonction retourne alors tous les éléments correspondant au sélecteur qui sont des descendants de l'objet inscrit comme deuxième paramètre comme dans l'exemple suivant:
var x = $("a.classe1", "p#nav")
où on sélectionne tous les éléments <a> de classe "classe1" descendants de l'élément <p> d'ID = "nav".
$(«élément du DOM», [«contexte»])
On peut aussi lui passer un élément du DOM ou un objet fenêtre comme premier paramètre. Dans ce cas, elle enveloppe l'élément, le document ou la fenêtre dans un objet jQuery et retourne cet objet. Il est assez commun de voir des appels comme $(document) ou $(this).
Une des principales utilisation de cette façon de faire consiste à s'assurer que la page qui se charge est prête à exécuter des instructions jQuery de façon sécuritaire et que le DOM peut être manipulé. C’est pourquoi on encapsule souvent l’ensemble du code écrit en jQuery dans les énoncés suivants:
$(document).ready(function()
// saisir le code ici
});
où $(document).ready() permet de définir les instructions javascript à exécuter dès que le html et le script qui contient l’appel à $(document).ready() est chargé. Cette fonction n’attend pas la fin du chargement de tous les éléments de la page (css, images, autres js…).
Techniquement parlant,
le "handler" passé à la fonction ready() reçoit l'assurance d'être exécuté lorsque le DOM est prêt.
On peut aussi considérer les exemples suivants:
$( document.body.children[0] );
où on cré un objet jQuery à partir d'un élément du DOM, ou
var paragraph = $('p');
$('a', paragraph );
où on fait une sélection à l'intérieur d'une autre sélection. On voit ici l'utilisation d'un second paramètre optionnel pour $().
$(«chaîne HTML», [«contexte»])
Lorsque le premier paramètre de $() est une chaîne HTML, la fonction cré un ou plusieurs élément HTML décrits par cette chaîne et retourne un objet jQuery le représentant. La function $() est alors uniquement un créateur d'objet jQuery. l'objet jQuery est en mémoire mais il n'est pas automatiquement inséré dans le document. Comme on va le voir plus tard, il existe diverses méthodes en permettant l'insertion.
Notons aussi que cette façon de faire ne permet pas de passer du texte brut à la fonction car $() va alors interpréter ce texte comme un sélecteur. Il faut absolument que la chaîne passée à la fonction contienne une balise HTML.
Chaînabilité
jQuery est construit d'une manière telle qu'il permet à ses méthodes de s'enchaîner les unes les autres. Ce chaînage est possible parce que toutes ces méthodes retournent l'objet jQuery généré par la fonction $().
Ainsi, au lieu d'écrire
$(".classe1").append(" un texte");
$(".classe1").css("border","1px solid red");
$(".classe1").addClass("classe2");
$(".classe1").removeClass("toto");
on écrira
$(".classe1").append(" un texte").css("border","1px solid red").addClass("classe2").removeClass("classe1");
Voic un exemple de code "chaîné" utilisé pour afficher des bulles sur les pages de ce site:
$('.trigger').mouseover(function() // Événement "OnMouseOver"
{
$("<div/>", { // définit un contenant pour la bulle
id: "tooltip",
css: {
display: "none",
position: "absolute",
border: "3px solid #111",
color: "#000",
padding: "5px",
opacity: 1.0,
fontSize: "15pt",
backgroundColor: "#fff",
borderRadius: "15px",
zIndex: 3000
}
}).appendTo(this);
$("#tooltip").html($(this).attr('title')); // passe l'attribut "title" au conteneur de la bulle
$(this).attr('title',''); // vider le titre de l'ancre (évite la réaction par défaut du fureteur)
$('#tooltip').show(); // afficher la bulle
}).mousemove(function(e) // événement "OnMouseMove"
{
$('#tooltip').css('top', e.pageY + 20); // la bulle se trouve 20px sous le pointeur de la souris
$('#tooltip').css('left', e.pageX - 20); // la bulle se trouve 20 px à droite du pointeur de la souris
}).mouseout(function() // Évenement "OnMouseOut"
{
$(this).attr('title',$('#tooltip').html()); // remet l'attribut "title" à sa place
$(this).children('div#tooltip').remove(); // se débarrasse du contenant de la bulle
});
Pour le moment, on va laisser de côté les événements, méthodes et fonctions pour se concentrer sur les sélecteurs de jQuery qui sont décrits dans la prochaine page de mes notes.