FreeDatas2HTML/public/documentation.html

234 lines
18 KiB
HTML
Raw Normal View History

<!DOCTYPE html>
<html lang="fr-fr">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="description" content="Documentation du module TypeScript/JavaScript FreeDatas2HTML.">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="robots" content="index,follow">
<link rel="stylesheet" href="CSS/paper.min.css">
<link rel="stylesheet" href="CSS/fd2html.css">
<script src="JS/matomo.js" defer></script>
<title>Documentation de FreeDatas2HTML</title>
</head>
<body class="paper container">
<header id="header" class="text-center">
<h1><a href="/">FreeDatas2HTML</a></h1>
<nav id="menu-principal">
<ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li>
<li><a href="./examples.html#content" class="badge success sm-12 col">Exemples</a></li>
<li><a href="./documentation.html#content" class="badge success sm-12 col">Documentation</a></li>
<li><a href="https://forge.chapril.org/Fab_Blab/freeDatas2HTML" target="_blank" title="accéder au dépôt GIT" rel="noopener" class="badge success sm-12 col">Git</a></li>
</ul>
</nav>
</header>
<article id="content">
<h2>Documentation FreeDatas2HTML</h2>
<h3>Installation FreeDatas2HTML</h3>
<p>Pour linstant FreeDatas2HTML nest 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>Importation de la classe principale</h3>
<p>Une fois les scripts présents dans le répertoire de votre projet, vous pouvez les importer comme nimporte quel module:<br />
<code>import { FreeDatas2HTML } from "./modules/FreeDatas2HTML";</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>Suivant ce que vous souhaitez faire, vous aurez peut-être besoin dimporter dautres classes, comme indiqué plus loin.</p>
<h3>Instanciation de la classe principale</h3>
<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 dindiquer le format des données à parser, avec trois options possibles: <em>«CSV»</em>, <em>«JSON»</em>, <em>«HTML»</em>.</p>
<h3>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 dune 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 linstanciation:<br />
<code>myConverter.parser.datas2Parse=`[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`;</code></p>
<h3>Importer les données à partir dune source distante</h3>
<p>Le dernier argument, vous permet de passer une instance de la classe RemoteSource quil 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 nimporte quelle classe validant linterface 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>Vous pouvez fournir des entêtes pour lappel à la source de données distantes:<br />
<code>mySource.headers=[ { key:"token", value:"1234" }, { key:"userName", value:"Toto" }];</code></p>
<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 linstanciation en utilisant le <em>setter</em>:<br />
<code>myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv" });</code><br />
Dans ce cas limportation 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>
<h3>Définir lélément du DOM où seront afficher les 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 soccupe dafficher les données, vous pouvez indiquer lid 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>Parser les données</h3>
<p>Pour lancer le parsage, utilisez la méthode <em>run()</em> qui est asynchrone:<br />
<code>await myConverter.run();</code></p>
<p>En cas de succès du parsage, si lid de lélément du DOM devant recevoir les données est connu, elles seront automatiquement affichées dans la page.</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>
<h4>Tolérance aux erreurs de parsage</h4>
<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 lindiquer 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>Adapter le rendu visuel des données</h3>
<p>Par défaut toutes les données trouvées seront affichées sous forme de tableau sans classe CSS particulière:</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>
<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 />
<code>myConverter.fields2Rend=[0,2]; // naffichera que le 1ᵉʳ et le troisième champ, la numérotation commençant à zéro.</code></p>
<p>Ce setter provoquera une erreur si vous fournissez un numéro de champ nexistant 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>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>Adapter le code HTML généré pour laffichage des données</h4>
<p>Pour spécifier le code HTML à générer, vous devez créer une instance de la classe <em>Render</em> ou dune autre classe validant linterface <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 limporter:<br />
<code>import { FreeDatas2HTML, Render } from "./modules/FreeDatas2HTML";</code></p>
<p>Puis linstancier:<br />
<code>const myRender=new Render();</code><br />
Et utiliser lattribut <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>
<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>Dans les deux cas, il faut ensuite attribuer votre <em>Render</em> à votre instance de FreeDatas2HTML:<br />
<code>myConverter.datasRender=myRender;</code></p>
2022-03-04 17:19:47 +01:00
<h4>Besoin d'un rendu complexe, fusionnant plusieurs champs?</h4>
<p>Il est possible dobtenir un rendu plus complexe, mixant les données venant de plusieurs champs. Cest par exemple le cas si vous souhaitez créer un lien dont lURL se trouve dans un champ et lancre dans un autre.</p>
<p>Ceci est possible via lextension <strong><em>MixedFieldsRender.ts</em></strong>. Cette documentation ne présente pas lusage de cette extension pour linstant, 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 lexemple 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 dune association</a> pour lister ses partenaires à partir dun fichier <em>CSV</em>.</p>
<h3>Affichage dun compteur</h3>
<p>Si vous souhaitez afficher quelque part le nombre denregistrements, il vous suffit de fournir lid 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 lutilisateur, mais ignore la pagination qui nest quune 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», cest-à-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 dutiliser votre propre fonction de classement, ce qui sera expliqué plus loin.</p>
<p>Si plusieurs filtres sont proposés à lutilisateur final, seuls les enregistrements validant tous les choix de lutilisateur seront affichés.</p>
<p>Pour ajouter un filtre, commencer par linclure 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 lid 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 dindiquer 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 dabord avoir parsé vos données avant de créer votre instance de Selector</strong>, car lexistence du champ fourni en paramètre est testé à cette étape.</p>
<p>Une fois votre instance créée, en attribut supplémentaire permettra à lutilisateur de sélectionner plusieurs valeurs dans la liste:<br />
<code>myFilter2.isMultiple=true;</code><br />
Ce nest 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>Linstanciation 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 sagit dun 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 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>
<p>&nbsp;</p>
<p><strong>À SUIVRE DOCUMENTATION EN COURS DÉCRITURE</strong></p>
2022-03-04 17:19:47 +01:00
</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>
</body>
</html>