FreeDatas2HTML/public/documentation.html

167 lines
12 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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>
<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>
</body>
</html>