Fab_Blab/FreeDatas2HTML
1
1
Fork 0
Code Issues Pull Requests Projects Releases Activity

Ajout page documentation (en cours d'écriture)

Browse Source
This commit is contained in:
Fabrice PENHOËT 2022-03-03 19:06:39 +01:00
parent 62e4e85eb7
commit e920f020f7
10 changed files with 176 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

167
public/documentation.html Normal file
View File

@ -0,0 +1,167 @@
<!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 l’instant FreeDatas2HTML n’est 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 n’importe 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 d’importer d’autres 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 d’indiquer 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 d’une 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 l’instanciation :<br />
<code>myConverter.parser.datas2Parse=`[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`;</code></p>
<h3>Importer les données à partir d’une source distante</h3>
<p>Le dernier argument, vous permet de passer une instance de la classe RemoteSource qu’il 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 n’importe quelle classe validant l’interface 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 l’appel à 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 l’instanciation en utilisant le <em>setter</em> :<br />
<code>myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv" });</code><br />
Dans ce cas l’importation 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 s’occupe d’afficher les données, vous pouvez indiquer l’id 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 l’id 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 l’indiquer 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]; // n’affichera 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 n’existant 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 l’affichage 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 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>.<br />
Dans le cas de la classe <em>Render</em>, il faut commencer par l’importer :<br />
<code>import { FreeDatas2HTML, Render } from "./modules/FreeDatas2HTML";</code></p>
<p>Puis l’instancier :<br />
<code>const myRender=new Render();</code><br />
Et utiliser l’attribut <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>

1
public/examples.html
View File

@ -19,6 +19,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/index.html
View File

@ -19,6 +19,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/mentions-legales.html
View File

@ -18,6 +18,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/userFile.html
View File

@ -19,6 +19,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/withCSV.html
View File

@ -19,6 +19,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/withHTML.html
View File

@ -20,6 +20,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/withJSON.html
View File

@ -20,6 +20,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/withMixedFields.html
View File

@ -20,6 +20,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>

1
public/withUL.html
View File

@ -20,6 +20,7 @@
<ul class="inline row flex-center"> <ul class="inline row flex-center">
<li><a href="./#intro" class="badge warning sm-12 col">Introduction</a></li> <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="./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> <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> </ul>
</nav> </nav>