Documentation FreeDatas2HTML
Installation FreeDatas2HTML
Pour l’instant FreeDatas2HTML n’est pas disponible sur NPM.
Vous devez donc en récupérer une copie sur le dépôt GIT du projet.
Si vous travaillez en TypeScript, vous pouvez directement utiliser les fichiers présents dans le répertoire /src et ignorer le sous-répertoire /build.
Si vous travaillez en JavaScript, vous devez au contraire utiliser les scripts présents dans le répertoire /src/build.
Importation de la classe principale
Une fois les scripts présents dans le répertoire de votre projet, vous pouvez les importer comme n’importe quel module :
import { FreeDatas2HTML } from "./modules/FreeDatas2HTML";
À supposer que les scripts soient situés dans le sous-répertoire FreeDatas2HTML du répertoire modules de votre projet.
Suivant ce que vous souhaitez faire, vous aurez peut-être besoin d’importer d’autres classes, comme indiqué plus loin.
Instanciation de la classe principale
Ensuite, dans votre script, vous pouvez créer votre instance de manière classique :
const myConverter=new FreeDatas2HTML("CSV");
Type de données
Le premier argument du constructeur est obligatoire et vous permet d’indiquer le format des données à parser, avec trois options possibles : « CSV », « JSON », « HTML ».
Fournir directement les données à parser
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 :
const myConverter=new FreeDatas2HTML("JSON", `[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`);
Mais vous pouvez très bien fournir ou modifier cette information après l’instanciation :
myConverter.parser.datas2Parse=`[{ "name": "Doe", "firstname" : "John" },{ "name": "Doe", "firstname" : "Janie" }]`;
Importer les données à partir d’une source distante
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 :
import { FreeDatas2HTML, RemoteSource } from "./modules/FreeDatas2HTML";
const mySource=new RemoteSource({ url:"https://www.example.com/datas.csv" });
const myConverter=new FreeDatas2HTML("CSV","", mySource);
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 interface.ts.
Vous pouvez fournir des entêtes pour l’appel à la source de données distantes :
mySource.headers=[ { key:"token", value:"1234" }, { key:"userName", value:"Toto" }];
Il vous est aussi possible de déclarer la propriété XMLHttpRequest.withCredentials :
source.withCredentials=true;
Mais vous pouvez aussi fournir la source de données distante après l’instanciation en utilisant le setter :
myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv" });
Dans ce cas l’importation préalable de la classe RemoteSource est inutile.
De nouveau, vous pouvez fournir des options :
myConverter.parser.setRemoteSource({ url:"https://www.example.com/datas.csv", headers:[{ key:"token", value:"1234" }], withCredentials:true });
Définir l’élément du DOM où seront afficher les données
Ceci est facultatif, car vous pouvez très bien simplement vouloir parser les données.
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 :
myConverter.datasViewElt={ id:"myDatas" };
L’élément doit exister dans la page, sans quoi le setter générera une erreur.
Parser les données
Pour lancer le parsage, utilisez la méthode run() qui est asynchrone :
await myConverter.run();
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.
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 :
const fields=myConverter.fields; // format de sortie: string[], exemple: ["fistname", "name"]
const datas=myConverter.datas; // format de sortie : {[index: string]:string}[], exemple: [{firstname:"Janie", name:"Doe"}, {firstname:"John", name:"Doe"}];
Les formats de sortie sont les mêmes, quel que soit le format des données parsées.
Tolérance aux erreurs de parsage
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.
Si vous souhaitez bloquer la suite quand cela arrive, il vous faut l’indiquer avant de lancer le parsage :
myConverter.stopIfParseErrors=true;
Par défaut, les erreurs de parsage sont tolérées.
Adapter le rendu visuel des données
Par défaut toutes les données trouvées seront affichées sous forme de tableau sans classe CSS particulière :
<table>
<thead><tr><td>firstname</td><td>name</td></tr></thead>
<tbody>
<tr><td>Janie</td><td>Doe</td></tr>
<tr><td>John</td><td>Doe</td></tr>
</tbody>
</table>
Ne pas afficher tous les champs disponibles
Si vous ne souhaitez pas afficher tous les champs trouvés dans votre fichier, vous pouvez indiquer ceux à garder :
myConverter.fields2Rend=[0,2]; // n’affichera que le 1ᵉʳ et le troisième champ, la numérotation commençant à zéro.
Ce setter provoquera une erreur si vous fournissez un numéro de champ n’existant pas les données parsées.
Vous pouvez par contre le déclarer à tout moment, pour prise en compte dès le prochain affichage.
Pour de nouveau afficher tous les champs (situation par défaut), il suffit de passer un tableau vide :
myConverter.fields2Rend=[];
Adapter le code HTML généré pour l’affichage des données
Pour spécifier le code HTML à générer, vous devez créer une instance de la classe Render ou d’une autre classe validant l’interface DatasRenders déclarée dans le script interface.ts.
Dans le cas de la classe Render, il faut commencer par l’importer :
import { FreeDatas2HTML, Render } from "./modules/FreeDatas2HTML";
Puis l’instancier :
const myRender=new Render();
Et utiliser l’attribut settings pour décrire ce que vous souhaitez obtenir :
myRender.settings=
{
allBegining:"<h4>Moi je préfère les listes aux tableaux !</h4>",
allEnding:"Pas vous ?",
linesBegining:"<ul>",
linesEnding:"</ul>",
lineBegining:"<li><ul>",
lineEnding:"</ul></li>",
dataDisplaying:"<li><b>#FIELDNAME :</b> #VALUE</li>",
};
Dans ce cas la configuration par défaut est écrasée par la valeur de settings.
Consulter le type DatasRendersSettings pour voir tous les attributs disponibles.
Si vous souhaitez simplement modifier un des attributs, vous pouvez le faire ainsi :
myRender.settings.allBegining="<table class='myTable'>";
Ici le tableau sera le même que précédément, seule la balise <table> recevra une classe CSS ou ce que vous voulez…
Dans les deux cas, il faut ensuite attribuer votre Render à votre instance de FreeDatas2HTML :
myConverter.datasRender=myRender;
À SUIVRE – DOCUMENTATION EN COURS D’ÉCRITURE