@gip-recia/js-tree

Esup Js-Tree

Js-Tree est un webcomponent s'appuyant sur la librairie Lit pour afficher une arborescence dépliable.

Installation

1. Installation via npm :

npm install @gip-recia/js-tree

1. Importation du composant :

Dans un module JavaScript :

import '@gip-recia/js-tree';

Dans une page HTML :

<script type="module">
  import './path/to/js-tree.js'
</script>

Ou directement la verion minifiée :

<script src="./path/to/js-tree.bundle.min.js"></script>

1. Ajout du composant sur une page HTML :

const tree = document.createElement('esup-js-tree');
tree.datas = [...];
tree.config = {...};
tree.onSelection = (data) => ...;
document.body.appendChild(tree);

Paramètres

Le webcomponent Js-Tree accepte les paramètres suvants :

• datas - Liste contenant l'ensemble des éléments de l'arborescence a afficher.

Propriétés de chaque élément :

Nom	Type	Obligatoire	Description
id	String	Oui	Identifiant unique de l'élément
text	String	Oui	Libellé de l'élément
children	Boolean	Oui	Indique si l'élément a des enfants
getChildren	Array/Function	Oui	Tableau des enfants de l'élément ou fonction retournant une promise permettant de récupérer les enfants de l'élément
iconIndex	Number	Non	Index (entre 0 et 10) de l'icône affiché pour cette élément

• config - Objet contenant la configuration de l'arbre.

Propriétés disponibles :

Nom	Type	Obligatoire	Description
identifier	String	Non	Identifiant html de l'arbre
showCheckbox	Boolean	Non	Permet d'afficher ou non une case à cocher sur chaque branche de l'arbre. Par défaut: false.
isMultipleSelection	Boolean	Non	Permet la sélection multiple sur l'arborescence (avec ou sans case à cocher). Par défaut: false.
allowDeselection	Boolean	Non	Permet dautoriser ou non la désélection dans l'arboresence. Par défaut: true.
sort	Boolean	Non	Permet de trier les branches de l'arbre par ordre alphabétique. Par défaut: false.

• onSelection - Fonction appelée lors de la sélection d'un élément de l'arbre.

Fonctions

Plusieurs fonctions sont disponibles pour manipuler l'arborescence :

• selectNode - Permet de sélectionner un élément.

Paramètres :

Nom	Type	Obligatoire	Description
id	String	Oui	Identifiant unique de l'élément

• deselectAllNodes - Permet de désélectionner tous les éléments.

• addNode - Permet d'ajouter un élément dans l'arborescence.

Paramètres :

Nom	Type	Obligatoire	Description
idParent	String	Oui	Identifiant unique de l'élément parent
properties	Object	Oui	Propriétés du nouvel élément (cf. tableau ci-dessus des propriétés des éléments)

• deleteNode - Permet de supprimer un élément dans l'arborescence.

Paramètres :

Nom	Type	Obligatoire	Description
id	String	Oui	Identifiant unique de l'élément

• refreshNode - Permet de rafraichir les données d'un élément dans l'arborescence.

Paramètres :

Nom	Type	Obligatoire	Description
id	String	Oui	Identifiant unique de l'élément
properties	Object	Oui	Propriétés à mettre à jour de l'élément (cf. tableau ci-dessus des propriétés des éléments)
refreshChildren	Boolean	Non	Indique s'il faut recharger les enfants de l'élément (par défaut : false)

Variables CSS

Modification de style

Plusieurs variables CSS peuvent être définis pour personnaliser l'arbre :

Nom	Description
--hover-text-color	Permet de modifier la couleur au survol du texte des éléments de l'arborescence
--selected-background-color	Permet de modifier la couleur de fond des éléments sélectionnés dans l'arborescence
--selected-text-color	Permet de modifier la couleur du texte des éléments sélectionnés de l'arborescence
--min-clickable-dimension	Permet de modifier la hauteur/largeur minimum des éléments cliquables de l'arborescence

Par défaut le webcomponent Js-Tree s'appuie sur les fonts Font-Awesome pour afficher des icônes (via des pseudo-elements). Il est cependant possible de personnaliser les icônes affichées via les propriétés suivantes :

Nom	Description
--icon-fold-font-family	Permet de configurer la famille de police de caractères de l'icône de replie
--icon-fold-font-weight	Permet de configurer poids de la police de caractères de l'icône de replie
--icon-fold-content	Caractère unicode dans la famille de police de caractères utilisée pour l'icône de replie
--icon-unfold-font-family	Permet de configurer la famille de police de caractères de l'icône de déplie
--icon-unfold-font-weight	Permet de configurer poids de la police de caractères de l'icône de déplie
--icon-unfold-content	Caractère unicode dans la famille de police de caractères utilisée pour l'icône de déplie

Icônes des noeuds de l'arbre

Il est possible de configurer jusqu'à 11 icônes pour les éléments de l'arborescence. Les variables à configurer pour définir une icône sont les suivantes (avec x entre 0 et 10) :

Nom	Description
--icon-{x}-font-family	Permet de configurer la famille de police de caractères de l'icône 'x'
--icon-{x}-font-weight	Permet de configurer poids de la police de caractères de l'icône 'x'
--icon-{x}-content	Caractère unicode dans la famille de police de caractères utilisée pour l'icône 'x'

Utilisation

Exemple de configuration des variables css dans un fichier de style :

esup-js-tree {
  --selected-background-color: #25b2f3;
  --text-color: #25b2f3;
  --selected-text-color: #fff;
  --icon-0-font-family: 'Font Awesome 5 Free';
  --icon-0-font-weight: 900;
  --icon-0-content: '\f015';
}

Test du webcomponent

Pour tester le webcomponent, exécuter la commande suivante :

npm start

Une page avec le webcomponent est alors disponible à l'adresse http://localhost:8000.