La bibliothèque JavaScript RootJS propose une liste de classes permettant de faciliter :
- les requêtes Ajax
- la manipulation des éléments du DOM :
- recherche
- ajouts, suppressions
- gestion des classes et des styles
- gestion des attributs
- gestion des événements
- gestion du défilement
- Installation
- Documentation
- Initialisation
- Requête Ajax
- ElementRJS
- searchOne
- searchList
- retrieve
- sameElement
- getPrevious
- getNext
- getParent
- getChild
- getChildren
- getLast
- hasClass
- addClass
- addClasses
- removeClass
- getProperty
- setProperty
- constructor
- addElement
- remove
- removeChild
- removeChildren
- addEvent
- fireEvent
- getStyle
- setStyles
- getOuterDimension
- computeOffset
- changeScroll
Vous pouvez récupérer le fichier root.js dans /resources/scripts/root.js. Vous pouvez ensuite charger le fichier comme vous le faites pour d'autres fichiers JavaScript :
<script src="root.js"></script>Le fichier définit des classes sans exécuter de code.
Vous pouvez définir la fonction initRootJS pour commencer à utiliser RootJS :
window.initRootJS = function() {
console.log("Initialisation.");
};Pour initialiser RootJS, vous pouvez utiliser le code suivant :
document.addEventListener("DOMContentLoaded", function() {
(new ControllerRJS()).execute();
}, false);Une fois le document chargé, RootJS sera initialisé et la fonction initRootJS sera exécutée. Vous n'êtes pas obligés d'appeler la fonction d'initialisation de RootJS, mais cela permet d'avoir un seul point d'entrée.
La classe AjaxRequestRJS permet d'exécuter une requête en Ajax. Le constructeur d'une requête prend en entrée un objet JSON.
Méthode
constructor(options)
Paramètre
object options : objet JSON des paramètres de la requête.
string url : adresse à appeler.
string method : méthode HTTP à utiliser. Par défaut, la valeur est get. Les méthodes get et post sont autorisées.
object params : objet JSON des paramètres à transmettre en Ajax.
function onComplete : fonction à appeler lorsque l'appel est terminé.
function onSuccess : fonction à appeler lorsque la réponse renvoie un code HTTP 200. Prend en entrée la réponse de l'appel.
function onError : fonction à appeler lorsqu'une erreur s'est produite lors de l'appel. Prend en entrée la réponse de l'appel.
new AjaxRequestRJS({
"url": "https://www.something.unk/",
"method": "post",
"params": {
"param1": 10,
"param2": "test",
"param3": true
},
"onComplete": function() {
console.log("Appel terminé.");
},
"onSuccess": function(response) {
console.log("Appel réussi.");
},
"onError": function(response) {
console.log("Echec de l'appel.");
}
}); La classe JsonAjaxRequestRJS permet de gérer un appel Ajax dont la réponse doit renvoyer du JSON. L'appel reste identique à la classe AjaxRequestRJS, il suffit d'utiliser la classe JsonAjaxRequestRJS à la place de la classe AjaxRequestRJS.
Méthode
constructor(options)
Paramètre
object options : objet JSON des paramètres de la requête.
string url : adresse à appeler.
string method : méthode HTTP à utiliser. Par défaut, la valeur est get. Les méthodes get et post sont autorisées.
object params : objet JSON des paramètres à transmettre en Ajax.
function onComplete : fonction à appeler lorsque l'appel est terminé.
function onSuccess : fonction à appeler lorsque la réponse renvoie un code HTTP 200. Prend en entrée la réponse de l'appel.
function onError : fonction à appeler lorsqu'une erreur s'est produite lors de l'appel. Prend en entrée la réponse de l'appel.
La classe UploadAjaxRequestRJS permet de faire un appel Ajax de téléchargement de fichier. La réponse doit être au format JSON.
Méthode
constructor(options)
Paramètre
object options : objet JSON des paramètres de la requête.
string url : adresse à appeler.
object params : objet JSON des paramètres à transmettre en Ajax.
function onComplete : fonction à appeler lorsque l'appel est terminé.
function onSuccess : fonction à appeler lorsque la réponse renvoie un code HTTP 200. Prend en entrée la réponse de l'appel.
function onError : fonction à appeler lorsqu'une erreur s'est produite lors de l'appel. Prend en entrée la réponse de l'appel.
function onProgress : fonction à appeler pour évaluer la progression du téléchargement. La fonction prend en paramètre un événement de type progress.
<input type="file" />let inputFile = ElementRJS.searchOne("input[type=file]");
inputFile.addEvent("change", function() {
let formData = {
file: ElementRJS.retrieve(this).getProperty("files")[0]
};
new UploadAjaxRequestRJS({
"url": "upload.php",
"params": formData,
"onProgress": function(event) {
let percent = 100 * ((event.total != 0) ? (event.loaded / event.total) : 0);
console.log(percent + " % téléchargé.");
},
"onComplete": function() {
console.log("Fichier téléchargé.");
},
"onSuccess": function(response) {
console.log("Succès.");
},
"onError": function(response) {
console.log(response);
}
});
}); La classe ElementRJS permet de rechercher, ajouter et supprimer des éléments HTML au document. Il est aussi possible d'attacher et de déclencher des événements aux éléments.
La méthode statique searchOne permet de récupérer un élément du DOM. La méthode prend en entrée un sélecteur accepté par la méthode querySelector. Le deuxième paramètre peut être omis. Il permet de préciser l'élément parent de celui recherché. Par défaut le parent est document. Si l'élément a été trouvé, la méthode retourne un objet ElementRJS, null sinon.
Méthode
static searchOne(selector, root)
Paramètres
string selector : sélecteur relatif à root de l'élément recherché.
ElementRJS root : élément racine à partir duquel s'effectut la recherche.
Retour
ElementRJS | null
<div class="page">
<div class="menu">
<ul>
<li>Element 1</li>
<li class="selected">Element 2</li>
</ul>
</div>
</div> let elementSelected = ElementRJS.searchOne("div.menu ul li.selected"); Le code précédent sélectionne l'élément li avec la classe selected.
La méthode statique searchList permet de récupérer un tableau d'éléments du DOM. La liste des paramètres est la même que celle de la méthode searchOne. La méthode retourne un tableau d'objets ElementRJS.
Méthode
static searchList(selector, root)
Paramètres
string selector : sélecteur relatif à root des éléments recherchés.
ElementRJS root : élément racine à partir duquel s'effectut la recherche.
Retour
Array<ElementRJS>
<div class="page">
<div class="menu">
<ul>
<li>Element 1</li>
<li class="selected">Element 2</li>
</ul>
</div>
</div> let
menu = ElementRJS.searchOne("div.menu"),
menuItems = ElementRJS.searchList("li", menu)
; Le code précédent sélectionne tous les éléments li de div.menu. Vous pouvez ensuite utiliser la méthode forEach des tableaux pour parcourir la liste :
menuItems.forEach(function(li) {
console.log(li);
}); Dans certains cas vous aurez besoin de recupérer un objet ElementRJS alors que vous n'aurez qu'un élément HTMLElement. Cela peut être le cas lors de la gestion d'événement. Avec la méthode ElementRJS.retrieve, vous récupérez un objet ElementRJS qui vous permettra de manipuler l'objet. La méthode renvoie null si l'objet n'a pas été trouvé.
Méthode
static retrieve(htmlElement)
Paramètre
HTMLElement htmlElement : objet natif HTMLElement du DOM.
Retour
ElementRJS | null
<a href="#" title="">Lien</a>ElementRJS.searchOne("a").addEvent("click", function(event) {
let anchor = ElementRJS.retrieve(this);
}); L'exemple précédent récupére l'objet ElementRJS correspond à l'ancre.
La méthode sameElement vous permet de vérifier qu'un élément correspond à l'élément courant.
Méthode
sameElement(element)
Paramètre
ElementRJS element : élément à comparer.
Retour
bool
<a href="#" title="">Lien</a>
<p>Texte</p>let anchor = ElementRJS.searchOne('a'),
pararagh = ElementRJS.searchOne('p'),
isSameAnchor = anchor.sameElement(ElementRJS.searchOne('a')),
isNotSameAnchor = anchor.sameElement(ElementRJS.searchOne('p'))
;L'exemple précédent stocke true dans la variable isSameAnchor et false dans la variable isNotSameAnchor.
La méthode getPrevious vous permet de récupérer l'élément précédent du même parent que l'élément courant. La méthode prend en entrée un sélecteur et retourne un objet ElementRJS si l'élément a été trouvé, null sinon.
Méthode
getPrevious(selector)
Paramètre
string selector : correspond au sélecteur de l'élément précédent recherché.
Retour
ElementRJS | null
<ul class="one">
<li class="first">First</li>
<li class="second">Second</li>
</ul>
<ul class="two">
<li class="first">Third</li>
<li class="second">Fourth</li>
</ul> let
element = ElementRJS.searchOne("ul.two li.second"),
previous = element.getPrevious("li")
; Cet exemple sélectonne le dernier élément li (avec le texte Fourth), et récupére l'élément li précédent (avec le texte Third).
La méthode getNext permet de récupérer l'élément suivant du même parent que l'élément courant. La méthode prend en entrée un sélecteur et retourne un objet ElementRJS si l'élément a été trouvé et null sinon.
Méthode
getNext(selector)
Paramètre
string selector : correspond au sélecteur de l'élément suivant recherché.
Retour
ElementRJS | null
<ul class="one">
<li class="first">First</li>
<li class="second">Second</li>
</ul>
<ul class="two">
<li class="first">Third</li>
<li class="second">Fourth</li>
</ul> let element = ElementRJS.searchOne("ul.one li.first"),
next = element.getNext("li")
; Cet exemple sélectionne le premier élément li (avec le texte First), et récupére l'élement li suivant (avec le texte Second).
La méthode getParent permet de retourner l'élément parent dont le sélecteur est donné en paramètre. La méthode retourne un objet ElementRJS si le parent a été trouvé et null sinon.
Méthode
getParent(selector)
Paramètre
string selector : correspond au sélecteur du parent recherché.
Retour
ElementRJS | null
<div class="page">
<div class="menu">
<ul>
<li>Element 1</li>
<li class="selected">Element 2</li>
</ul>
</div>
</div> let
element = ElementRJS.searchOne("ul li.selected"),
parent = element.getParent("div.page")
; L'exemple précédent sélectionne l'élément li.selected et récupére l'élément div.page parent.
La méthode getChild permet de retourner l'enfant dont le sélecteur est fourni en paramètre. La méthode est similaire à la méthode searchOne : c'est comme si cette méthode était appelée avec l'élément courant en deuxième paramètre.
Méthode
getChild(selector)
Paramètre
string selector : correspond au sélecteur de l'enfant recherché.
Retour
ElementRJS | null
<div class="page">
<div class="menu">
<ul>
<li>Element 1</li>
<li class="selected">Element 2</li>
</ul>
</div>
</div> let
parent = ElementRJS.searchOne("div.menu"),
child = parent.getChild("li")
; L'exemple précédent sélectionne le premier enfant li (avec le texte Element 1) de l'élément div.menu.
La méthode getChildren permet de récupérer un tableau des enfants dont le sélecteur est fourni en paramètre. La méthode est similaire à la méthode searchList : c'est comme si cette méthode était appelée avec l'élément courant en deuxième paramètre.
Méthode
getChildren(selector)
Paramètre
string selector : correspond au sélecteur des enfants recherchés.
Retour
Array<ElementRJS>
<div class="page">
<div class="menu">
<ul>
<li>Element 1</li>
<li class="selected">Element 2</li>
</ul>
</div>
</div> let
parent = ElementRJS.searchOne("div.menu"),
elements = parent.getChildren("ul li")
; L'exemple précédent sélectionne tous les li de l'élément div.menu.
La méthode getLast retourne le dernier enfant correspondant au sélecteur en paramètre. Retourne un objet ElementRJS si l'élément a été trouvé, null sinon.
Méthode
getLast(selector)
Paramètre
string selector : correspond au sélecteur recherché.
Retour
ElementRJS | null
<div class="page">
<div class="menu">
<ul>
<li>Element 1</li>
<li class="selected">Element 2</li>
</ul>
</div>
</div> let
parent = ElementRJS.searchOne("div.menu"),
lastElement = parent.getLast("ul li")
; L'exemple précédent sélectionne le dernier li (avec le texte Element 2) de l'élément div.menu.
La méthode hasClass permet de vérifier si l'objet courant posséde la classe fournit en paramètre. Le paramètre en entrée doit être une chaine de caractères. La méthode retourne un booléen : true si la classe est présente, false sinon.
Méthode
hasClass(className)
Paramètre
string className : nom de la classe à vérifier.
Retour
bool
<a href="#" class="link" title="">Lien</a>let
anchor = ElementRJS.searchOne("a"),
hasTargetClass = anchor.hasClass("target"),
hasLinkClass = anchor.hasClass("link")
; Dans l'exemple précédent, hasTargetClass vaut false et hasLinkClass vaut true.
La méthode addClass permet d'ajouter la classe donnée en paramètre à l'objet courant, s'il ne l'a pas déjà. Le paramètre en entrée doit être une chaine de caractères. La méthode retourne l'objet courant.
Méthode
addClass(className)
Paramètre
string className : nom de la classe à ajouter.
Retour
ElementRJS : l'élément courant.
<a href="#" class="link" title="">Lien</a>let anchor = ElementRJS.searchOne("a");
anchor.addClass("target"); Dans l'exemple précédent, la classe target a été ajouté à anchor.
La méthode addClasses permet d'ajouter plusieurs classes à l'objet courant. Le paramètre en entrée doit être un tableau de chaines de caractères. La méthode retourne l'objet courant.
Méthode
addClasses(classes)
Paramètre
Array<string> classes : tableau des classes à ajouter.
Retour
ElementRJS : l'élément courant.
<a href="#" title="">Lien</a>let anchor = ElementRJS.searchOne("a");
anchor.addClasses([ "link", "target" ]); Dans l'exemple précédent, les classes link et target ont été ajouté à anchor.
La méthode removeClass permet de retirer la classe en paramètre de l'objet. Le paramètre en entrée doit être une chaine de caractères. La méthode retourne l'objet courant.
Méthode
removeClass(classToDelete)
Paramètre
string classToDelete : nom de la classe à supprimer.
Retour
ElementRJS : l'élément courant.
<a href="#" class="link" title="">Lien</a>let anchor = ElementRJS.searchOne("a");
anchor.removeClass("link"); Dans l'exemple précédent, la classe link a été enlevée de l'élément anchor.
La méthode getProperty retourne la valeur dont la propriété est donnée en paramètre. Le paramètre en entrée doit être une chaine de caractères. La méthode retourne la valeur si elle a été trouvée et null sinon.
Méthode
getProperty(property)
Paramètre
string property : nom de la propriété à récupérer.
Retour
mixed | null : valeur de la propriété.
<p data-type="paragraph">Texte</p>let
element = ElementRJS.searchOne("p"),
elementType = element.getProperty("data-type"),
elementText = element.getProperty("text")
; Dans l'exemple précédent, la variable elementType vaut paragraph, la variable elementText vaut Texte.
La méthode setProperty permet de changer la valeur d'une propriété. Le premier paramètre correspond à la propriété, le deuxième à la valeur. La méthode retourne l'objet courant.
Méthode
setProperty(property, value)
Paramètres
string property : nom de la propriété à modifier.
mixed value : valeur de la propriété.
Retour
ElementRJS : l'élément courant.
<p data-type="paragraph">Texte</p>let element = ElementRJS.searchOne("p");
element.setProperty("data-modified", 1);
element.setProperty("text", "Texte modifié"); Dans l'exemple précédent, le texte du paragraphe a été modifié et la propriété data-modified a été affectée.
La méthode setProperty permet de changer la valeur d'une propriété. Le premier paramètre correspond à la propriété, le deuxième à la valeur. La méthode retourne l'objet courant.
Méthode
setProperty(property, value)
Paramètres
string property : nom de la propriété à modifier.
mixed value : valeur de la propriété.
Retour
ElementRJS : l'élément courant.
<p data-type="paragraph">Texte</p>let element = ElementRJS.searchOne("p");
element.setProperty("data-modified", 1);
element.setProperty("text", "Texte modifié"); Dans l'exemple précédent, le texte du paragraphe a été modifié et la propriété data-modified a été affectée.
Le premier paramètre du constructeur d'un objet ElementRJS est le nom de la balise HTML (a, p, table...). Le deuxième paramètre est un objet JSON des propriétés à affecter à la balise.
Méthode
constructor(tagName, attributes, htmlElement)
Paramètres
string tagName : nom de la balise (a, img, p).
object attributes : objet JSON des propriétés de la balise.
HTMLElement htmlElement : objet HTMLElement utilisé pour instancier un objet ElementRJS (utilisé par la méthode retrieve).
let element = new ElementRJS("div", {
"class": "menu"
}); La méthode addElement permet d'ajouter un élément au DOM. Le premier paramètre est l'élément à ajouter à l'élément courant. Le deuxième paramètre est la position où placer l'élément par rapport à l'élément courant. Les positions disponibles sont before, after, top et bottom. Par défaut, l'élément sera ajouté après le dernier enfant de l'élément courant.
Méthode
addElement(element, position)
Paramètre
ElementRJS element : objet ElementRJS à ajouter.
string position : position où ajouter l'élément en paramètre par rapport à l'objet courant. Les valeurs before, after, top et bottom sont autorisées.
Retour
ElementRJS : l'élément courant.
<div class="menu">
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div> let
ul = ElementRJS.searchOne("div.menu ul"),
menuItem = new ElementRJS("li", {
"class": "selected",
"text": "Nouveau menu"
})
;
ul.addElement(menuItem, "top"); L'exemple précédent ajoute un élément li en première position au menu.
La méthode remove permet de supprimer l'élément courant du DOM.
<div class="page">
<p>Texte</p>
</div> let element = ElementRJS.searchOne("p");
element.remove(); Dans l'exemple précédent, la balise p a été supprimée.
La méthode removeChild permet de supprimer l'objet ElementRJS donné en paramètre de l'élément courant.
Méthode
removeChild(element)
Paramètre
ElementRJS element : objet ElementRJS à supprimer.
Retour
ElementRJS : l'élément courant.
<div class="menu">
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div>let
menu = ElementRJS.searchOne("div.menu"),
li = menu.getChild("li")
;
menu.removeChild(li); Dans l'exemple précédent, le premier élément li a été supprimé.
La méthode removeChildren supprime tous les enfants de l'élément courant.
Méthode
removeChildren()
Retour
ElementRJS : l'élément courant.
<div class="menu">
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div> let ul = ElementRJS.searchOne("div.menu ul");
ul.removeChildren(); Dans l'exemple précédent, tous les éléments li ont été supprimés.
La méthode addEvent permet d'ajouter un événement à l'élément courant. Le premier paramètre est le type d'événement (click, change, blur, mouseover...). Le deuxième paramètre est la fonction appelée lors de l'exécution de l'événement, elle prend en paramètre un objet Event.
Méthode
addEvent(event, callback)
Paramètres
string event : nom de l'événement.
function callback : fonction à appeler lors de l'événement.
Retour
ElementRJS : l'élément courant.
<a href="#" title="">Lien</a>let anchor = ElementRJS.searchOne("a");
anchor.addEvent("click", function(event) {
event.preventDefault();
element = ElementRJS.retrieve(this);
element.addClass("active");
}); Dans l'exemple précédent, la classe active est ajoutée à l'ancre lors du clic.
La méthode fireEvent permet de déclencher un événement. Le premier paramètre est le type d'événement. Le second paramètre est facultatif, il vous permet de transmettre une liste de paramètres à la fonction d'appel de l'événement.
Méthode
fireEvent(event)
Paramètre
string event : nom de l'événement.
array params : liste des paramètres à transmettre à la fonction d'appel, si nécessaire.
Retour
ElementRJS : l'élément courant.
<a href="#" title="">Lien</a>let anchor = ElementRJS.searchOne("a");
anchor.addEvent("addLog", function(message) {
let
link = ElementRJS.retrieve(this),
paragraph = new ElementRJS("p", {
"text": message
})
;
anchor.addElement(paragraph, "after");
});
anchor.addEvent("click", function(event) {
event.preventDefault();
let link = ElementRJS.retrieve(this);
link.fireEvent("addLog", [ 'Nouveau clic' ]);
}); L'exemple précédent ajoute un paragraphe avec le texte Nouveau clic à chaque clic sur l'ancre.
La méthode getStyle permet de récupérer la valeur d'une propriété CSS. La méthode prend en entrée le nom de la propriété et retourne la valeur CSS correspondante, ou null si la valeur n'a pas été trouvée.
Méthode
getStyle(key)
Paramètre
string key : nom de la propriété CSS.
Retour
string | null : la valeur de la propriété.
<a href="#" title="">Lien</a>let
anchor = ElementRJS.searchOne("a"),
color = anchor.getStyle("color")
; L'exemple précédent retourne la couleur de l'ancre.
La méthode setStyles permet de modifier les styles d'un élément. Elle prend en entrée un objet JSON des styles à appliquer.
Méthode
setStyles(styles)
Paramètre
object styles : objet JSON des styles à appliquer.
Retour
ElementRJS : l'élément courant.
<a href="#" title="">Lien</a>let anchor = ElementRJS.searchOne("a");
anchor.setStyles({
"text-decoration": "none",
"color": "gray"
}); L'exemple précédent modifit la couleur et le surlignage de l'ancre.
La méthode getOuterDimension permet de retourner la largeur ou la hauteur de l'élément y compris les marges extérieurs (margin), intérieurs (padding) et les bordures.
Méthode
getOuterDimension(property)
Paramètre
string property : width pour calculer la largeur, height pour calculer la hauteur.
Retour
float : la valeur demandée en pixels.
<p>Texte</p>let
element = ElementRJS.searchOne("p"),
width = element.getOuterDimension("width"),
height = element.getOuterDimension("height")
;L'exemple précédent calcul la largeur (variable width) et la hauteur (variable height) du paragraphe.
La méthode computeOffset calcul le décalage vertical ou horizontal de l'élément courant par rapport au début de la page. La méthode prend en entrée la valeur top pour le décalage vertical ou left pour le décalage horizontal. La méthode retourne le nombre de pixels correspond au décalage.
Méthode
computeOffset(property)
Paramètre
string property : top pour calculer le décalage vertical et left pour calculer le décalage horizontal.
Retour
float : décalage de l'élément par rapport au début de la page, en pixels.
<div class="menu">
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</div> let
li = ElementRJS.searchOne("li:nth-child(3)"),
offsetTop = li.computeOffset("top")
; L'exemple précédent calcul le décalage vertical du troisième élément li.
La méthode changeScroll permet de modifier les positions du défilement horizontal et vertical. La méthode prend en entrée un objet JSON avec les positions left et top. Les nouvelles positions doivent être des float correspondant à des valeurs en pixels.
Méthode
changeScroll(data)
Paramètre
object data : objet JSON des valeurs du défilement à changer.
Retour
ElementRJS : l'élément courant.
<div class="content">
<a href="#" class="top" title="Tester le décalage vertical.">Tester</a>
</div> let
scrollingElement = ElementRJS.retrieve(document.scrollingElement),
content = ElementRJS.searchOne("div.content"),
anchorTop = content.getChild("a.top")
;
anchorTop.addEvent("click", function(event) {
event.preventDefault();
content.setStyles({
"min-height": "2000px"
});
scrollingElement.changeScroll({
"top": content.getProperty("clientHeight")
});
}); Dans l'exemple précédent, le clic sur l'ancre modifit la hauteur de l'élément div.content pour que nous puissions tester le défilement. Le défilement se déplace ensuite en bas de page.