Exporter en CSV les contenus d'un projet Drupal 8

Le besoin d'exporter les contenus d'un projet Drupal 8 est un besoin récurrent, que ce soit à des fins d'analyse ou encore de mise à jour en masse avec un processus d'importation concomitant. Nous disposons de plusieurs solutions avec Drupal 8 qui chacune présente des avantages et des inconvénients, que ce soit au niveau des types de contenu exportables, des options d'export des entêtes de colonnes et des valeurs, du niveau de droits d'accès requis et des options de configuration très variables. Nous allons ici vous présenter un nouveau module Entity Export CSV qui semble pouvoir répondre à de nombreux cas d'usage.

Encore un nouveau module d'export CSV ?

Nous disposons de nombreuses solutions pour mettre en place un export CSV sur un projet. Essayons d'en lister quelque unes sans vouloir être exhaustif.

Le module Views Data Export comme son nom l'indique se base sur le module Views du Core pour configurer et mettre en place des export CSV. Grâce à l'utilisation de Views nous pouvons alors configurer un export sur n'importe quelle entité de Drupal 8, généralement sur un bundle particulier. Nous avons besoin alors de configurer autant de vues que d'export nécessaires et certaines limites peuvent apparaître quand il s'agit de procéder à l'export de champ multiples. La mise en place d'export CSV avec ce module nécessite des droits d'administration permettant la création et la gestion des vues d'un projet Drupal 8, avec une certaine compréhension du fonctionnement de Views. Il n'est donc pas vraiment destiné à des utilisateurs finaux.

Le module Content Export CSV permet d'exporter rapidement les noeuds d'un site Drupal 8. Ses options de configuration sont très limitées, notamment du choix des champs exportées et de leur valeur, outre le fait que seuls les noeuds sont exportables avec ce module. A contrario ce module peut être utilisé directement par les utilisateurs finaux.

Le module Entity Content Export permet de nombreuses options de configuration. Il permet d'exporter toutes les entités de contenus de Drupal 8 et les exports de chaque entité peuvent être configurés en s'appuyant sur les modes d'affichage des entités, et notamment les formateurs de champs que nous pouvons sélectionner et configurer pour tel ou tel export de contenu. Il nécessite toutefois une configuration initiale conséquente, avec des droits d'accès en matière d'administration très élevés, au niveau de chaque paquet d'entité qu'on souhaite rendre exportable.

Pour les besoins d'un projet d'usine à sites Drupal, chacune de ses solutions pouvait y répondre en partie mais pas totalement. Notamment car il n'était pas possible de connaître par avance quel type de contenu ou quel type d'entité il était nécessaire de pouvoir exporter, comment le type de contenu était configuré et utilisé (dans le cas de types de contenu génériques personnalisables par instance de l'usine à sites) et surtout que toute configuration et mise en place de ces exports CSV devaient pouvoir être réalisée par des utilisateurs finaux, sans connaissance particulière de Drupal, ni droits d'accès sur la configuration d'un projet Drupal 8.

Introduction du module Entity Export CSV

C'est pour répondre à ces enjeux que le module Entity Export CSV a été créé.

• Pouvoir exporter n'importe quelle entité de contenu de Drupal 8
• Pouvoir sélectionner quels champs sont exportables pour chaque entité et chaque paquet
• Pouvoir configurer comment sont exportés chaque champ d'une entité
• Pouvoir configurer champs par champs leur comportement en matière d'export lorsqu'il s'agit de champs multiples (export dans un seule colonne avec séparateur et export de chaque valeur dans un colonne distincte)
• Être facilement personnalisable pour l'export d'un champ particulier, avec un besoin métier spécifique
• Être utilisable par un utilisateur final sans droits d'administration particulier sur la configuration d'un projet Drupal 8 (Views, Mode d'affichages des entités, etc.)

En terme d'architecture, pour pouvoir répondre à ces enjeux, Entity Export CSV s'appuie sur :

• une simple page de configuration permettant de sélectionner quelles seront, parmi les entités de contenu présentes sur un projet, les entités exportables et le cas échéant de les limiter à un ou plusieurs paquets, et également de limiter (ou non) les champs de ces paquets d'entité qui seront exportable
• une simple page d'export, permettant sur la base de la configuration initiale de sélection l'entité à exporter, son paquet, puis de configurer pour chaque champ s'il doit être inclus dans l'export et le cas échéant comment on souhaite que celui-ci soit exporté

Présentation détaillée du fonctionnement de Entity Export CSV

Une fois le module installé, comme indiqué plus haut il convient dans un premier temps de configurer les entités exportables, qui seront accessibles dans la page d'export.

La configuration est assez simple. Pour chaque type d'entité disponible sur le projet nous sélectionnons celles que nous voulons rendre exportable, et nous pouvons limiter les paquets par type d'entité qui seront exportables.

Puis pour chaque entité et paquet activé, nous pouvons aussi limiter les champs qui seront exportables, ceci par exemple afin de ne pas surcharger la page d'export avec les champs dits techniques d'une entité (uuid, revision, ou tout autre champ ajouté sur l'entité qui ne contient pas de contenu à proprement parler).

Puis il suffit de rendre sur la page d'export CSV proprement dite.

Les utilisateurs peuvent configurer pour chaque champs, si celui-ci doit être inclus dans l'export, comment l'entête de colonne sera alimentée (Nom lisible du champ ou nom système), le nombre de colonnes à utiliser pour le cas des champs multiple ainsi que le format d'export à utiliser pour chaque champs.

Une fois la configuration finie, l'utilisateur peut enregistrer cette configuration afin de ne pas avoir à procéder à une autre configuration lors d'un prochain export. Chaque configuration est enregistrée pour un type d'entité, un paquet et par utilisateur. Une évolution programmée sera de pouvoir configurer des exports de configuration pour chaque type d'entité et paquet, de façon illimitée, et utiliser alors ici ces configurations d'export comme modèle réutilisable.

Chaque champ peut être configuré différemment au niveau de l'entête de colonne utilisée pour son export, et au niveau de la valeur exportée. Pour ce faire le module dispose d'un système de Plugin FieldTypeExport qui permet de créer très facilement des exports de champs configurable et/ou spécifique. Par exemple ci-dessous le champs "Modifié" est configuré avec le plugin Timestamp export qui expose comme option le formatage de la date.

Un autre plugin fourni de base par le module permet de configurer comment sont exportés les champs de type Entity Reference. Par exemple si nous souhaitons exporter l'identifiant de l'entité référencée ou son label, et pour le cas d'un champ multiple le nombre de colonnes à utiliser pour exporter les valeurs.

Extension du module Entity Export CSV

Un des enjeux auxquels répond le module est de pouvoir être facilement extensible et/ou personnalisable. Rare sont les projets Drupal 8 où un champs ne rentre pas dans une case générique et nécessite un traitement particulier.

Le module Entity Export CSV s'appuie sur un système de Plugin pour exporter tous les champs et de ce fait peut être très facilement étendu par un Développeur Drupal 8 pour supporter tout type de cas particulier ou encore des champs créés par des modules contribués (le module par exemple inclut de base un Plugin pour les champs du module Geolocation et du module Address).

Pour créer un Plugin d'export de champ, il faut donc créer un Plugin de type FieldTypeExport dans l'espace de nom src/Plugin/FieldTypeExport de n'importe quel module Drupal 8.

Les annotations de ce plugin permettent de contrôler certains comportements du Plugin et sa disponibilité. Regardons ces annotations avec l'exemple du plugin Geolocation inclus dans le module

namespace Drupal\entity_export_csv\Plugin\FieldTypeExport;

use Drupal\Core\Field\FieldDefinitionInterface;
use Drupal\Core\Form\FormStateInterface;
use Drupal\entity_export_csv\Plugin\FieldTypeExportBase;
use Drupal\Core\Field\FieldItemInterface;

/**
 * Defines a Geolocation field type export plugin.
 *
 * @FieldTypeExport(
 *   id = "geolocation_export",
 *   label = @Translation("Geolocation export"),
 *   description = @Translation("Geolocation export"),
 *   weight = 0,
 *   field_type = {
 *     "geolocation",
 *   },
 *   entity_type = {},
 *   bundle = {},
 *   field_name = {},
 *   exclusive = FALSE,
 * )
 */
class GeolocationExport extends FieldTypeExportBase {

  /**
   * {@inheritdoc}
   */
  public function getSummary() {
    return [
      'message' => [
        '#markup' => $this->t('Geolocation field type exporter.'),
      ],
    ];
  }

  /**
   * {@inheritdoc}
   */
  public function buildConfigurationForm(array $form, FormStateInterface $form_state, FieldDefinitionInterface $field_definition) {
    $configuration = $this->getConfiguration();
    $build = parent::buildConfigurationForm($form, $form_state, $field_definition);
    return $build;
  }

  /**
   * {@inheritdoc}
   */
  public function massageExportPropertyValue(FieldItemInterface $field_item, $property_name, FieldDefinitionInterface $field_definition, $options = []) {
    // Stuff to format field item value.
  }

  /**
   * {@inheritdoc}
   */
  protected function getFormatExportOptions(FieldDefinitionInterface $field_definition) {
    $options = parent::getFormatExportOptions($field_definition);
    return $options;
  }

}

Les annotations d'un plugin FieldTypeExport sont :

• weight : le poids du plugin. Le plugin avec le poids le plus haut sera le plugin sélectionné par défaut si plusieurs plugin sont disponibles pour un champs
• field_type : le type de champs auquel s'applique le plugin. On peut indiquer plusieurs types de champs le cas échéant. Cette option est obligatoire.
• entity_type : il est possible ici de limiter le plugin à seulement certains types d'entité. Laissez vide et le plugin sera disponible pour le type de champ sur tout type d'entité
• bundle : il est possible ici de limiter le plugin à seulement certains paquets d'entité. Laissez vide et le plugin sera disponible pour le type de champ sur tous les paquets
• field_name: il est possible ici de limiter le plugin à un seul champ particulier. Laissez vide et le plugin sera disponible pour le type de champ sur tous les champs de ce type.
• exclusive : cette option si définie à TRUE permet de rendre ce plugin exclusif, autrement dit tous les autres plugin disponibles pour ce type de champs ne seront plus visible. Utile si on souhaite par un champ particulier limiter les options possibles pour exporter un champs spécifique. Par défaut la valeur est FALSE.

Vous pouvez alors surcharger toutes les méthodes disponibles sur le Plugin de base afin de personnaliser le rendu d'export du champs. Notamment vous pouvez exposer de nouvelles options de configuration, et bien entendu implémenter la méthode massageExportPropertyValue() qui est en charge de formater l'export d'une instance de champ.

A vos exports

Le module Entity Export CSV permet de donner accès à des fonctions d'export avancées à des utilisateurs finaux qui ne disposent pas forcément d'une connaissance approfondie de Drupal ni de droits de configuration avancés. Il permet de mettre à disposition rapidement des fonctions d'export, sur tout type d'entité, tout en restant totalement indépendant de la configuration d'un projet et à ce titre peut être intégré sur tout type de projet, dont notamment des projets de type usine à sites. L'interface simplifiée qu'il met à disposition des utilisateurs ne se fait pas au détriment de cas plus ou moins complexes, grâce à son système de Plugin qui permet de traiter tous les besoins métier un peu spécifique à très peu de frais.

Besoin d'un export CSV ? Pensez à Entity Export CSV !