Browse Source

Finalisation de la première version complète de la documentation.

master
Fabrice PENHOËT 4 months ago
parent
commit
d4d24732e0
  1. 536
      public/documentation.html

536
public/documentation.html

@ -24,348 +24,414 @@
</ul>
</nav>
</header>
<aside>
<h4>Menu</h4>
<ul>
<li><a href="#installation">Installer FreeDatas2HTML</a></li>
<li><a href="#instance">Instancier la classe principale</a></li>
<li><a href="#setDatas">Fournir directement les données à parser</a></li>
<li><a href="#import">Importer les données à partir d’une source distante</a></li>
<li><a href="#DOMElt">Définir l’élément du DOM où seront affichées les données</a></li>
<li><a href="#parser">Parser les données</a></li>
<li><a href="#render">Adapter le code HTML généré pour afficher des données</a></li>
<li><a href="#compteur">Afficher un compteur</a></li>
<li><a href="#pagination">Paginer les données</a></li>
<li><a href="#filtres">Proposer des filtres pour les données</a></li>
<li><a href="#search">Proposer un moteur de recherche</a></li>
<li><a href="#classement">Permettre de classer les données affichées</a></li>
<li><a href="#fonctionClassement">Personnaliser la façon de classer les données</a></li>
<li><a href="#conclusion">Conclusion</a></li>
</ul>
</aside>
<article id="content">
<h2>Documentation FreeDatas2HTML</h2>
<h3>Installation FreeDatas2HTML</h3>
<h3 id="installation">Installer FreeDatas2HTML</h3>
<p>Pour l’instant FreeDatas2HTML n’est pas disponible sur NPM.<br />
Vous devez donc en récupérer une copie sur <a href="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 <a href="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 <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/build" rel="noopener" target="_blank">/src/build</a>.</p>
<h3 id="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 />
<code>const myConverter=new FreeDatas2HTML("CSV");</code></p>
<h4>Type de données</h4>
<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>
<h3 id="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 />
<code>const myConverter=new FreeDatas2HTML("JSON", `[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`);</code></p>
<p>Pour l’instant FreeDatas2HTML n’est pas disponible sur NPM.<br />
Vous devez donc en récupérer une copie sur <a href="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 <a href="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 <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/build" rel="noopener" target="_blank">/src/build</a>.</p>
<p>Mais vous pouvez très bien fournir ou modifier cette information après l’instanciation:<br />
<code>myConverter.parser.datas2Parse=`[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`;</code></p>
<h3>Importation de la classe principale</h3>
<h3 id="import">Importer les données à partir d’une source distante</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></p>
<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 />
const mySource=new RemoteSource({ url:"https://www.example.com/datas.csv" });<br />
const myConverter=new FreeDatas2HTML("CSV","", mySource);</code></p>
<p>À supposer que les scripts soient situés dans le sous-répertoire <em>FreeDatas2HTML</em> du répertoire <em>modules</em> de votre projet.</p>
<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 <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts" rel="noopener" target="_blank">interface.ts</a>.</p>
<p>Suivant ce que vous souhaitez faire, vous aurez peut-être besoin d’importer d’autres classes, comme indiqué plus loin.</p>
<p>Vous pouvez fournir des entêtes pour l’appel à la source de données distantes:<br />
<code>mySource.headers=[ { key:"token", value:"1234" }, { key:"userName", value:"Toto" }];</code></p>
<h3>Instanciation de la classe principale</h3>
<p>Il vous est aussi possible de déclarer la propriété <em>XMLHttpRequest.withCredentials</em>:<br />
<code>mySource.withCredentials=true;</code><br />
<br />
Mais vous pouvez aussi fournir la source de données distante après l’instanciation en utilisant le <em>setter</em>:<br />
<code>myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv" });</code></p>
<p>Ensuite, dans votre script, vous pouvez créer votre instance de manière classique:<br />
<code>const myConverter=new FreeDatas2HTML("CSV");</code></p>
<p>Dans ce cas l’importation préalable de la classe <em>RemoteSource</em> est inutile.<br />
De nouveau, vous pouvez fournir des options:<br />
<code>myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv", headers:[{ key:"token", value:"1234" }],&nbsp;<code class="code-inner"><span class="nx">withCredentials</span>:true</code> });</code></p>
<h4>Type de données</h4>
<h3 id="DOMElt">Définir l’élément du DOM où seront affichées les données</h3>
<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>
<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 />
<code>myConverter.datasViewElt={ id:"myDatas" };</code><br />
L’élément doit exister dans la page, sans quoi le <em>setter</em> générera une erreur.</p>
<h3>Fournir directement les données à parser</h3>
<h3 id="parser">Parser les données</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 />
<code>const myConverter=new FreeDatas2HTML("JSON", `[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`);</code><br />
Mais vous pouvez très bien fournir ou modifier cette information après l’instanciation:<br />
<code>myConverter.parser.datas2Parse=`[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`;</code></p>
<p>Pour lancer le parsage, utilisez la méthode <em>run()</em> qui est asynchrone:<br />
<code>await myConverter.run();</code></p>
<h3>Importer les données à partir d’une source distante</h3>
<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 dernier argument, vous permet de passer une instance de la classe RemoteSource qu’il vous faudra au préalable avoir importée et déclarée:<br />
<code>import { FreeDatas2HTML, RemoteSource } from "./modules/FreeDatas2HTML";</code><br />
const mySource=new RemoteSource({ url:"https://www.example.com/datas.csv" });<br />
<code>const myConverter=new FreeDatas2HTML("CSV","", mySource);</code><br />
En fait, il sera accepté une instance de n’importe quelle classe validant l’interface RemoteSources que vous pouvez retrouver déclarée dans le script <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts" rel="noopener" target="_blank">interface.ts</a>.</p>
<p>Dans tous les cas, une fois le parsage finalisé avec succès, vous pouvez accéder aux noms de champs et aux données trouvées:<br />
<code>const fields=myConverter.fields; // format de sortie: string[], exemple: ["fistname", "name"]<br />
const datas=myConverter.datas; // format de sortie : {[index: string]:string}[], exemple: [{"firstname":"Janie", "name":"Doe"}, {"firstname":"John", "name":"Doe"}];</code><br />
Les formats de sortie sont les mêmes, quel que soit le format des données parsées.</p>
<p>Vous pouvez fournir des entêtes pour l’appel à la source de données distantes:<br />
<code>mySource.headers=[ { key:"token", value:"1234" }, { key:"userName", value:"Toto" }];</code></p>
<h4>Tolérance aux erreurs de parsage</h4>
<p>Il vous est aussi possible de déclarer la propriété <em>XMLHttpRequest.withCredentials</em>:<br />
<code>source.withCredentials=true;</code><br />
<br />
Mais vous pouvez aussi fournir la source de données distante après l’instanciation en utilisant le <em>setter</em>:<br />
<code>myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv" });</code><br />
Dans ce cas l’importation préalable de la classe <em>RemoteSource</em> est inutile.<br />
De nouveau, vous pouvez fournir des options:<br />
<code>myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv", headers:[{ key:"token", value:"1234" }],&nbsp;<code class="code-inner"><span class="nx">withCredentials</span>:true</code> });</code></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 />
<code>myConverter.stopIfParseErrors=true;</code><br />
Par défaut, les erreurs de parsage sont tolérées.</p>
<h3>Définir l’élément du DOM où seront afficher les données</h3>
<h3>Adapter le rendu visuel des données</h3>
<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’id de l’élément de la page où les afficher:<br />
<code>myConverter.datasViewElt={ id:"myDatas" };</code><br />
L’élément doit exister dans la page, sans quoi le <em>setter</em> générera une erreur.</p>
<p>Par défaut toutes les données trouvées seront affichées sous forme de tableau, sans classe CSS particulière:</p>
<h3>Parser les données</h3>
<p><code>&lt;table&gt;<br />
&nbsp;&lt;thead&gt;&lt;tr&gt;&lt;td&gt;firstname&lt;/td&gt;&lt;td&gt;name&lt;/td&gt;&lt;/tr&gt;&lt;/thead&gt;<br />
&nbsp;&lt;tbody&gt;<br />
&nbsp; &lt;tr&gt;&lt;td&gt;Janie&lt;/td&gt;&lt;td&gt;Doe&lt;/td&gt;&lt;/tr&gt;<br />
&nbsp; &lt;tr&gt;&lt;td&gt;John&lt;/td&gt;&lt;td&gt;Doe&lt;/td&gt;&lt;/tr&gt;<br />
&nbsp;&lt;/tbody&gt;<br />
&lt;/table&gt;</code></p>
<p>Pour lancer le parsage, utilisez la méthode <em>run()</em> qui est asynchrone:<br />
<code>await myConverter.run();</code></p>
<h4>Ne pas afficher tous les champs disponibles</h4>
<p>En cas de succès du parsage, si l’id de l’élément du DOM devant recevoir les données est connu, elles seront automatiquement affichées dans la page.</p>
<p>Si vous ne souhaitez pas afficher tous les champs trouvés dans votre fichier, vous pouvez indiquer ceux à garder:<br />
<code>myConverter.fields2Rend=[0,2]; // n’affichera que le 1ᵉʳ et le 3ᵉ champ, la numérotation commençant à zéro.</code></p>
<p>Dans tous les cas, une fois le parsage finalisé avec succès, vous pouvez accéder aux noms de champs et aux données trouvées:<br />
<code>const fields=myConverter.fields; // format de sortie: string[], exemple: ["fistname", "name"]<br />
const datas=myConverter.datas; // format de sortie : {[index: string]:string}[], exemple: [{firstname:"Janie", name:"Doe"}, {firstname:"John", name:"Doe"}];</code><br />
Les formats de sortie sont les mêmes, quel que soit le format des données parsées.</p>
<p>Ce <em>setter</em> provoquera une erreur si vous fournissez un numéro de champ n’existant pas dans les données parsées.<br />
Vous pouvez par contre le déclarer à tout moment, pour prise en compte dès le prochain affichage.</p>
<h4>Tolérance aux erreurs de parsage</h4>
<p>Pour de nouveau afficher tous les champs (soit, revenir à la situation par défaut), il vous suffit de passer un tableau vide:<br />
<code>myConverter.fields2Rend=[];</code></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 />
<code>myConverter.stopIfParseErrors=true;</code><br />
Par défaut, les erreurs de parsage sont tolérées.</p>
<h3 id="render">Adapter le code HTML généré pour afficher des données</h3>
<h3>Adapter le rendu visuel des données</h3>
<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 <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts" rel="noopener" target="_blank">interface.ts</a>.</p>
<p>Par défaut toutes les données trouvées seront affichées sous forme de tableau sans classe CSS particulière:</p>
<p>Dans le cas de la classe <em>Render</em>, il faut commencer par l’importer et l’instancier:<br />
<code>import { FreeDatas2HTML, Render } from "./modules/FreeDatas2HTML";</code><br />
<code></code><br />
<code>const myRender=new Render();</code></p>
<p><code>&lt;table&gt;<br />
&nbsp;&lt;thead&gt;&lt;tr&gt;&lt;td&gt;firstname&lt;/td&gt;&lt;td&gt;name&lt;/td&gt;&lt;/tr&gt;&lt;/thead&gt;<br />
&nbsp;&lt;tbody&gt;<br />
&nbsp; &lt;tr&gt;&lt;td&gt;Janie&lt;/td&gt;&lt;td&gt;Doe&lt;/td&gt;&lt;/tr&gt;<br />
&nbsp; &lt;tr&gt;&lt;td&gt;John&lt;/td&gt;&lt;td&gt;Doe&lt;/td&gt;&lt;/tr&gt;<br />
&nbsp;&lt;/tbody&gt;<br />
&lt;/table&gt;</code></p>
<p>Et ensuite utiliser l’attribut <em>settings</em> pour décrire ce que vous souhaitez obtenir:<br />
<code>myRender.settings=<br />
{<br />
&nbsp;&nbsp;&nbsp; allBegining:"&lt;h4&gt;Moi je préfère les listes aux tableaux!&lt;/h4&gt;",<br />
&nbsp;&nbsp;&nbsp; allEnding:"Pas vous?",<br />
&nbsp;&nbsp;&nbsp; linesBegining:"&lt;ul&gt;",<br />
&nbsp;&nbsp;&nbsp; linesEnding:"&lt;/ul&gt;",<br />
&nbsp;&nbsp;&nbsp; lineBegining:"&lt;li&gt;&lt;ul&gt;",<br />
&nbsp;&nbsp;&nbsp; lineEnding:"&lt;/ul&gt;&lt;/li&gt;",<br />
&nbsp;&nbsp;&nbsp; dataDisplaying:"&lt;li&gt;&lt;b&gt;#FIELDNAME :&lt;/b&gt; #VALUE&lt;/li&gt;",<br />
};</code></p>
<h4>Ne pas afficher tous les champs disponibles</h4>
<p>Dans ce cas, la configuration par défaut est écrasée par ce qui est fourni à <em>settings</em>.<br />
<a href="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>Si vous ne souhaitez pas afficher tous les champs trouvés dans votre fichier, vous pouvez indiquer ceux à garder:<br />
<code>myConverter.fields2Rend=[0,2]; // n’affichera que le 1ᵉʳ et le troisième champ, la numérotation commençant à zéro.</code></p>
<p>Si vous souhaitez simplement modifier un des attributs, vous pouvez le faire ainsi:<br />
<code>myRender.settings.allBegining="&lt;table class='myTable'&gt;";</code><br />
Ici le tableau sera le même que précédément, seule la balise <em>&lt;table&gt;</em> s’est vu ajouter une classe CSS.</p>
<p>Ce setter provoquera une erreur si vous fournissez un numéro de champ n’existant pas les données parsées.<br />
Vous pouvez par contre le déclarer à tout moment, pour prise en compte dès le prochain affichage.</p>
<p>Dans les deux cas, il faut ensuite fournir votre <em>Render</em> à votre instance de FreeDatas2HTML:<br />
<code>myConverter.datasRender=myRender;</code></p>
<p>Pour de nouveau afficher tous les champs (situation par défaut), il suffit de passer un tableau vide:<br />
<code>myConverter.fields2Rend=[];</code></p>
<h4>Besoin d’un rendu complexe, fusionnant plusieurs champs?</h4>
<h4>Adapter le code HTML généré pour l’affichage des données</h4>
<p>Il est possible d’obtenir un rendu plus complexe, mixant les données venant de plusieurs champs.<br />
C’est par exemple le cas si vous souhaitez créer un lien dont l’URL se trouve dans un champ et l’ancre dans un autre.</p>
<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 <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/interfaces.ts" rel="noopener" target="_blank">interface.ts</a>.<br />
Dans le cas de la classe <em>Render</em>, il faut commencer par l’importer:<br />
<code>import { FreeDatas2HTML, Render } from "./modules/FreeDatas2HTML";</code></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 <a href="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>Puis l’instancier:<br />
<code>const myRender=new Render();</code><br />
Et utiliser l’attribut <em>settings</em> pour décrire ce que vous souhaitez obtenir:<br />
<code>myRender.settings=<br />
{<br />
&nbsp;&nbsp;&nbsp; allBegining:"&lt;h4&gt;Moi je préfère les listes aux tableaux !&lt;/h4&gt;",<br />
&nbsp;&nbsp;&nbsp; allEnding:"Pas vous ?",<br />
&nbsp;&nbsp;&nbsp; linesBegining:"&lt;ul&gt;",<br />
&nbsp;&nbsp;&nbsp; linesEnding:"&lt;/ul&gt;",<br />
&nbsp;&nbsp;&nbsp; lineBegining:"&lt;li&gt;&lt;ul&gt;",<br />
&nbsp;&nbsp;&nbsp; lineEnding:"&lt;/ul&gt;&lt;/li&gt;",<br />
&nbsp;&nbsp;&nbsp; dataDisplaying:"&lt;li&gt;&lt;b&gt;#FIELDNAME :&lt;/b&gt; #VALUE&lt;/li&gt;",<br />
};</code><br />
Dans ce cas la configuration par défaut est écrasée par la valeur de settings.<br />
<a href="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>
<h3 id="compteur">Afficher un compteur</h3>
<p>Si vous souhaitez simplement modifier un des attributs, vous pouvez le faire ainsi:<br />
<code>myRender.settings.allBegining="&lt;table class='myTable'&gt;";</code><br />
Ici le tableau sera le même que précédément, seule la balise <em>&lt;table&gt;</em> recevra une classe CSS ou ce que vous voulez…</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 />
<code>myConverter.datasCounterElt={ id:"ndDatas" };</code></p>
<p>Dans les deux cas, il faut ensuite attribuer votre <em>Render</em> à votre instance de FreeDatas2HTML:<br />
<code>myConverter.datasRender=myRender;</code></p>
<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>
<h4>Besoin d'un rendu complexe, fusionnant plusieurs champs?</h4>
<p>Si vous souhaitez vous-mêmes actualiser l’affichage de ce compteur, utilisez cette méthode:<br />
<code>myConverter.datasCounter2HTML();</code></p>
<p>Il est possible d’obtenir un rendu plus complexe, mixant les données venant de plusieurs champs. C’est par exemple le cas si vous souhaitez créer un lien dont l’URL se trouve dans un champ et l’ancre dans un autre.</p>
<h3 id="pagination">Paginer les données</h3>
<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 <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/src/demo/exampleWithMixedFields.ts" rel="noopener" target="_blank">du code utilisé de l’exemple d'usage de ce site de démonstration</a> ou encore <a href="https://forge.chapril.org/Fab_Blab/FreeDatas2HTML/src/branch/master/integrations/src/segal.ts" rel="noopener" target="_blank">du code utilisé sur le site d’une association</a> pour lister ses partenaires à partir d’un fichier <em>CSV</em>.</p>
<p>Par défaut, tous les enregistrements extraits de la source de données sont affichés à l’emplacement prévu dans la page.<br />
Toutefois, vous pouvez les paginer et même proposer aux utilisateurs finaux de choisir le nombre de résultats à afficher par page.</p>
<h3>Affichage d’un compteur</h3>
<p>Ceci est possible via la classe <em>Pagination</em> qui doit donc être importée et instanciée:<br />
<code>import { FreeDatas2HTML, Pagination } from "./modules/FreeDatas2HTML";</code><br />
<code></code><br />
<code>const myPagination=new Pagination(converter, { id:"pages" });</code></p>
<p>Si vous souhaitez afficher quelque part le nombre d’enregistrements, il vous suffit de fournir l’id de l’élément de votre page devant recevoir cette information :<br />
<code>myConverter.datasCounterElt={ id:"ndDatas" };</code></p>
<p>Ceci ne devant être fait qu’<strong>après avoir importé vos données</strong>, qui sont nécessaires à la pagination.</p>
<p>Ce compteur sera ensuite mis à jour à chaque actualisation des données. Il prend en compte les filtres activés par l’utilisateur, mais ignore 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 />
Par défaut, il y sera affiché «Pages».</p>
<p>Si vous souhaitez vous-mêmes actualiser ce compteur, utilisez cette méthode:<br />
<code>myConverter.datasCounter2HTML();</code></p>
<p>Une fois votre classe instanciée, vous pouvez proposer un choix de pagination aux utilisateurs finaux:<br />
<code>myPagination.options={ displayElement: { id:"paginationOptions" }, values: [10,20,50,100] , name: "Choix de pagination :" };</code><br />
Ici:</p>
<h3>Proposer des filtres pour les données</h3>
<ul>
<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>
</ul>
<p>Les filtres sont des éléments <em>SELECT</em> listant, de manière&nbsp;classée et dédoublonnée, toutes les valeurs disponibles pour un champ. 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»… Pour des besoins particuliers, il vous est possible d’utiliser votre propre fonction de classement, ce qui sera expliqué plus loin.</p>
<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>Si plusieurs filtres sont proposés à l’utilisateur final, seuls les enregistrements validant tous les choix de l’utilisateur seront affichés.</p>
<p>Puis il vous reste à fournir votre pagination à votre instance FreeDatas2HTML:<br />
<code>myConverter.pagination=myPagination;</code></p>
<p>Pour ajouter un filtre, commencer par l’inclure dans votre script:<br />
<code>import { FreeDatas2HTML, Selector } from "./modules/FreeDatas2HTML";</code></p>
<p>Si vous proposez des options de pagination, vous devez lancer l’injection du code HTML correspondant dans votre page:<br />
<code>myPagination.options2HTML();</code></p>
<p>Pour créer une instance:<br />
<code>const myFilter1=new Selector(myConverter, 3, { id:"filter1"});</code></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 trois premiers paramètres sont obligatoires:</p>
<h3 id="filtres">Proposer des filtres pour les données</h3>
<ul>
<li>le premier est votre instance de FreeDatas2HTML</li>
<li>le deuxième correspond au numéro du champ utilisé pour ce filtre</li>
<li>le troisième est l’id de l’élément HTML dans lequel sera injecté la liste <em>SELECT</em>.</li>
</ul>
<p>Les filtres sont des éléments <em>SELECT</em> listant, de manière&nbsp;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 est facultatif, mais 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 />
<code>const myFilter2=new Selector(myConverter, 2, { id:"filter2"}, ";" );</code></p>
<p>Si plusieurs filtres sont proposés à l’utilisateur final, seuls les enregistrements validant tous les choix de l’utilisateur seront affichés.</p>
<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>Pour ajouter un filtre, commencer par l’inclure dans votre script et créer une instance:<br />
<code>import { FreeDatas2HTML, Selector } from "./modules/FreeDatas2HTML";</code><br />
<code></code><br />
<code>const myFilter1=new Selector(myConverter, 3, { id:"filter1"});</code></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 sera affiché.</p>
<p>Les trois premiers paramètres sont obligatoires:</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 />
<code>const selectDatas=myFilter1.selectedValues;</code><br />
Il s’agit d’un tableau de chaînes de caractères. Par exemple pour des années:<br />
<code>["1998", "2000", "2005" ....]</code></p>
<ul>
<li>le premier est votre instance de FreeDatas2HTML</li>
<li>le deuxième correspond au numéro du champ utilisé pour ce filtre</li>
<li>le troisième est l’<em>id </em>de l’élément HTML dans lequel sera injecté la liste <em>SELECT</em>.</li>
</ul>
<p>Une fois la configuration terminée, vous pouvez afficher votre liste dans la page via le code suivant:<br />
<code>myFilter.filter2HTML();</code></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 />
<code>const myFilter2=new Selector(myConverter, 2, { id:"filter2"}, ";" );</code></p>
<p>Par défaut, le <em>label</em> affiché devant la liste sera le nom du champ tel que présent dans les données traitées.<br />
Si vous souhaitez afficher un autre texte, vous pouvez le passer en paramètre:<br />
<code>myFilter.filter2HTML("Choisissez une valeur :");</code></p>
<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>Pour que votre filtre soit effectivement actif, il vous faut ensuite le transmettre à votre instance de FreeDatas2HTML.<br />
Vous pouvez passer tous vos filtres en une seule fois:<br />
<code>myConverter.datasFilters=[myFilter1, myFilter2, myFilter3];</code><br />
Il sera en fait acceptée toute instance d’une classe respectant l’interface Filters <a href="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>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>
<h3>Proposer un moteur de recherche</h3>
<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 />
<code>const selectDatas=myFilter1.selectedValues;</code><br />
Il s’agit d’un tableau de chaînes de caractères. Par exemple pour des années:<br />
<code>["1998", "2000", "2005" …]</code></p>
<p>Un moteur de recherche est en fait un filtre comme les autres ou presque!</p>
<p>Une fois la configuration terminée, vous pouvez injecter votre liste dans la page via le code suivant:<br />
<code>myFilter.filter2HTML();</code></p>
<p>Effectivement, dans les deux cas il est proposé à l’utilisateur final de filtrer les données suivant son choix, qu’il aura effectué librement dans un moteur de recherche ou de manière contrainte dans une liste de sélections.</p>
<p>Par défaut, le <em>label</em> affiché devant la liste sera le nom du champ concerné, tel que présent dans les données traitées.<br />
Si vous souhaitez afficher un autre texte, vous pouvez le passer en paramètre:<br />
<code>myFilter.filter2HTML("Choisissez une valeur :");</code></p>
<p>Il s’agit d’ailleurs d’un exemple concret d’utilisation des interfaces, car les deux classes <em>Filter</em> et <em>SearchEngine</em> implémentent l’interface <em>Filters</em>, déjà citée plus haut. Toute instance d’une classe validant cette interface sera acceptée par FreeDatas2HTML comme filtre.</p>
<p>Pour que votre filtre soit effectivement actif, il vous faut ensuite le transmettre à votre instance de FreeDatas2HTML.<br />
Vous pouvez passer tous vos filtres en une seule fois:<br />
<code>myConverter.datasFilters=[myFilter1, myFilter2, myFilter3];</code><br />
Il sera en fait acceptée toute instance d’une classe respectant l’interface Filters <a href="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>Bref pour ajouter un moteur de recherche, il faut de nouveau inclure la classe:<br />
<code>import { FreeDatas2HTML, SearchEngine } from "./modules/FreeDatas2HTML";</code></p>
<h3 id="search">Proposer un moteur de recherche</h3>
<p>Puis en créer une instance:<br />
<code>const mySearch=new SearchEngine(myConverter, { id:"search" });</code></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>Les deux premiers paramètres sont obligatoires:</p>
<p>Les deux classes <em>Filter</em> et <em>SearchEngine</em> implémentent d’ailleurs la même interface: <em>Filters</em>.<br />
Et comme dit plus haut, toute instance d’une classe validant cette interface sera acceptée comme filtre par FreeDatas2HTML.</p>
<ul>
<li>le premier est de nouveau votre instance de FreeDatas2HTML</li>
<li>le second correspond à l’id de l’élément de votre document dans lequel le moteur de recherche sera injecté.</li>
</ul>
<p>Bref pour ajouter un moteur de recherche, il faut de nouveau inclure la classe et l’instancier:<br />
<code>import { FreeDatas2HTML, SearchEngine } from "./modules/FreeDatas2HTML";<br />
<br />
const mySearch=new SearchEngine(myConverter, { id:"search" });</code></p>
<h4>Définir les champs à utiliser pour votre recherche</h4>
<p>Les deux premiers paramètres sont obligatoires:</p>
<p>Un troisième paramètre vous permet de préciser la liste des champs dans lesquels la saisie de l’utilisateur sera recherchée, par exemple pour limiter la recherche aux troisième et quatrième champs:<br />
<code>const mySearch=new SearchEngine(myConverter, { id:"search" }, [2,3]);</code></p>
<ul>
<li>le premier est de nouveau votre instance de FreeDatas2HTML</li>
<li>le second correspond à l’<em>id </em>de l’élément de votre document dans lequel le moteur de recherche sera injecté.</li>
</ul>
<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 (cf plus haut).<br />
Il peut ainsi être intéressant d’avoir dans votre fichier un champ contenant des mots-clés utiles à votre moteur de recherche, sans pour autant les afficher dans la page…</p>
<h4>Définir les champs à utiliser pour votre recherche</h4>
<h4>Personnaliser l’apparence du moteur de recherche</h4>
<p>Un troisième paramètre vous permet de préciser la liste des champs dans lesquels la saisie de l’utilisateur sera recherchée.<br />
Par exemple, pour limiter la recherche aux troisième et quatrième champs:<br />
<code>const mySearch=new SearchEngine(myConverter, { id:"search" }, [2,3]);</code></p>
<p>Vous pouvez ensuite personnaliser l’apparence de votre moteur de recherche via certains attributs.</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>Le texte du <em>label</em> du champ de saisie:<br />
<code>mySearch.label="Votre recherche :"; // par défaut vide, il n’y aura alors pas de &lt;label&gt;</code></p>
<h4>Personnaliser l’apparence du moteur de recherche</h4>
<p>Le texte du bouton lançant la recherche:<br />
<code>mySearch.btnTxt="Va chercher !"; // par défaut : Search</code></p>
<p>Vous pouvez ensuite personnaliser l’apparence de votre moteur de recherche via certains attributs.</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>
<p>Le texte du <em>label</em> du champ de saisie:<br />
<code>mySearch.label="Votre recherche :"; // par défaut vide, il n’y aura alors pas de &lt;label&gt;</code></p>
<h4>Lancement automatique de la recherche?</h4>
<p>Le texte du bouton lançant la recherche:<br />
<code>mySearch.btnTxt="Va chercher!"; // par défaut: Search</code></p>
<p>D’autres attributs permettent d’adapter le comportement du moteur de recherche.</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>
<p>Pour lancer la recherche dès la saisie:<br />
<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. Ici il faut en saisir deux. Les espaces entourant la saisie sont ignorés.</code></p>
<h4>Lancement automatique de la recherche?</h4>
<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>Pour lancer la recherche dès la saisie:<br />
<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>
<h4>Recherche stricte ou «lâche»?</h4>
<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>Ensuite, sachez que 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.<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>
<h4>Recherche stricte ou «lâche»?</h4>
<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>
<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>
<ul>
<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&nbsp;(*) 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>
</ul>
<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>
<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>
<ul>
<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&nbsp;(*) 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>
</ul>
<p>Évidemment toutes les options précédentes peuvent être passées en une seule fois:<br />
<code>mySearch.searchMode={ accentOff:true, caseOff=true, separatedWords=false, specialCharsOff=true };</code></p>
<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>
<h4>Intégration à la page et activation</h4>
<p>Évidemment toutes les options précédentes peuvent être passées en une seule fois:<br />
<code>mySearch.searchMode={ accentOff=true, caseOff=true, separatedWords=false, specialCharsOff=true };</code></p>
<p>Une fois configuré, vous pouvez afficher votre moteur de recherche de la même manière que pour les filtres précédents:<br />
<code>mySearch.filter2HTML();</code></p>
<h4>Intégration à la page et activation</h4>
<p>Sans oublier de le transmettre à votre instance FreeDatas2HTML, sans quoi il sera inactif:<br />
<code>myConverter.datasFilters=[mySearch];</code></p>
<p>Une fois configuré, vous pouvez afficher votre moteur de recherche de la même manière que pour les filtres précédents:<br />
<code>mySearch.filter2HTML();</code></p>
<p>Ce qui peut être fait conjointement à vos autres filtres:<br />
<code>myConverter.datasFilters=[myFilter1, myFilter2, mySearch];</code></p>
<p>Sans oublier de le transmettre à votre instance FreeDatas2HTML, sans quoi il sera inactif:<br />
<code>myConverter.datasFilters=[mySearch];</code></p>
<h3>Permettre de classer les données affichées</h3>
<p>Ce qui peut être fait conjointement à vos autres filtres:<br />
<code>myConverter.datasFilters=[myFilter1, myFilter2, mySearch];</code></p>
<p>Un dernier outil va donner la possibilité à vos utilisateurs de classer les données affichées via le champ de son choix. Pour ce faire, il faut que le rendu que vous avez choisi propose des entêtes de colonnes, ce qui est typiquement le cas des tableaux HTML contenant des balises &lt;TH&gt;. L’utilisateur pourra ainsi cliquer sur l’entête d’une colonne pour s’en servir pour classer les données dans un sens, puis de nouveau cliquer pour les classer dans l’autre sens.</p>
<h3 id="classement">Permettre de classer les données affichées</h3>
<p>Pour utiliser cet outil, comme d’habitude, il vous faut commencer par inclure sa classe:<br />
<code>import { FreeDatas2HTML, SortingField } from "./modules/FreeDatas2HTML";</code></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 &lt;TH&gt;.<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>Puis l’instancier, pour chaque colonne que vous souhaitez rendre cliquable:<br />
<code>const mySortingField1=new SortingField(myConverter, 0);</code><br />
<code>const mySortingField2=new SortingField(myConverter, 3);</code></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 />
<br />
const mySortingField1=new SortingField(myConverter, 0);</code><br />
<code>const mySortingField2=new SortingField(myConverter, 3);</code></p>
<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 le sélecteur CSS à utiliser pour trouver les entêtes dans votre code HTML (par défaut, «TH»):<br />
<code>const mySortingField1=new SortingField(myConverter, 0, "td.fieldNames");</code><br />
Ce sélecteur CSS doit retourner le même nombre d’éléments qu’il n’y a de champs affichés dans votre page, sans quoi il y aura une erreur.</p>
<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 <a href="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 />
<code>const mySortingField1=new SortingField(myConverter, 0, "td.fieldNames");</code><br />
Ce sélecteur CSS doit retourner le même nombre d’éléments qu’il y a de champs affichés dans votre page, sans quoi il y aura une erreur.</p>
<p>Une fois tous vos champs de classement instanciés, il vous faut les transmettre à votre instance FreeDatas2HTML:<br />
<code>myConverter.datasSortingFields=[<code>mySortingField1, mySortingField2</code>];</code></p>
<p>Une fois tous vos champs de classement instanciés, il vous faut les transmettre à votre instance FreeDatas2HTML:<br />
<code>myConverter.datasSortingFields=[<code>mySortingField1, mySortingField2</code>];</code></p>
<p>Il est préférable de les transmettre avant le 1ᵉʳ affichage, car c’est FreeDatas2HTML qui s’occupera de rendre ses éléments cliquables.<br />
Dans le cas contraire, vous pouvez toujours actualiser l’affichage après coup:<br />
<code>myConverter.refreshView();</code></p>
<p>Il est préférable de les transmettre avant le 1ᵉʳ affichage, car c’est FreeDatas2HTML qui s’occupera de rendre ses éléments cliquables.<br />
Dans le cas contraire, vous pouvez toujours actualiser l’affichage après coup:<br />
<code>myConverter.refreshView();</code></p>
<p>Une fois les liens de classement installés, vous n’avez pu à vous en occuper, les données seront classées alternativement dans le sens ascendant, puis descendant suivant les clics de l’utilisateur final.</p>
<p>Une fois les liens de classement installés, vous n’avez plus à vous en occuper.<br />
Toutefois si vous souhaitez intervenir, l’attribut <em>order</em> est disponible:<br />
<code>mySortingField1.order="desc"; // accepte "asc", "desc" ou undefined.</code></p>
<p>Toutefois si vous souhaitez intervenir, l’attribut <em>order</em> est disponible:<br />
<code>mySortingField1.order="desc"; // accepte "asc", "desc" ou undefined.</code></p>
<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 <a href="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>À 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. Il s’agit de la classe <i>SortingFieldsStandAlone</i> qui n’est pas documentée ici pour l’instant. Mais vous pouvez <a href="https://forge.chapril.org/Fab_Blab/freeDatas2HTML/src/branch/master/src/demo/exampleWithUL.ts" target="_blank">étudier le code de la page de démonstration l’utilisant</a>.</p>
<h3 id="fonctionClassement">Personnaliser la façon de classer les données</h3>
<h3>Personnaliser la façon de classer les données</h3>
<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>Comme indiqué précédemment, 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 <a href="/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&nbsp;«&gt; 1 et &lt; 100000». Comment faire pour trier ces données?</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 <a href="/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&nbsp;«&gt; 1 et &lt; 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 <a href="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 />
<code>const mySort=(a: any, b: any, order: "asc"|"desc" = "asc") =&gt;<br />
{<br />
&nbsp;&nbsp;&nbsp; const values=[ "&gt; 100000", "&gt; 1 et &lt; 100 000", "≤ 1",&nbsp; "Traces", "Inexistant"];<br />
&nbsp;&nbsp;&nbsp; if(order === "desc")<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; values.reverse();<br />
&nbsp;&nbsp;&nbsp; if(values.indexOf(a) &gt; values.indexOf(b))<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return -1;<br />
&nbsp;&nbsp;&nbsp; else if(values.indexOf(a) &lt; values.indexOf(b))<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return 1;<br />
&nbsp;&nbsp;&nbsp; else<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return 0;<br />
};</code></p>
<p>Dans ce cas, il vous faut fournir une fonction personnalisée de classement à votre instance de FreeDatas2HTML. Cette fonction doit <a href="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 page de démonstration:<br />
<code>const mySort=(a: any, b: any, order: "asc"|"desc" = "asc") =&gt;<br />
{<br />
&nbsp;&nbsp;&nbsp; const values=[ "&gt; 100000", "&gt; 1 et &lt; 100 000", "≤ 1",&nbsp; "Traces", "Inexistant"];<br />
&nbsp;&nbsp;&nbsp; if(order === "desc")<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; values.reverse();<br />
&nbsp;&nbsp;&nbsp; if(values.indexOf(a) &gt; values.indexOf(b))<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return -1;<br />
&nbsp;&nbsp;&nbsp; else if(values.indexOf(a) &lt; values.indexOf(b))<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return 1;<br />
&nbsp;&nbsp;&nbsp; else<br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return 0;<br />
};</code></p>
<p>Une fois toutes vos fonctions de classement définies, il vaut faut les associer aux champs concernés de vos données:<br />
<code>myConverter.datasSortingFunctions=[{ datasFieldNb:4, sort:mySort }, { datasFieldNb:5, sort:mySort2 }];</code></p>
<p>Une fois toutes vos fonctions de classement définies, il vaut faut les associer aux champs concernés de vos données:<br />
<code>myConverter.datasSortingFunctions=[{ datasFieldNb:4, sort:mySort }, { datasFieldNb:5, sort:mySort2 }];</code></p>
<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>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>
<h3 id="conclusion">Conclusion</h3>
<p>&nbsp;</p>
<p>Cette documentation n’est sans doute pas exhaustive, mais vous donne les principales clés pour intégrer FreeDatas2HTML à votre projet.</p>
<p><strong>À SUIVRE – DOCUMENTATION EN COURS D’ÉCRITURE</strong></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>
</article>

Loading…
Cancel
Save