Browse Source

Suite rédaction documentation.

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

67
public/documentation.html

@ -158,8 +158,75 @@
<p>Dans les deux cas, il faut ensuite attribuer votre <em>Render</em> à votre instance de FreeDatas2HTML:<br />
<code>myConverter.datasRender=myRender;</code></p>
<h4>Besoin d'un rendu complexe, fusionnant plusieurs champs?</h4>
<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>
<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>
<h3>Affichage d’un compteur</h3>
<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>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>Si vous souhaitez vous-mêmes actualiser ce compteur, utilisez cette méthode:<br />
<code>myConverter.datasCounter2HTML();</code></p>
<h3>Proposer des filtres pour les données</h3>
<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>Si plusieurs filtres sont proposés à l’utilisateur final, seuls les enregistrements validant tous les choix de l’utilisateur seront affichés.</p>
<p>Pour ajouter un filtre, commencer par l’inclure dans votre script:<br />
<code>import { FreeDatas2HTML, Selector } from "./modules/FreeDatas2HTML";</code></p>
<p>Pour créer une instance:<br />
<code>const myFilter1=new Selector(myConverter, 3, { id:"filter1"});</code></p>
<p>Les trois premiers paramètres sont obligatoires:</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’id de l’élément HTML dans lequel sera injecté la liste <em>SELECT</em>.</li>
</ul>
<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>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 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 />
<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>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>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>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>&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>

Loading…
Cancel
Save