Documentation destinée aux développeurs de modèles
Les fichiers composant le Widget
La création d'un modèle de page personnalisé (custom template) nécessite la maîtrise du développement de pages Web et le respect de quelques spécificités propres à GRIST (JavaScript).
On retrouve les fichiers suivants :
| Fichier | Description |
|---|---|
| Index.html | Structure de base du Widget |
| Index.js | Code permettant d'animer le contenu du Widget, en le liant aux données de la base |
| Package.json (Optionnel) | Description du contenu du package et de ses éventuelles dépendances (librairies, par exemple) |
| Screen.css (Optionnel) | Feuille de style pour la mise en forme |
Structure d'un widget personnalisé
Gestion des données
Un Widget personnalisé est composé des fichiers suivants :
- Index.html: Ce fichier contient la structure de base du Widget. Vous pouvez y définir les éléments HTML nécessaires, tels que les boutons, les champs de saisie, les graphiques, etc...
Assurez-vous d'attribuer des classes ou des identifiants aux éléments avec lesquels vous souhaitez interagir à l'aide de JavaScript.
Index.js: Ce fichier contient le code JavaScript principal pour votre Widget. Vous utiliserez entre autres les fonctions fournies par GRIST pour interagir avec les données et les options. Il y a trois fonctions principales à retenir :
grist.ready(): Cette fonction est appelée lorsque le Widget est prêt à être utilisé. Vous pouvez y effectuer des initialisations ou des configurations supplémentaires.grist.onRecord(): Cette fonction est appelée chaque fois que le curseur est déplacé sur une nouvelle ligne de la table de données. Vous pouvez y accéder aux valeurs des colonnes et effectuer des actions en conséquence.grist.onRecords(): Cette fonction est appelée lorsque les données dans la table sont modifiées. Vous pouvez y réagir en mettant à jour le contenu du Widget en fonction des nouvelles données.grist.onOptions(): Cette fonction est appelée lorsque la configuration du Widget change. Vous pouvez y ajuster le comportement du Widget en fonction des nouvelles options.
Package.json (optionnel): Ce fichier est utilisé pour définir les dépendances et les scripts associés à votre Widget. Si vous utilisez des bibliothèques externes ou si vous avez des scripts supplémentaires à exécuter, vous pouvez les spécifier dans ce fichier. Voir documentation pour plus d'information sur la structure de ce fichier.
Screen.css (optionnel): Ce fichier est utilisé pour définir les styles CSS spécifiques à votre Widget. Vous pouvez personnaliser l'apparence du Widget en modifiant les règles CSS correspondantes.
Il est également possible d'ajouter des fonctionnalités plus avancées à votre Widget en utilisant des bibliothèques externes telles que D3.js pour les graphiques ou Axios pour les appels API. Assurez-vous d'inclure ces bibliothèques dans votre fichier HTML ou de les importer via le package.json si nécessaire.
Pour plus de détails, exemples et ressources sur la création de Widgets, nous vous recommandons de consulter la documentation en ligne de GRIST, notamment la page officielle, la page de support et la documentation spécifique aux Widgets. Vous pouvez également consulter notre documentation pour des instructions sur la création de Widgets et sur GRIST en général.
En explorant ces ressources, vous découvrirez de nombreux exemples et astuces pour développer des Widgets personnalisés puissants et interactifs dans GRIST. Amusez-vous bien et n'hésitez pas à expérimenter pour créer vos propres Widgets et nous les partager si vous voulez les publier pour tous !
Fonctions Javascript de Grist
Afin de mieux comprendre l'utilisation des fonctions Javascript de Grist, nous allons voir un exemple de code concret dans lequel les fonctions Grist sont implémentées.
La partie de code est issue d'un widget permettant d'afficher les informations des agents contenues dans une table de manière visuelle sur un badge.
Avant de commencer, il est nécessaire d'appeler l'API Grist :
<script src="https://docs.getgrist.com/grist-plugin-api.js"></script>
Le code Javascript est le suivant :
grist.ready({columns: [
{
name: 'Matricule',
// title: 'Matricule',
description: 'Matricule de l\'agent'
},
{
name: 'Nom',
// title:'Nom',
type:'Text',
optional: true,
description:'Nom de l\'agent',
},
{
name:'Prenom',
title:'Prénom',
type:'Text',
optional: true,
description:'Prénom de l\'agent'
},
{
name:'NumCarte',
title:'N° de carte',
// type:'Numeric',
optional: true,
description:'Numéro de la carte'
},
{
name:'Expiration',
title:'Date de fin',
type:'Date',
optional: true,
description: 'Fin de validité de la carte de l\'agent'
},
{
name:'Photo',
// title:'Photo',
description:'Photo de l\'agent',
optional:true
}
], requiredAccess: 'read table'});
grist.onRecord(function (record, mappings) {
const mapped = grist.mapColumnNames(record);
// Si toutes les colonnes sont mappées
if (mapped) {
document.getElementById('nom').innerText = mapped.Nom;
document.getElementById('prenom').innerText = mapped.Prenom;
document.getElementById('matricule').innerText = mapped.Matricule;
document.getElementById('numcarte').innerText = mapped.NumCarte;
document.getElementById('expiration').innerText = mapped.Expiration;
document.getElementById('photo').src = mapped.Photo;
console.log(`Using ${mappings.Nom} and ${mappings.Prenom}
and ${mappings.Matricule} and ${mappings.NumCarte}
and ${mappings.Expiration} and ${mappings.Photo} columns`);
} else {
console.error("Veuillez mapper toutes les colonnes obligatoires");
}
});
Fonction Ready
Dans un premier temps, nous appelons la fonction ready() afin d'indiquer que le widget est prêt à démarrer et nous y effectuons des initialisations. Ici, nous voulons pouvoir attribuer manuellement les colonnes. Nous avons donc renseigné les colonnes à mapper ainsi que leurs paramètres.
Si vous ne voulez pas renseigner de paramètres à vos colonnes, la fonction ready() ressemblera à cela :
grist.ready({columns: ['NomColonne', 'NomColonne2']});
Fonction onRecord
Nous appelons et initialisons ensuite la fonction onRecord() qui sera exécutée dès qu'une nouvelle ligne de la table sera sélectionnée.
Comme dit précédement, il est possible de prédéfinir le mappage des colonnes mais afin d'être plus flexible, nous avons rendu cela manuel. Il sera donc nécessaire de mapper les colonnes après la création d'une vue avec notre widget.
Pour se faire nous utilisons l'instruction console.log('Using ${mappings.[Variable-de-la-colonne]}').
L'instruction document.getElementById('nom').innerText = mapped.Nom permet d'associer les colonnes aux attributs du code HTML afin que le badge affiche les informations de l'agent sélectionné.
Maintenant, libre à vous de compléter votre code avec les fonctions Javascript ou bibliothèques que vous souhaitez pour réaliser votre widget.
Pour des explications plus appronfondies, vous pouvez vous référer à la documentation officielle.
Gestion des options
Les options sont destinées aux utilisateurs qui souhaitent paramétrer le template pour l'intégrer dans un document Grist. Elles permettent souvent de définir des options générales ou de faire le lien avec les données des tables de données.
Pour la création d’un panneau d’options, le code suivant sera utilisé :
// Stockage d'une valeur simple
await grist.setOption('color', '#FF0000');
// Stockage d'un objets complexe en Json
await grist.setOption('settings', {lines: 10, skipFirst: true});
// Lecture des anciennes données sauvegardées
const color = await grist.getOption('color');
// Réinitialisation des options
await grist.clearOptions();
// Prend et remplace les options.
await grist.getOptions();
await grist.setOptions({...});