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
+ +