167 lines
12 KiB
HTML
167 lines
12 KiB
HTML
<!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" }], <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><table><br />
|
||
<thead><tr><td>firstname</td><td>name</td></tr></thead><br />
|
||
<tbody><br />
|
||
<tr><td>Janie</td><td>Doe</td></tr><br />
|
||
<tr><td>John</td><td>Doe</td></tr><br />
|
||
</tbody><br />
|
||
</table></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 />
|
||
allBegining:"<h4>Moi je préfère les listes aux tableaux !</h4>",<br />
|
||
allEnding:"Pas vous ?",<br />
|
||
linesBegining:"<ul>",<br />
|
||
linesEnding:"</ul>",<br />
|
||
lineBegining:"<li><ul>",<br />
|
||
lineEnding:"</ul></li>",<br />
|
||
dataDisplaying:"<li><b>#FIELDNAME :</b> #VALUE</li>",<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="<table class='myTable'>";</code><br />
|
||
Ici le tableau sera le même que précédément, seule la balise <em><table></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> |