Dynamique.js - Documentation module Selector

Ce module est dédié à la sélection d'élément du DOM (Document Object Model). Il peut être utilisé indépendamment de Dynamique.

Contrairement aux régles de sélections CSS 3, les régles proposées par ce module permettent une sélection plus efficace des éléments. Dans le cas où une sélection exploitant uniquement les régles de bases CSS 3 est suffisante, il est préférable d'utiliser le module SelectorQuery à la place, dans un objectif d'optimisation des performances. Celui-ci repose sur la méthode document.querySelectorAll et l'adapte à Dynamique.

Le choix du sélecteur à utiliser avec Dynamique doit être fait en fonction des nécessités réelles et concrètes du projet réalisé. Dans le cas où une sélection d'éléments DOM se ferait uniquement par l'attribut id, l'adaptation de la méthode document.getElementById semble encore plus appropriée que les deux précédentes solutions énoncées.

La documentation de ce module décris les opérateurs et les régles de sélections supportées.

Lorsque Selector est utilisé sans Dynamique, il s'initialise directement sur l'objet window. Il est alors accessible tel que:


							Selector(...);
							// ===
							window.Selector(...);

Lorsque Selector est utilisé avec Dynamique, il s'initialise en tant que module de Dynamique ainsi que comme sélecteur par défaut d'éléments DOM.


							Dynamique("body");	// Selector est appelé en interne par Dynamique

Ce module à pour but de sélectionner un ensemble d'éléments DOM correspondant à un ensemble de régles de recherches donné, dans un contexte et un document donné. Ces régles de recherches sont décrites sous forme de chaine de caractère où certains caractères seront associés à des régles de recherches alors que d'autres à des paramètres à utiliser avec ces régles.

Par exemple, la chaine #monId représente une recherche devant retournée l'ensemble des éléments ayant pour id la valeur monId. Le symbole # demande le filtrage d'éléments par leur attribut id et la chaine monId indique la valeur que doivent avoir les éléments pour être sélectionné.

La sélection des éléments se fait en exploitant deux types de régle: les régles de sélection, qui permettent de sélectionner des éléments, et les régles de filtrage, qui permettent de filtrer des éléments sélectionnés par les régles de sélection.

Les régles de sélection permettent de sélectionner un ensemble d'éléments répondant à des critères se sélection. Le module supporte l'ensemble des régles de sélection suivantes:

Sélecteur d'éléments descendants ou " " (espace): permet la sélection de noeuds descendants, mais pas nécessairement fils direct, d'un élément donné.
- Synthaxe: A B.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "body span" sélectionnera tous les éléments span étant enfant de body. "body span|p" sélectionnera tout les éléments span ou p descendants de body.
Sélecteur d'éléments fils >: permet la sélection de noeuds fils descendants direct d'un élément donné.
- Synthaxe: A > B A>B.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "body > span" sélectionnera tous les fils descendants direct span de body. "body > span|p" sélectionnera tout les fils descendants direct span ou p descendants de body.
Sélecteur de voisin direct +: permet la sélection de noeuds qui suivent immédiatement un élément donné.
- Synthaxe: A + B A+B.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "head + body" sélectionnera tous les éléments body suivant immédiatement l'élément body. "h1 + p|h2" sélectionnera tous les éléments p ou h2 suivant immédiatement l'élément h1.
Sélecteur de voisins ~: permet la sélection de noeuds qui suivent un élément donné et qui ont le même parent.
- Synthaxe: A ~ B A~B.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "head ~ body" sélectionnera tous les éléments body suivant l'élément body. "h1 ~ p|h2" sélectionnera tous les éléments p ou h2 suivant l'élément h1.
Sélecteur de parent -: permet la sélection des parents des éléments donnés.
- Synthaxe: A - B A-B.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "body - html" sélectionnera les parents de body ayant comme parent html. "span - h1|h2" sélectionnera les parents des span ayant comme parent h1 ou h2.
Sélecteur d'enfants direct par numéro de noeuds /: permet la d'enfants direct puis d'immédiatement les filtrer par leur numéro de noeuds.
- Synthaxe: A / B A/B.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "p / 1" sélectionnera les enfants directs de p ayant comme nodeType 1. "p / 1|2" sélectionnera les enfants directs des p ayant comme nodeType 1 ou 2.

Les régles de filtrage permettent de filtrer un ensemble d'éléments. Le module supporte l'ensemble des filtres de sélection suivants:

Filtre de classe .: permet de filtrer les éléments par rapport à leur attribut class. Un élément sera retenu si il possède au moins la ou les classes indiquées.
- Synthaxe: .class.
- Support: Ce sélecteur supporte l'opérateur OU (|), l'opérateur ET (&) et le mot clef *.
- Exemple: ".title" ne retiendra que les éléments ayant au moins la classe title. ".title|title1&title2" sélectionnera les éléments ayant au moins les classes title ou au moins les classes title1 et title2.
Filtre d'identifiant #: permet de filtrer les éléments par rapport à leur attribut id.
- Synthaxe: #id.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "#title" ne retiendra que les éléments ayant un identifiant valant title. "#title1|title2" sélectionnera les éléments ayant un identifiant valant title1 ou title2.
Filtre de nom @: permet de filtrer les éléments par rapport à leur attribut name.
- Synthaxe: @name.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "@firstname" ne retiendra que les éléments ayant un nom valant firstname. "@mail|phone" sélectionnera les éléments ayant un nom valant mail ou phone.
Filtre de numéro de noeud //: permet de filtrer les éléments par rapport à leur numéro de noeud nodeType.
- Synthaxe: //nodeType.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "//1" ne retiendra que les éléments ayant comme numéro de noeud 1. "//1|2" sélectionnera les éléments ayant comme numéro de noeud 1 ou 2.
Filtre de nom de noeud %: permet de filtrer les éléments par rapport à leur attribut nodeName.
- Synthaxe: %nodeName.
- Support: Ce sélecteur supporte l'opérateur OU (|) et le mot clef *.
- Exemple: "%DIV" ne retiendra que les éléments ayant comme nom de noeud DIV. "%'#text'|DIV" sélectionnera les éléments ayant comme nom de noeud #text ou DIV.
Filtre pseudo-classes :: permet de filtrer les éléments par rapport à une information d'état qui n'est pas stocké dans l'arbre du document.
- Synthaxe: :pseudo-classe.
- Support: Ce sélecteur supporte l'opérateur OU (|) et l'opérateur ET (&).
- Exemple: ":root" ne retiendra que l'élément étant la racine du document.
- Pseudo-classes supportées:
  - root: cible la racine de l'arbre représentant le document;
  - nth-child(an+b): cible un élément qui possède an+b-1 éléments voisins (au même niveau) avant lui dans l'arbre du document pour des valeurs entières n incrémenté à partir de 0 et qui possède un élément parent. Le mot clef odd peut être utilisé pour représenter les éléments impaires et le mot clef event pour représenter les éléments paires.
  - nth-int-child(a1,b1[,...aN,bN]): cible un élément dont la position est dans un des intervals donnés. Le mot clef + ou - peuvent être utilisés pour représenter respectivement +Infinity et -Infinity.
  - nth-last-child(an+b): cible un élément qui possède an+b-1 éléments frères qui le suivent au même niveau dans l'arbre du document pour des valeurs entières n incrémenté à partir de 0 et qui possède un élément parent. Le mot clef odd peut être utilisé pour représenter les éléments impaires et le mot clef event pour représenter les éléments paires.
  - nth-of-type(x): cible des éléments d'un type donné, en fonction de leur position au sein d'un groupe de frères et soeurs. Le mot clef odd peut être utilisé pour représenter les éléments impaires et le mot clef event pour représenter les éléments paires.
  - nth-int-type(a1,b1[,...aN,bN]): cible des éléments d'un type donné dont de leur position au sein d'un groupe de frères et soeurs est comprise dans un des intervals donnés. Le mot clef + ou - peuvent être utilisés pour représenter respectivement +Infinity et -Infinity.
  - nth-last-of-type(an+b): cible les éléments qui possède an+b-1 noeuds frères étant les mêmes éléments et qui le suivent dans l'arbre du document pour des valeurs entières de n incrémenté à partir de 0 et qui possède le même élément parent. Le mot clef odd peut être utilisé pour représenter les éléments impaires et le mot clef event pour représenter les éléments paires.
  - first-child: cible les éléments qui sont les premiers éléments fils par rapport à leur élément parent, en tenant compte les noeuds non-éléments.
  - last-child: cible les éléments qui sont les derniers éléments fils par rapport à leur élément parent, en tenant compte les noeuds non-éléments.
  - first-element: cible les éléments qui sont les premiers éléments fils par rapport à leur élément parent, en ne tenant pas compte des noeuds non-éléments.
  - last-element: cible les éléments qui sont les derniers éléments fils par rapport à leur élément parent, en ne tenant pas compte des noeuds non-éléments.
  - first-of-type: cible les éléments qui sont les premiers éléments fils par rapport à leur élément parent, en ne tenant pas compte des noeuds non-éléments, parmis les éléments ayant le même nodeName.
  - last-of-type: cible les éléments qui sont les derniers éléments fils par rapport à leur élément parent, en ne tenant pas compte des noeuds non-éléments, parmis les éléments ayant le même nodeName.
  - only-of-type: cible les éléments qui sont les seuls fils de leur élément parent, en ne tenant pas compte des noeuds non-éléments, à avoir ce nodeName.
  - only-child: cible les éléments qui sont les seuls fils de leur élément parent, en ne tenant pas compte des noeuds non-éléments.
  - only-node: cible les éléments qui sont les seuls fils de leur élément parent, en tenant compte des noeuds non-éléments.
  - empty: cible les éléments qui n'ont pas d'éléments fils.
  - empty-node: cible les éléments qui n'ont pas de noeuds fils.
  - target: cible l'unique élément (s'il existe) dont l'attribut id correspond au fragment d'identifiant de l'URI du document.
  - lang(x): cible les éléments visible, dont l'attribut lang est égal à x.
  - hidden: cible les éléments cachés, dont l'attribut hidden vaut true.
  - enabled: cible les éléments activés, dont l'attribut enabled vaut true.
  - disabled: cible les éléments désactivés, dont l'attribut enabled vaut false.
  - checked: cible les éléments cochés, dont l'attribut checked vaut true.
  - unchecked: cible les éléments non-cochés, dont l'attribut checked vaut false.
  - indeterminate: cible les éléments qui sont dans un état indéterminé (ni-coché, ni non-coché), dont l'attribut indeterminate vaut true.
  - valid: cible les éléments valides, dont l'attribut validity.valid vaut true.
  - contains(x): cible les éléments dont le contenu contient x, en étant insenssible à la casse.
  - contains-exactly(x): cible les éléments dont le contenu contient x, en étant senssible à la casse.
  - focus: cible les éléments qui ont l'attention de l'utilisateur (focus).
  - hover: cible les éléments qui sont survolés (hover).
  - load: cible les éléments dont leur ressource à finie de charger (load).
Filtre par attributs et propriétés [: permet de filtrer les éléments par rapport à la valeur de leurs attributs ou propriétés.
- Synthaxe: [attr operator value].
- Caractère fermant: ].
- Support: Ce sélecteur supporte l'opérateur OU (|), ET (|), OU (||), ET (&&) et le mot clef *. Il tient également compte des guillemets simple et double ' ".
- Exemple: "[id = monId]" ne retiendra que les éléments ayant comme propriétés id la valeur monId. "[a.b|a = h.g|t && f = g || y = o]".
- Opérateurs supportés:
  - ou "" (aucun opérateur): vérifie si la propriété vaut true ou si elle vaut false ou équivalent ("", 0, undefined etc...).
  - #=: vérifie si le type de la propriété est égale à la valeur donné.
  - /=: vérifie si la valeur de la propriété correspondant à l'expresson régulière donnée.
  - =: vérifie si la valeur de la propriété est égale à la valeur donnée.
  - !=: vérifie si la valeur de la propriété n'est pas égale à la valeur donnée.
  - >: vérifie si la valeur de la propriété est supérieur à la valeur donnée.
  - : vérifie si la valeur de la propriété est inférieur à la valeur donnée.
  - >=: vérifie si la valeur de la propriété est supérieur ou égale à la valeur donnée.
  - : vérifie si la valeur de la propriété est inférieur ou égale à la valeur donnée.
  - a,b: vérifie si la valeur de la propriété est dans l'interval a,b donné.
  - ~=: vérifie si, dans la valeur de la propriété, la valeur donnée entourée par des espaces est présente.
  - ^=: vérifie si la valeur de la propriété commence par la valeur donnée.
  - $=: vérifie si la valeur de la propriété termine par la valeur donnée.
  - *=: vérifie si la valeur de la propriété contient au moins une fois la valeur donnée (senssible à la casse).
  - %=: vérifie si la valeur de la propriété contient au moins une fois la valeur donnée (insenssible à la casse).
  - |=: vérifie si la valeur de la propriété contient exactement la valeur donnée ou dont si la valeur de la propriété commence par la valeur donnée suivi d'un tiret -.

Les régles annexes sont des régles qui ne peuvent être considéré ni comme des régles de sélections, ni comme des régles de filtrage. Les régles annexes sont les suivantes:

Nouvelle recherche ,: permet d'effectuer plusieurs recherches dans une seule chaine de recherche. Les éléments trouvés seront ajoutés aux éléments précédemment trouvés.
- Synthaxe: rule, rule.
- Exemple: "body > div, a" sélectionnera les éléments div étant enfants directs de body et l'ensemble des éléments a du document.
Nouvelle recherche à partir des résultats précédents ;: permet d'effectuer une nouvelle recherche à partir des éléments précédemment sélectionnés. Les éléments trouvés seront ajoutés aux éléments précédemment trouvés.
- Synthaxe: rule; rule.
- Exemple: "body > div; a" sélectionnera les éléments div étant enfants directs de body et l'ensemble des éléments a étant dans les éléments div précédemment trouvés.
Bulle de recherche : permet d'effectuer une nouvelle recherche. Les éléments trouvés seront ajoutés aux éléments précédemment trouvés puis la recherche pourra continuer sur l'ensemble des ces éléments.
- Synthaxe: rule .
- Caractère fermant: >.
- Opérateur supporté: L'opérateur $$ est supporté. Si $$ est utilisé, la recherche commencera à partir des éléments précédemment trouvés.
- Exemple: "body > div span" sélectionnera les éléments div étant enfants directs de body, l'ensemble des éléments h1 puis l'ensemble des éléments span étant dans tout les éléments trouvés précédemment.

Module Selector

Accessibilité

Sélecteurs et filtres

Régles de sélection

Régles de filtrage

Autres régles annexes

Compatibilité

Dépendances