Comment créer un plugin de processeur Search API compatible Solr dans Drupal 10

Dans Drupal, l'intégration avec Solr pour des fonctionnalités de recherche puissantes est courante. Parfois, vous pourriez avoir besoin de combiner des informations provenant de plusieurs champs pour créer un nouveau champ personnalisé pour la recherche Solr. Ce guide vous montre comment créer un plugin de processeur Search API compatible Solr dans Drupal 10. Ce guide est également compatible avec Drupal 8 et 9.

Prérequis

1. Une installation fonctionnelle de Drupal 8, 9 ou 10
2. Moteur de recherche Solr intégré à Drupal
3. Un type de contenu personnalisé nommé Club avec un champ personnalisé field_cl_district_name. (Note : Le champ title est une propriété par défaut pour tout type de contenu Drupal. Aux fins de cet article, un champ personnalisé pour le nom du district est ajouté au type de contenu. Vous devriez créer ou utiliser un type de contenu réel pertinent pour votre projet.)
4. Module Search API de Drupal installé et activé
5. Module Search API Solr installé et activé
6. Module personnalisé nommé my_custom_module (vous pouvez le nommer comme vous le souhaitez)

Compatibilité Solr

Ce guide est conçu pour être compatible avec Solr, l'un des backends de recherche les plus populaires utilisés avec Drupal. Le plugin de processeur Search API personnalisé que vous allez créer peut être configuré pour fonctionner de manière transparente avec Solr, améliorant ainsi les capacités de recherche de votre site.

Création du plugin de processeur Search API

Étape 1 : Préparer votre module personnalisé

Si vous n'avez pas encore créé de module personnalisé, vous devez d'abord le configurer. Créez un dossier sous modules/custom nommé my_custom_module. À l'intérieur, vous aurez besoin d'un fichier my_custom_module.info.yml avec le contenu suivant :

name: 'Mon Module Personnalisé'
type: module
description: 'Un module personnalisé pour étendre les fonctionnalités de Drupal.'
core_version_requirement: ^8 || ^9 || ^10
package: Custom

Étape 2 : Créer la classe du plugin

Créez un fichier PHP nommé FullClubName.php dans modules / custom / my_custom_module / src / Plugin / search_api / processor.

Voici à quoi ressemblerait le fichier FullClubName.php :

<?php

namespace Drupal\my_custom_module\Plugin\search_api\processor;

use Drupal\search_api\Datasource\DatasourceInterface;
use Drupal\search_api\Processor\ProcessorPluginBase;
use Drupal\search_api\Item\ItemInterface;
use Drupal\search_api\Processor\ProcessorProperty;

/**
 * @SearchApiProcessor(
 *   id = "full_club_name",
 *   label = @Translation("Nom Complet du Club"),
 *   description = @Translation("Combine les champs Titre et District pour les clubs."),
 *   stages = {
 *     "add_properties" = 0,
 *   },
 *   locked = true,
 *   hidden = true,
 * )
 */
class FullClubName extends ProcessorPluginBase {

  public function getPropertyDefinitions(DatasourceInterface $datasource = NULL) {
    $properties = [];

    if (!$datasource) {
      $definition = [
        'label' => $this->t('Nom Complet du Club'),
        'description' => $this->t('Combine les champs Titre et District pour les clubs.'),
        'type' => 'string',
        'processor_id' => $this->getPluginId(),
      ];
      $properties['full_club_name'] = new ProcessorProperty($definition);
    }

    return $properties;
  }

  public function addFieldValues(ItemInterface $item) {
    $entity = $item->getOriginalObject()->getValue();
    if ($entity->bundle() === 'club') {
      $title = $entity->get('title')->getString();
      $district = $entity->get('field_cl_district_name')->getString();

      $combined_value = $title . ' (' . $district . ')';
      $fields = $this->getFieldsHelper()
        ->filterForPropertyPath($item->getFields(), NULL, 'full_club_name');
      foreach ($fields as $field) {
        $field->addValue($combined_value);
      }
    }
  }
}

Annotation expliquée

• @SearchApiProcessor : Cette annotation déclare la classe comme un plugin de processeur Search API.
• id = "full_club_name" : Le nom de machine interne du plugin, qui doit être unique.
• label = @Translation("Nom Complet du Club") : Le libellé lisible par l'homme pour le plugin, qui peut être traduit.
• description = @Translation("Combine les champs Titre et District pour les clubs.") : Fournit plus d'informations sur ce que fait ce plugin de processeur.
• stages = { "add_properties" = 0 } : Spécifie que ce plugin opère au stade « add_properties » avec un poids de 0.
• locked = true : Le processeur est verrouillé sur l'index et ne peut pas être supprimé via l'interface d'administration.
• hidden = true : Le processeur est masqué dans l'interface d'administration.

Cette annotation est essentielle car elle définit comment Drupal doit traiter la classe qui suit. Elle spécifie tout, de l'ID et du libellé du plugin à un comportement plus nuancé comme les étapes auxquelles il participe et s'il est verrouillé ou masqué dans l'interface utilisateur.

Méthodes expliquées

Après avoir défini l'annotation du plugin, le cœur de votre plugin réside dans les méthodes que vous implémentez. Voici les méthodes essentielles dont vous aurez généralement besoin dans un plugin de processeur Search API et ce que fait chacune d'elles :

getPropertyDefinitions(DatasourceInterface $datasource = NULL)

Cette méthode est responsable de la définition des nouvelles propriétés que le plugin ajoutera ou manipulera. Elle est appelée pendant l'étape « add_properties » comme spécifié dans l'annotation de notre plugin. Si votre plugin doit créer de nouveaux champs pour l'index de recherche, c'est ici que vous les définissez.

preprocessIndexItems(PreprocessIndexItemsEvent $event)

Cette méthode est appelée pour remplir les valeurs des champs que vous avez définis dans getPropertyDefinitions(). Si vous manipulez des champs existants ou en ajoutez de nouveaux, vous spécifiez la logique ici. Elle reçoit un objet événement qui contient tous les éléments sur le point d'être indexés, vous permettant de modifier leurs propriétés avant qu'ils ne soient envoyés à l'index de recherche.

Étape 3 : Activer le plugin et vider le cache

Après avoir écrit le code de votre plugin de processeur Search API personnalisé, vous devez vous assurer qu'il est reconnu par Drupal et par Search API.

Si le module n'est pas encore activé

Si votre module personnalisé n'est pas encore activé, accédez à la page Étendre (/admin/modules) dans votre interface d'administration Drupal, trouvez votre module personnalisé et activez-le.

Si le module est déjà activé

Si votre module personnalisé contenant le plugin est déjà activé, Drupal ne détectera pas automatiquement le nouveau plugin. Vous devrez vider le cache pour que les modifications prennent effet. Vous pouvez vider le cache via l'interface d'administration en accédant à Configuration > Développement > Performance (/admin / config / development / performance) et en cliquant sur « Vider tous les caches ».

Alternativement, vous pouvez vider le cache en utilisant Drush avec la commande suivante :

drush cr

Étape 4 : Configurer l'index Search API

Après avoir activé le module et vidé le cache, accédez aux paramètres des champs de votre index Search API en allant sur /admin/config/search/search-api/index/your-index/fields.

1. Cliquez sur le bouton « Ajouter des champs », généralement situé en haut de la page. Cette action révélera une liste des champs disponibles.
2. Dans cette liste, vous devriez trouver votre nouveau champ personnalisé intitulé Nom Complet du Club.
3. Sélectionnez ce champ, puis cliquez sur le bouton « Ajouter » à côté du nom du champ pour l'inclure dans votre index.
4. Cliquez sur Terminé.
5. Enfin, réindexez votre contenu pour vous assurer que le nouveau champ personnalisé est rempli et devient consultable.

Utilisation du champ personnalisé dans les vues et la recherche

Une fois que vous avez activé votre module personnalisé et vidé le cache, votre plugin de processeur Search API personnalisé devrait être activé. Ce que cela signifie pour vous :

Disponibilité du champ dans la vue d'index

Votre nouveau champ personnalisé Nom Complet du Club sera disponible dans la liste des champs lorsque vous créez ou modifiez une vue d'index dans Drupal. Cela vous donne la possibilité d'inclure ces données agrégées dans vos résultats de recherche ou vos listes de vues.

Filtres de recherche plein texte

Si vous avez défini le champ personnalisé comme type « Texte intégral » dans vos paramètres Search API, vous pouvez également utiliser ce champ comme critère de filtre dans la vue d'index. Cela permet aux utilisateurs d'effectuer des requêtes de recherche plein texte spécifiquement sur ce champ combiné, améliorant potentiellement la précision et la pertinence des résultats de recherche.

Conclusion

Ce guide vous a guidé à travers le processus de création d'un plugin de processeur Search API personnalisé dans Drupal 8, 9 et 10. Le plugin, nommé FullClubName, combine les champs title et field_cl_district_name du type de contenu Club en un seul champ consultable. Cela améliore vos capacités de recherche et est un exemple parfait de la flexibilité et de l'extensibilité de Drupal.

Bon débogage !