<p>Pour l’instant FreeDatas2HTML n’est pas disponible sur NPM.<br/>
Vous devez donc en récupérer une copie sur <ahref="https://forge.chapril.org/Fab_Blab/freeDatas2HTML"rel="noopener"target="_blank">le dépôt GIT du projet</a>.<br/>
Si vous travaillez en TypeScript, vous pouvez directement utiliser les fichiers présents dans le répertoire <ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src"rel="noopener"target="_blank">/src</a> et ignorer le sous-répertoire /build.<br/>
Si vous travaillez en JavaScript, vous devez au contraire utiliser les scripts présents dans le répertoire <ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/build"rel="noopener"target="_blank">/src/build</a>.</p>
<h3id="instance">Instancier la classe principale</h3>
<p>Une fois les scripts présents dans le répertoire de votre projet, vous pouvez les importer comme n’importe quel module:<br/>
<code>import { FreeDatas2HTML } from "./modules/FreeDatas2HTML";</code><br/>
À supposer que les scripts soient situés dans le sous-répertoire FreeDatas2HTML du répertoire <em>modules</em> de votre projet.</p>
<p>Suivant ce que vous souhaitez faire, vous aurez peut-être besoin d’importer d’autres classes, comme indiqué plus loin.</p>
<p>Ensuite, dans votre script, vous pouvez créer votre instance de manière classique:<br/>
<p>Le premier argument du constructeur est obligatoire et vous permet d’indiquer le format des données à parser, avec trois options possibles: <em>«CSV»</em>, <em>«JSON»</em>, <em>«HTML»</em>.</p>
<h3id="setDatas">Fournir directement les données à parser</h3>
<p>Si vous avez déjà les données à parser sous la main, vous pouvez les fournir en deuxième argument du constructeur sous forme d’une chaîne de caractère:<br/>
<p>Le dernier argument, vous permet de passer une instance de la classe <em>RemoteSource</em> qu’il vous faudra au préalable avoir importée et déclarée:<br/>
<code>import { FreeDatas2HTML, RemoteSource } from "./modules/FreeDatas2HTML";<br/>
<p>En fait, il sera accepté une instance de n’importe quelle classe validant l’interface <em>RemoteSources</em> que vous pouvez retrouver déclarée dans le script <ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts"rel="noopener"target="_blank">interface.ts</a>.</p>
<p>Ceci est facultatif, car vous pouvez très bien simplement vouloir parser les données.<br/>
Mais si vous souhaitez que FreeDatas2HTML s’occupe d’afficher les données, vous pouvez indiquer l’<em>id </em>de l’élément de la page où les afficher:<br/>
<p>En cas de succès du parsage, si l’<em>id </em>de l’élément du DOM devant recevoir les données est connu, elles seront automatiquement affichées dans la page.</p>
<p>Le parseur peut rencontrer certaines erreurs ne le bloquant pas, mais correspondant à des anomalies, par exemple, une colonne en trop dans des données CSV.<br/>
Si vous souhaitez bloquer la suite quand cela arrive, il vous faut l’indiquer avant de lancer le parsage:<br/>
<p>Pour spécifier le code HTML à générer, vous devez créer une instance de la classe <em>Render</em> ou d’une autre classe validant l’interface <em>DatasRenders</em> déclarée dans le script <ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts"rel="noopener"target="_blank">interface.ts</a>.</p>
<p>Dans ce cas, la configuration par défaut est écrasée par ce qui est fourni à <em>settings</em>.<br/>
<ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts"rel="noopener"target="_blank">Consulter le type <em>DatasRendersSettings</em></a> pour voir tous les attributs disponibles.</p>
<p>Ceci est possible via l’extension <strong><em>MixedFieldsRender.ts</em></strong>. Cette documentation ne présente pas l’usage de cette extension pour l’instant, mais vous pouvez vous inspirer <ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/demo/exampleWithMixedFields.ts"rel="noopener"target="_blank">du code utilisé par la page de démonstration de cette classe</a>.</p>
<p>Si vous souhaitez afficher quelque part le nombre d’enregistrements, il vous suffit de fournir l’<em>id </em>de l’élément de votre page devant recevoir cette information:<br/>
<p>Ce compteur sera ensuite mis à jour à chaque actualisation des données, en prennant en compte les filtres activés par l’utilisateur, mais en ignorant la pagination qui n’est qu’une commodité de navigation.</p>
<p>Le 1ᵉʳ paramètre est votre instance de FreeDatas2HTML et le deuxième l’<em>id </em>de l’élément HTML où sera injecté le <em>SELECT</em> permettant de passer d’une page à l’autre.<br/>
Un troisième paramètre peut vous permettre de personnaliser le texte dans le L<em>ABEL</em> de ce <em>SELECT</em>:<br/>
<code>const myPagination=new Pagination(converter, { id:"pages" }, "Aller à la page :");</code><br/>
<li><em>displayElement</em> est l’<em>id </em>de l’élément de votre page où sera injecté le <em>SELECT</em> proposant les options</li>
<li><em>values</em>, les différentes valeurs de pagination proposées, qui doivent être des nombres entiers réels. Au besoin, ils seront dédoublonnés, mais laissés dans l’ordre fourni. Il doit y avoir au moins 2 valeurs distinctes.</li>
<li><em>name</em> le texte du <em>LABEL</em>. S’il n’est pas fourni, la valeur par défaut est «Pagination».</li>
<p>Vous pouvez aussi définir une valeur de pagination par défaut:<br/>
<code>myPagination.selectedValue=10;</code><br/>
Si des options de pagination sont renseignées, cette valeur doit faire partie de celles proposées ou bien <em>undefined</em> pour afficher toutes les données.</p>
<p>Il y a une méthode similaire, <em>pages2HTML()</em>, pour injecter le code du <em>SELECT</em> permettant de changer de page.<br/>
Mais vous n’avez pas à vous en occuper, car c’est FreeDatas2HTML qui appelle cette méthode à chaque fois que l’affichage des données est actualisé.<br/>
Car suivant les filtres activés par l’utilisateur, le nombre d’enregistrements peut changer et par conséquent le nombre de pages à proposer.<br/>
Quand il y a moins de données affichées que le nombre maximum prévu par page, ce <em>SELECT</em> n’est pas affiché.</p>
<p>Les filtres sont des éléments <em>SELECT</em> listant, de manière classée et dédoublonnée, toutes les valeurs distinctes disponibles pour un champ.<br/>
Le classement se fait par ordre «naturel», c’est-à-dire par ordre alphabétique ignorant la casse pour les chaînes. De même pour les nombres, «02» ne sera pas avant «1», bien que «0» précède «1»…<br/>
Pour des besoins particuliers, il vous est possible d’utiliser votre propre fonction de classement, ce qui sera expliqué plus loin.</p>
<p>Un quatrième paramètre facultatif permet d’indiquer un séparateur, qui vous sera utile si un champ contient plusieurs valeurs pour un même enregistrement.<br/>
Par exemple, à supposer que vous souhaitiez créer un filtre sur le 3ᵉ champ (donc le numéro 2!) contenant des mots-clés séparés par des point virgule, voici le code à utiliser:<br/>
<p>Attention, <strong>vous devez d’abord avoir parsé vos données avant de créer votre instance de Selector</strong>, car l’existence du champ fourni en paramètre est testé à cette étape.</p>
<p>Une fois votre instance créée, en attribut supplémentaire permettra à l’utilisateur de sélectionner plusieurs valeurs dans la liste:<br/>
<code>myFilter2.isMultiple=true;</code><br/>
Ce n’est pas le cas par défaut. Si le choix multiple est permis, tout enregistrement valide pour au moins une des valeurs sélectionnées dans la liste sera affiché.</p>
<p>L’instanciation va aussi récupérer les données distinctes à proposer dans la liste. Vous pouvez récupérer cette liste de valeurs, via le code suivant:<br/>
Il sera en fait acceptée toute instance d’une classe respectant l’interface Filters <ahref="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts"rel="noopener"target="_blank">décrite dans le script interface.ts</a>.</p>
<p>Un moteur de recherche est en fait un filtre comme les autres ou presque!<br/>
Effectivement, dans les deux cas il est proposé à l’utilisateur final de filtrer les données suivant son choix, qu’il pourra effectuer librement dans un moteur de recherche ou de manière contrainte dans une liste de sélections.</p>
<p>Par défaut la recherche se fait donc dans tous les champs présents dans les données, qui ne sont pas forcément affichés.<br/>
Vous pouvez ainsi avoir dans vos données un champ contenant des mots-clés utiles à votre moteur de recherche, sans pour autant les afficher dans la page…</p>
<p>Ou encore le <em>placeholder</em> s’affichant dans le champ de saisie:<br/>
<code>mySearch.placeholder="Saisir votre recherche"; // par défaut vide ou «Please enter at least NB characters. », s’il y a un nombre minimum de caractères pour lancer la recherche automatique.</code></p>
<code>mySearch.automaticSearch=true; // par défaut false</code><br/>
En fixant éventuellement au nombre minimum de caractères:<br/>
<code>mySearch.nbCharsForSearch=2; // si l’option précédente est à «true», par défaut la recherche sera lancée dès le premier caractère saisi. Les espaces entourant la saisie sont ignorés.</code></p>
<p>Ce nombre de caractères minimum ne concerne pas le bouton lançant la recherche.<br/>
En mode recherche automatique lorsque le champ de saisie est vidé par l’utilisateur, l’affichage est actualisé pour ne plus prendre en compte ce filtre.</p>
<p>Sachez que <strong>par défaut la recherche de la valeur se fait de manière «lâche», c’est-à-dire en ignorant la casse, les accents ou encore les caractères spéciaux.</strong><br/>
Par ailleurs, si plusieurs expressions séparées par des espaces sont saisies, elles sont cherchées séparément dans les enregistrements, mais doivent toutes être trouvées pour qu’un enregistrement soit affiché en résultat.</p>
<p>En effet, les utilisateurs prennent rarement la peine de saisir l’orthographe exacte de ce qu’ils cherchent.<br/>
Mais cela peut créer des faux positifs et si vous souhaitez une recherche plus stricte, l’attribut «searchMode» vous permet de préciser votre besoin:</p>
<li><code>mySearch.searchMode.accentOff=true; // la recherche prendra en compte les accents.</code></li>
<li><code>mySearch.searchMode.caseOff=true; // la recherche prendra en compte la casse.</code></li>
<li><code>mySearch.searchMode.separatedWords=false; // même si elle contient des espaces, l’expression saisie sera cherchée en entier.</code></li>
<li><code>mySearch.searchMode.specialCharsOff=true; // la recherche prendra en compte les éventuels caractères spéciaux (*) saisis.</code></li>
<li><code>mySearch.searchMode.specialCharsWhiteList="#@%"; // dans le cas où l’option précédente est à «false», les caractères listés dans la chaîne fournie seront néanmoins pris en compte, c’est-à-dire ici "#", "@" et "%".</code></li>
<p>(*) Seuls les caractères de l’alphabet latin (a, b…z) et les 10 chiffres de la base décimale (0, 1…9) sont considérés comme des caractères non spéciaux. Donc, par défaut, tout autre caractère saisi sera ignoré.</p>
<p>Un dernier outil va donner la possibilité à vos utilisateurs de classer les données affichées via le champ de son choix.<br/>
Pour ce faire, <strong>il est nécessaire que le rendu que vous avez choisi propose des entêtes de colonnes</strong>, ce qui est typiquement le cas des tableaux HTML contenant des balises <TH>.<br/>
L’utilisateur pourra ainsi cliquer sur l’entête d’une colonne pour classer les données dans un sens, puis de nouveau cliquer pour les classer dans l’autre sens, etc.</p>
<p>Pour utiliser cet outil, comme d’habitude, il vous faut commencer par inclure sa classe et l’instancier pour chaque champ/colonne ouverte au classement:<br/>
<code>import { FreeDatas2HTML, SortingField } from "./modules/FreeDatas2HTML";<br/>
<p>Le premier paramètre est votre instance de FreeDatas2HTML et le deuxième le numéro du champ concerné, qui doit évidemment être affiché dans la page…<br/>
Un troisième paramètre facultatif, vous permet de désigner <ahref="https://www.w3.org/Style/css3-selectors-updates/WD-css3-selectors-20010126.fr.html#selectors"rel="noopener"target="_blank"title="W3C">le sélecteur CSS</a> à utiliser pour trouver les entêtes dans votre code HTML (par défaut, «TH»):<br/>
<p>À noter qu’une extension est proposée pour vous permettre de créer des liens de classement, même quand vous n’avez pas prévu d’entêtes dans le rendu de vos données.<br/>
Il s’agit de la classe <strong><i>SortingFieldsStandAlone</i></strong> qui n’est pas documentée ici pour l’instant. Mais vous pouvez <ahref="https://forge.chapril.org/Fab_Blab/freeDatas2HTML/src/branch/master/src/demo/exampleWithUL.ts"target="_blank">étudier le code d’une des pages de démonstration l’utilisant</a>.</p>
<p>Comme déjà indiqué, par défaut les classements se font de manière «naturelle», c’est-à-dire par ordre alphabétique ignorant la casse pour les chaînes de caractère. Pour les nombres, l’éventuel «0» initial sera ignoré, etc.</p>
<p>Toutefois, la façon de classer certaines données doit être explicitée. C’est par exemple le cas de la 4ᵉ colonne <ahref="/withCSV.html"target="_blank"title="accéder à cette page">de la page de démonstration listant des éléments chimiques</a>. Vous y trouver des textes «Inexistant», «Traces» ou encore des opérateurs de comparaison comme « > 1 et < 100000». Comment faire pour trier ces données?</p>
<p>Dans ce cas, il vous faut fournir une fonction personnalisée de classement à votre instance de FreeDatas2HTML. Cette fonction doit <ahref="https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Array/sort"rel="noopener"target="_blank"title="Documentation sur MDN">être compatible avec la fonction sort() de JavaScript</a>.<br/>
Voici par exemple, la fonction utilisée dans la page de démonstration:<br/>
<p>Il est important de les associer à votre instance avant de déclarer toute autre fonctionnalité en ayant besoin: filtres <em>SELECT</em>, colonnes de classement…</p>
<p>Pour une adaptation plus poussée à vos besoins, je vous encourage à étudier directement le code source et notamment les interfaces qui vous permettent de créer vos propres classes pour gérer l’affichage, les filtres, la pagination, etc. tout en continuant à bénéficier du reste du code de FreeDatas2HTML.</p>
