Relecture/correction page de documentation
This commit is contained in:
parent
d4d24732e0
commit
18de3cc10e
|
|
@ -25,8 +25,10 @@
|
|||
</nav>
|
||||
</header>
|
||||
|
||||
<aside>
|
||||
<h4>Menu</h4>
|
||||
<article id="content">
|
||||
<h2>Documentation FreeDatas2HTML</h2>
|
||||
|
||||
<h4>Sommaire</h4>
|
||||
<ul>
|
||||
<li><a href="#installation">Installer FreeDatas2HTML</a></li>
|
||||
<li><a href="#instance">Instancier la classe principale</a></li>
|
||||
|
|
@ -43,9 +45,6 @@
|
|||
<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 id="installation">Installer FreeDatas2HTML</h3>
|
||||
|
||||
|
|
@ -84,7 +83,7 @@
|
|||
const mySource=new RemoteSource({ url:"https://www.example.com/datas.csv" });<br />
|
||||
const myConverter=new FreeDatas2HTML("CSV","", mySource);</code></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>En fait, il sera accepté une instance de n’importe quelle classe validant l’interface <em>RemoteSources</em> que vous pouvez trouver 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>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>
|
||||
|
|
@ -104,7 +103,7 @@
|
|||
<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>
|
||||
L’élément doit exister dans la page, sans quoi ce <em>setter</em> générera une erreur.</p>
|
||||
|
||||
<h3 id="parser">Parser les données</h3>
|
||||
|
||||
|
|
@ -139,20 +138,19 @@
|
|||
|
||||
<h4>Ne pas afficher tous les champs disponibles</h4>
|
||||
|
||||
<p>Si vous ne souhaitez pas afficher tous les champs trouvés dans votre fichier, vous pouvez indiquer ceux à garder :<br />
|
||||
<p>Si vous ne souhaitez pas afficher tous les champs trouvés dans les données, 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>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>
|
||||
<p>Ce <em>setter</em> ne peut être utilisé qu’après le parsage, car il provoquera une erreur si vous fournissez un numéro de champ n’existant pas dans les données parsées.</p>
|
||||
|
||||
<p>Pour de nouveau afficher tous les champs (soit, revenir à la situation par défaut), il vous suffit de passer un tableau vide :<br />
|
||||
<p>Pour de nouveau afficher tous les champs (situation par défaut), il vous suffit de passer un tableau vide :<br />
|
||||
<code>myConverter.fields2Rend=[];</code></p>
|
||||
|
||||
<h3 id="render">Adapter le code HTML généré pour afficher 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>Dans le cas de la classe <em>Render</em>, il faut commencer par l’importer et l’instancier :<br />
|
||||
<p>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>
|
||||
|
|
@ -260,7 +258,7 @@
|
|||
</ul>
|
||||
|
||||
<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 />
|
||||
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>
|
||||
|
|
@ -269,15 +267,14 @@
|
|||
<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 />
|
||||
<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>L’instanciation va aussi récupérer les données distinctes à proposer dans la liste.<br>Vous pouvez récupérer cette liste de valeurs, via le code suivant :<br />
|
||||
<code>const filter1Datas=myFilter1.values;</code><br />
|
||||
Il s’agit d’un tableau de chaînes de caractères. Par exemple pour des années : <code>["1998", "2000", "2005" …]</code></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>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 />
|
||||
<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>
|
||||
|
||||
|
|
@ -294,7 +291,7 @@
|
|||
<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>
|
||||
|
||||
<p>Bref pour ajouter un moteur de recherche, il faut de nouveau inclure la classe et l’instancier :<br />
|
||||
<p>Bref pour ajouter un moteur de recherche, il faut de nouveau importer la classe et l’instancier :<br />
|
||||
<code>import { FreeDatas2HTML, SearchEngine } from "./modules/FreeDatas2HTML";<br />
|
||||
…<br />
|
||||
const mySearch=new SearchEngine(myConverter, { id:"search" });</code></p>
|
||||
|
|
@ -308,12 +305,10 @@
|
|||
|
||||
<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 l’utilisateur sera recherchée.<br />
|
||||
Par exemple, pour limiter la recherche aux troisième et quatrième champs :<br />
|
||||
<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>
|
||||
|
||||
<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>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… Par défaut la recherche se fait donc dans tous les champs présents dans les données, même s’ils ne sont pas affichés.</p>
|
||||
|
||||
<h4>Personnaliser l’apparence du moteur de recherche</h4>
|
||||
|
||||
|
|
@ -326,11 +321,11 @@
|
|||
<code>mySearch.btnTxt="Va chercher !"; // par défaut : Search</code></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.placeholder="Saisir votre recherche"; // par défaut vide ou « Please enter at least NB characters. », s’il est renseigné un nombre minimum de caractères pour lancer la recherche automatique.</code></p>
|
||||
|
||||
<h4>Lancement automatique de la recherche ?</h4>
|
||||
|
||||
<p>Pour lancer la recherche dès la saisie :<br />
|
||||
<p>Pour que la recherche soit lancée 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>
|
||||
|
|
@ -347,17 +342,17 @@
|
|||
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>
|
||||
|
||||
<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.accentOff=false; // la recherche prendra en compte les accents.</code></li>
|
||||
<li><code>mySearch.searchMode.caseOff=false; // 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>
|
||||
<li><code>mySearch.searchMode.specialCharsOff=false; // 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 à « true », 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>(*) 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>É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>
|
||||
<code>mySearch.searchMode={ accentOff=false, caseOff=false, separatedWords=false, specialCharsOff=false }; // les recherches lancées seront strictes</code></p>
|
||||
|
||||
<h4>Intégration à la page et activation</h4>
|
||||
|
||||
|
|
@ -372,11 +367,11 @@
|
|||
|
||||
<h3 id="classement">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.<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 />
|
||||
<p>Un dernier outil va donner la possibilité à vos utilisateurs de classer les données affichées via le champ de leur 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 <em><TH></em>.<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 />
|
||||
<p>Pour utiliser cet outil, comme d’habitude, il vous faut commencer par importer 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 />
|
||||
|
|
@ -399,7 +394,7 @@
|
|||
<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>
|
||||
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>
|
||||
|
||||
<h3 id="fonctionClassement">Personnaliser la façon de classer les données</h3>
|
||||
|
||||
|
|
@ -422,7 +417,7 @@
|
|||
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 />
|
||||
<p>Une fois toutes vos fonctions de classement définies, il vaut faut les associer aux champs concernés :<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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue