Documentation en ligne

Connecteur avec un fichier tableur (CSV ou ODS)

Dans un formulaire on peut avoir besoin d'une liste d'éléments provenant d'une source extérieure (ça permet de réutiliser ladite liste dans plusieurs formulaires, et facilite sa maintenance).

La façon la plus simple de mettre en place une telle liste, est de faire un fichier tableur (au format CSV ou ODS) qui servira de base à la mise enplace d'un connecteur dans Passerelle.

Cela se fait en plusieurs étapes :

  1. préparation du fichier tableur
  2. création d'un connecteur qui va diffuser le contenu du fichier sous la forme d'une ressource Web;
  3. ajout d'une source de données dans la fabrique de formulaires, afin de rendre les élements de ce connecteur plus facilement utilisables dans tous les formulaires.

Préparation du fichier tableur

Le fichier tableur doit avoir au moins deux colonnes :

  • une première colonne contenant un identifiant unique pour chaque ligne (valeur numérique ou texte, peu importe)
  • une seconde colonne contenant les éléments que l'on souhaite faire apparaître dans la liste du formulaire.

Le fichier peut comporter d'autres colonnes, comprenant des informations qui seront elles aussi exploitables dans le formulaire.

Si vous souhaitez gérer des éléments désactivés (qui n'apparaîtront pas dans la liste du formulaire), vous devez prévoir une colonne « disabled » qui sera vide pour les éléments à afficher et complétée d'une valeur, quelconque, pour les éléments désactivés.

Prenons l'exemple d'un fichier dans lequel chaque arrondissement est représenté par son numéro :

Identifiant Arrondissement Population
1 1er arrondissement 25000
2 2nd arrondissement 35000
3 3ème arrondissement 45000

Attention, les fichiers doivent être encodés en UTF-8.

Création d'un connecteur CSV

Pour transformer ce fichier en connecteur :

  1. se rendre dans le menu «Services web»
  2. cliquer sur «Ajouter un connecteur» (en haut à droite)
  3. dans la ligne «Sources des données», cliquer sur «Fichier tableur»
  4. compléter les champs nécessaires :
    1. Titre : donner un nom à votre source de données.
    2. Description : rappeler son objectif.
    3. Fichier tableur : joignez ici votre fichier CSV ou ODS.
    4. Noms des clés pour les colonnes : ici il faut donner un nom (sans accents ni espace) à chaque colonne du fichier. Les noms sont séparés par des virgules. Pour notre fichier exemple on aura :
      1. id (nom obligatoire, qui désigne la colonne de l'identifiant)
      2. text (nom obligatoire, qui désigne la colonne devant apparaître dans la liste)
      3. population (nom libre choisi pour désigner la troisième colonne)
    5. Passer la première ligne : si la première ligne de votre fichier contient le nom des colonnes (comme dans l'exemple donné) alors il faut cocher cette case pour que la première ligne ne soit pas considérée comme faisant partie des données.
    6. Nom de la feuille : à renseigner quand vous utilisez le format ODS, pour indiquer la feuille à utiliser, par exemple : «Feuil1».
  5. Cliquer sur «Enregistrer».

La page de présentation du connecteur s'affiche alors, indiquant les Points d'accès du connecteur (ce qu'on appelle aussi les endpoints de l'API, c'est-à-dire les adresses par lesquelles les données sont accessibles.)

Il faut alors régler la sécurité du connecteur, car par défaut celui-ci est inaccessible. Pour cela, en dessous du tableau «Sécurité», cliquer sur «Ajouter» et ajouter l'utilisateur Passerelle de votre choix. En général un utilisateur «Public» est disponible qui autorise un accès public au connecteur.

Votre connecteur CSV est maintenant créé. Vous devez noter son adresse, qui doit être du type :

  • {{passerelle_url}}csvdatasource/nom-de-la-source/

Le point d'accès aux données est le suivant :

  • {{passerelle_url}}csvdatasource/nom-de-la-source/data
Si vous obtenez une erreur 403 en essayant d'accéder à votre connecteur c'est certainement parce que vous n'avez pas l'autorisation d'accéder à l'API. Cette autorisation se règle sur la partie inférieure de l'écran d'accueil : « Sécurité » et sur l'url {{passerelle_url}}manage/access/

Création de la source de données associée

Votre connecteur nouvellement créé est déjà utilisable dans un formulaire. Mais si vous envisagez de l'utiliser dans plusieurs formulaires, faîtes-vous une faveur : créez une source de donnée liée à ce connecteur. Elle va vous permettre de réutiliser la liste beaucoup plus simplement et sans risque d'erreur. Pour créer cette source, vous devez vous rendre dans la fabrique de formulaires et utiliser le lien «Sources de données» en haut à droite.

Cliquez sur «Nouvelle source de données», toujours dans la colonne droite.

  • Indiquer un nom et une description, généralement les mêmes que ceux choisis lors de la configuration du connecteur CSV.
  • Au niveau de «Source de données», choisir le type «URL du JSON».
  • Indiquer ensuite l'URL du point d'accès aux données, voir ci-dessus. Il s'agit de l'adresse URL du connecteur suivie de /data.

Votre liste est maintenant disponible dans «Source de données» (dans les paramètres avancés) lorsque vous éditez un champ de type liste dans un formulaire.

Si un champ liste (identifiant « liste ») est lié à un fichier tableur comprenant les colonnes « nom » et « prenom », on récupèrera le contenu de ces colonnes dans les variables {{ form_var_liste_nom }} et {{ form_var_liste_prenom }}. Dans notre exemple {{ form_var_liste_population }} contiendra « 25000 » si form_var_liste contient « 1er arrondissement ».

Il est possible de construire des requêtes pour aller plus loin dans l'utilisation des données contenues dans un fichier CSV ou ODS.

Dernière mise à jour le 29 novembre 2018 18:29 — Éditer