29 agosto 2023

In Drupal, l'integrazione con Solr per potenti funzionalità di ricerca è comune. A volte, potresti dover combinare informazioni da più campi per creare un nuovo campo personalizzato per la ricerca Solr. Questa guida mostra come creare un Plugin Processore per Search API compatibile con Solr in Drupal 10. Questa guida è compatibile anche con Drupal 8 e 9.

Prerequisiti

Un'installazione funzionante di Drupal 8, 9 o 10
Motore di ricerca Solr integrato con Drupal
Un tipo di contenuto personalizzato denominato Club con un campo personalizzato field_cl_district_name. (Nota: il campo title è una proprietà predefinita per qualsiasi tipo di contenuto Drupal. Ai fini di questo articolo, viene aggiunto un campo personalizzato per il nome del distretto al tipo di contenuto. Dovresti creare o utilizzare un tipo di contenuto effettivo pertinente al tuo progetto.)
Modulo Search API di Drupal installato e abilitato
Modulo Search API Solr installato e abilitato
Modulo personalizzato denominato my_custom_module (puoi nominarlo come preferisci)

Compatibilità Solr

Questa guida è progettata per essere compatibile con Solr, uno dei backend di ricerca più popolari utilizzati con Drupal. Il Plugin Processore per Search API personalizzato che creerai può essere configurato per funzionare senza interruzioni con Solr, migliorando le capacità di ricerca del tuo sito.

Creazione del Plugin Processore per Search API

Passaggio 1: Prepara il tuo Modulo Personalizzato

Se non hai ancora creato un modulo personalizzato, devi prima configurarlo. Crea una cartella sotto modules/custom denominata my_custom_module. All'interno, avrai bisogno di un file my_custom_module.info.yml con il seguente contenuto:

name: 'My Custom Module'
type: module
description: 'A custom module to extend Drupal functionalities.'
core_version_requirement: ^8 || ^9 || ^10
package: Custom

Passaggio 2: Crea la Classe del Plugin

Crea un file PHP denominato FullClubName.php all'interno di modules / custom / my_custom_module / src / Plugin / search_api / processor.

Ecco come apparirebbe il file 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("Full Club Name"),
 *   description = @Translation("Combine Title and District fields for 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('Full Club Name'),
        'description' => $this->t('Combines the Title and District fields for 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);
      }
    }
  }
}

Annotazione Spiegata

@SearchApiProcessor: Questa annotazione dichiara la classe come Plugin Processore per Search API.
id = "full_club_name": Il nome macchina interno per il plugin, che deve essere univoco.
label = @Translation("Full Club Name"): L'etichetta leggibile dall'uomo per il plugin, che può essere tradotta.
description = @Translation("Combine Title and District fields for clubs."): Fornisce maggiori informazioni su cosa fa questo plugin processore.
stages = { "add_properties" = 0 }: Specifica che questo plugin opera nella fase “add_properties” con un peso di 0.
locked = true: Il processore è bloccato all'indice e non può essere rimosso tramite l'interfaccia di amministrazione.
hidden = true: Il processore è nascosto dall'interfaccia di amministrazione.

Questa annotazione è essenziale in quanto definisce come Drupal dovrebbe trattare la classe che segue. Specifica tutto, dall'ID e dall'etichetta del plugin a comportamenti più sfumati come le fasi in cui partecipa e se è bloccato o nascosto nell'interfaccia utente.

Metodi Spiegati

Dopo aver definito l'annotazione del plugin, il nucleo del tuo plugin risiede nei metodi che implementi. Ecco i metodi essenziali di cui avrai tipicamente bisogno in un Plugin Processore per Search API e cosa fa ciascuno:

getPropertyDefinitions(DatasourceInterface $datasource = NULL)

Questo metodo è responsabile della definizione di nuove proprietà che il plugin aggiungerà o manipolerà. Viene invocato durante la fase “add_properties” come specificato nella nostra annotazione del plugin. Se il tuo plugin necessita di creare nuovi campi per l'indice di ricerca, è qui che li definisci.

preprocessIndexItems(PreprocessIndexItemsEvent $event)

Questo metodo viene invocato per popolare i valori dei campi che hai definito in getPropertyDefinitions(). Se stai manipolando campi esistenti o aggiungendone di nuovi, specifichi la logica qui. Riceve un oggetto evento che contiene tutti gli elementi in procinto di essere indicizzati, permettendoti di modificarne le proprietà prima che vengano inviati all'indice di ricerca.

Passaggio 3: Abilitazione del Plugin e Pulizia della Cache

Dopo aver scritto il codice per il tuo Plugin Processore per Search API personalizzato, devi assicurarti che venga riconosciuto da Drupal e da Search API.

Se il modulo non è ancora abilitato

Se il tuo modulo personalizzato non è ancora abilitato, naviga alla pagina Estendi (/admin/modules) nella tua interfaccia di amministrazione di Drupal, trova il tuo modulo personalizzato e abilitalo.

Se il modulo è già abilitato

Se il tuo modulo personalizzato contenente il plugin è già abilitato, Drupal non rileverà automaticamente il nuovo plugin. Dovrai svuotare la cache affinché le modifiche abbiano effetto. Puoi svuotare la cache tramite l'interfaccia di amministrazione navigando su Configurazione > Sviluppo > Prestazioni (/admin / config / development / performance) e facendo clic su “Svuota tutte le cache”.

In alternativa, puoi svuotare la cache utilizzando Drush con il seguente comando:

drush cr

Passaggio 4: Configura l'Indice Search API

Dopo aver abilitato il modulo e svuotato la cache, naviga alle impostazioni dei campi del tuo indice Search API andando su /admin/config/search/search-api/index/your-index/fields.

Fai clic sul pulsante “Aggiungi campi”, solitamente situato in cima alla pagina. Questa azione rivelerà un elenco di campi disponibili.
In questo elenco, dovresti trovare il tuo campo personalizzato appena aggiunto etichettato come Full Club Name.
Seleziona questo campo e quindi fai clic sul pulsante “Aggiungi” accanto al nome del campo per includerlo nel tuo indice.
Fai clic su Fatto.
Infine, re-indicizza il tuo contenuto per assicurarti che il nuovo campo personalizzato sia popolato e diventi ricercabile.

Campi personalizzati aggiunti all'indice

Utilizzo del Campo Personalizzato in Viste e Ricerca

Una volta abilitato il tuo modulo personalizzato e svuotata la cache, il tuo Plugin Processore per Search API personalizzato dovrebbe essere attivo. Cosa significa questo per te:

Disponibilità del Campo nella Vista Indice

Il tuo nuovo campo personalizzato Full Club Name sarà disponibile nell'elenco dei campi quando crei o modifichi una vista indice in Drupal. Questo ti dà la possibilità di includere questi dati aggregati come parte dei tuoi risultati di ricerca o elenchi di viste.

Filtri di Ricerca Full-Text

Se hai definito il campo personalizzato come tipo “Full Text” nelle tue impostazioni di Search API, puoi anche utilizzare questo campo come criterio di filtro all'interno della vista indice. Ciò consente agli utenti di eseguire query di ricerca full-text specificamente su questo campo combinato, migliorando potenzialmente l'accuratezza e la pertinenza dei risultati di ricerca.

Conclusione

Questa guida ti ha accompagnato attraverso il processo di creazione di un Plugin Processore per Search API personalizzato in Drupal 8, 9 e 10. Il plugin, denominato FullClubName, combina i campi title e field_cl_district_name dal tipo di contenuto Club in un unico campo ricercabile. Ciò migliora le tue capacità di ricerca ed è un perfetto esempio di quanto Drupal possa essere flessibile ed estensibile.

Buona Debugging!

Solr

Come Creare un Plugin Processore per Search API Compatibile con Solr in Drupal 10