Suite rédaction documentation.

This commit is contained in:
Fabrice PENHOËT 2022-03-07 18:13:45 +01:00
parent fce80c87c4
commit 4c664c98f4
1 changed files with 141 additions and 1 deletions

View File

@ -221,12 +221,152 @@
<code>myConverter.datasFilters=[myFilter1, myFilter2, myFilter3];</code><br />
Il sera en fait acceptée toute instance dune classe respectant linterface 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>
<h3>Proposer un moteur de recherche</h3>
<p>Un moteur de recherche est en fait un filtre comme les autres ou presque!</p>
<p>Effectivement, dans les deux cas il est proposé à lutilisateur final de filtrer les données suivant son choix, quil aura effectué librement dans un moteur de recherche ou de manière contrainte dans une liste de sélections.</p>
<p>Il sagit dailleurs dun exemple concret dutilisation des interfaces, car les deux classes <em>Filter</em> et <em>SearchEngine</em> implémentent linterface <em>Filters</em>, déjà citée plus haut. Toute instance dune classe validant cette interface sera acceptée par FreeDatas2HTML comme filtre.</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>
<p>Puis en créer une instance:<br />
<code>const mySearch=new SearchEngine(myConverter, { id:"search" });</code></p>
<p>Les deux premiers paramètres sont obligatoires:</p>
<ul>
<li>le premier est de nouveau votre instance de FreeDatas2HTML</li>
<li>le second correspond à lid de lélément de votre document dans lequel le moteur de recherche sera injecté.</li>
</ul>
<h4>Définir les champs à utiliser pour votre recherche</h4>
<p>Un troisième paramètre vous permet de préciser la liste des champs dans lesquels la saisie de lutilisateur 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>
<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 davoir 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>Personnaliser lapparence du moteur de recherche</h4>
<p>Vous pouvez ensuite personnaliser lapparence de votre moteur de recherche via certains attributs.</p>
<p>Le texte du <em>label</em> du champ de saisie:<br />
<code>mySearch.label="Votre recherche :"; // par défaut vide, il ny aura alors pas de &lt;label&gt;</code></p>
<p>Le texte du bouton lançant la recherche:<br />
<code>mySearch.btnTxt="Va chercher !"; // par défaut : Search</code></p>
<p>Ou encore le <em>placeholder</em> saffichant dans le champ de saisie:<br />
<code>mySearch.placeholder="Saisir votre recherche"; // par défaut vide ou "Please enter at least NB characters.", sil y a un nombre minimum de caractères pour lancer la recherche automatique.</code></p>
<h4>Lancement automatique de la recherche?</h4>
<p>Dautres attributs permettent dadapter le comportement du moteur de recherche.</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 loption 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>
<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 lutilisateur, laffichage est actualisé pour ne plus prendre en compte ce filtre.</p>
<h4>Recherche stricte ou «lâche»?</h4>
<p>Ensuite, sachez que par défaut la recherche de la valeur se fait de manière «lâche», cest-à-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 quun enregistrement soit affiché en résultat.</p>
<p>En effet, les utilisateurs prennent rarement la peine de saisir lorthographe exacte de ce quils cherchent.<br />
Mais cela peut créer des faux positifs et si vous souhaitez une recherche plus stricte, lattribut «searchMode» vous permet de préciser votre besoin:</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, lexpression 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ù loption précédente est à «false», les caractères listés dans la chaîne fournie seront néanmoins pris en compte, cest-à-dire ici "#", "@" et "%".</code></li>
</ul>
<p>(*) Seuls les caractères de lalphabet 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>É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>
<h4>Intégration à la page et activation</h4>
<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>Sans oublier de le transmettre à votre instance FreeDatas2HTML, sans quoi il sera inactif:<br />
<code>myConverter.datasFilters=[mySearch];</code></p>
<p>Ce qui peut être fait conjointement à vos autres filtres:<br />
<code>myConverter.datasFilters=[myFilter1, myFilter2, mySearch];</code></p>
<h3>Permettre de classer les données affichées</h3>
<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;. Lutilisateur pourra ainsi cliquer sur lentête dune colonne pour sen servir pour classer les données dans un sens, puis de nouveau cliquer pour les classer dans lautre sens.</p>
<p>Pour utiliser cet outil, comme dhabitude, il vous faut commencer par inclure sa classe:<br />
<code>import { FreeDatas2HTML, SortingField } from "./modules/FreeDatas2HTML";</code></p>
<p>Puis linstancier, 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>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 quil ny 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>Il est préférable de les transmettre avant le 1ᵉʳ affichage, car cest FreeDatas2HTML qui soccupera de rendre ses éléments cliquables.<br />
Dans le cas contraire, vous pouvez toujours actualiser laffichage après coup:<br />
<code>myConverter.refreshView();</code></p>
<p>Une fois les liens de classement installés, vous navez pu à vous en occuper, les données seront classées alternativement dans le sens ascendant, puis descendant suivant les clics de lutilisateur final.</p>
<p>Toutefois si vous souhaitez intervenir, lattribut <em>order</em> est disponible:<br />
<code>mySortingField1.order="desc"; // accepte "asc", "desc" ou undefined.</code></p>
<p>À noter quune extension est proposée pour vous permettre de créer des liens de classement, même quand vous navez pas prévu dentêtes dans le rendu de vos données. Il sagit de la classe <i>SortingFieldsStandAlone</i> qui nest pas documentée ici pour linstant. 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 lutilisant</a>.</p>
<h3>Personnaliser la façon de classer les données</h3>
<p>Comme indiqué précédemment, par défaut les classements se font de manière «naturelle», cest-à-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. Cest 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 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>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>&nbsp;</p>
<p><strong>À SUIVRE DOCUMENTATION EN COURS DÉCRITURE</strong></p>
</article>
<footer><p>Design: <a href="https://www.getpapercss.com" target="_blank">PaperCSS</a> | <a href="/mentions-legales.html">Contact et mentions légales</a>.</p></footer>