FreeDatas2HTML/public/documentation.html

167 lines
12 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>
<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>