29 augustus 2023

In Drupal is integratie met Solr voor krachtige zoekfunctionaliteit gebruikelijk. Soms moet je informatie uit meerdere velden combineren om een nieuw aangepast veld te creëren voor Solr-zoekopdrachten. Deze gids laat je zien hoe je een Solr-compatibele Search API Processor Plugin maakt in Drupal 10. Deze gids is ook compatibel met Drupal 8 en 9.

Vereisten

Een functionele Drupal 8, 9 of 10 installatie
Solr zoekmachine geïntegreerd met Drupal
Een aangepast content type genaamd Club met een aangepast veld field_cl_district_name. (Opmerking: Het title veld is een standaard eigenschap voor elk Drupal content type. Voor dit artikel is een aangepast veld voor de districtsnaam toegevoegd aan het content type. Je moet een relevant content type voor je project aanmaken of gebruiken.)
Drupal’s Search API module geïnstalleerd en ingeschakeld
Search API Solr module geïnstalleerd en ingeschakeld
Aangepaste module genaamd my_custom_module (je mag het een andere naam geven)

Solr Compatibiliteit

Deze gids is ontworpen om compatibel te zijn met Solr, een van de meest populaire zoekbackends die met Drupal worden gebruikt. De aangepaste Search API Processor Plugin die je gaat maken, kan worden geconfigureerd om naadloos met Solr te werken, waardoor de zoekmogelijkheden van je site worden verbeterd.

De Search API Processor Plugin maken

Stap 1: Je Aangepaste Module Voorbereiden

Als je nog geen aangepaste module hebt gemaakt, moet je deze eerst instellen. Maak een map aan onder modules/custom met de naam my_custom_module. Daarin heb je een my_custom_module.info.yml bestand nodig met de volgende inhoud:

name: 'Mijn Aangepaste Module'
type: module
description: 'Een aangepaste module om Drupal functionaliteiten uit te breiden.'
core_version_requirement: ^8 || ^9 || ^10
package: Custom

Stap 2: De Plugin Klasse Maken

Maak een PHP-bestand genaamd FullClubName.php aan in modules / custom / my_custom_module / src / Plugin / search_api / processor.

Hier zie je hoe het FullClubName.php bestand eruit zou zien:

<?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("Volledige Club Naam"),
 *   description = @Translation("Combineer Titel en District velden voor 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('Volledige Club Naam'),
        'description' => $this->t('Combineert de Titel en District velden voor 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);
      }
    }
  }
}

Annotatie Uitgelegd

@SearchApiProcessor: Deze annotatie verklaart de klasse als een Search API Processor Plugin.
id = "full_club_name": De interne machinenaam voor de plugin, die uniek moet zijn.
label = @Translation("Volledige Club Naam"): Het menselijk leesbare label voor de plugin, dat vertaald kan worden.
description = @Translation("Combineer Titel en District velden voor clubs."): Geeft meer informatie over wat deze processor plugin doet.
stages = { "add_properties" = 0 }: Specificeert dat deze plugin opereert in de “add_properties” fase met een gewicht van 0.
locked = true: De processor is vergrendeld aan de index en kan niet via de admin UI worden verwijderd.
hidden = true: De processor is verborgen voor de admin UI.

Deze annotatie is essentieel omdat het definieert hoe Drupal de volgende klasse moet behandelen. Het specificeert alles, van de ID en het label van de plugin tot meer genuanceerd gedrag zoals de fasen waarin deze deelneemt en of deze vergrendeld of verborgen is in de UI.

Methoden Uitgelegd

Na het definiëren van de plugin-annotatie, ligt de kern van je plugin in de methoden die je implementeert. Hier zijn de essentiële methoden die je doorgaans nodig hebt in een Search API Processor Plugin en wat elke methode doet:

getPropertyDefinitions(DatasourceInterface $datasource = NULL)

Deze methode is verantwoordelijk voor het definiëren van nieuwe eigenschappen die de plugin zal toevoegen of manipuleren. Het wordt aangeroepen tijdens de “add_properties” fase zoals gespecificeerd in onze plugin-annotatie. Als je plugin nieuwe velden voor de zoekindex moet aanmaken, definieer je ze hier.

preprocessIndexItems(PreprocessIndexItemsEvent $event)

Deze methode wordt aangeroepen voor het vullen van de waarden van de velden die je hebt gedefinieerd in getPropertyDefinitions(). Als je bestaande velden manipuleert of nieuwe toevoegt, specificeer je hier de logica. Het ontvangt een event-object dat alle items bevat die op het punt staan geïndexeerd te worden, waardoor je hun eigenschappen kunt wijzigen voordat ze naar de zoekindex worden gestuurd.

Stap 3: De Plugin Inschakelen en Cache Wissen

Nadat je de code voor je aangepaste Search API Processor Plugin hebt geschreven, moet je ervoor zorgen dat deze wordt herkend door Drupal en de Search API.

Als de module nog niet is ingeschakeld

Als je aangepaste module nog niet is ingeschakeld, ga dan naar de Extensiepagina (/admin/modules) in je Drupal admin-interface, zoek je aangepaste module en schakel deze in.

Als de module al is ingeschakeld

Als je aangepaste module die de plugin bevat al is ingeschakeld, zal Drupal de nieuwe plugin niet automatisch detecteren. Je moet de cache wissen zodat de wijzigingen van kracht worden. Je kunt de cache wissen via de admin-interface door naar Configuratie > Ontwikkeling > Prestaties te gaan (/admin / config / development / performance) en op “Alle caches wissen” te klikken.

Je kunt de cache ook wissen met Drush met het volgende commando:

drush cr

Stap 4: De Search API Index Configureren

Nadat je de module hebt ingeschakeld en de cache hebt gewist, ga je naar de veldinstellingen van je Search API index door naar /admin/config/search/search-api/index/your-index/fields te gaan.

Klik op de knop “Velden toevoegen”, die meestal bovenaan de pagina staat. Deze actie toont een lijst met beschikbare velden.
In deze lijst zou je je nieuw toegevoegde aangepaste veld met het label Volledige Club Naam moeten vinden.
Selecteer dit veld en klik vervolgens op de knop “Toevoegen” naast de veldnaam om het aan je index toe te voegen.
Klik op Gereed.
Indexeer ten slotte je content opnieuw om ervoor te zorgen dat het nieuwe aangepaste veld wordt gevuld en doorzoekbaar wordt.

Aangepaste velden toegevoegd aan de index

Het Aangepaste Veld Gebruiken in Views en Zoeken

Nadat je je aangepaste module hebt ingeschakeld en de cache hebt gewist, zou je aangepaste Search API Processor Plugin geactiveerd moeten zijn. Wat dit voor jou betekent:

Beschikbaarheid van Index View Veld

Je nieuwe aangepaste veld Volledige Club Naam zal beschikbaar zijn in de lijst met velden wanneer je een index view in Drupal maakt of bewerkt. Dit geeft je de mogelijkheid om deze geaggregeerde gegevens op te nemen als onderdeel van je zoekresultaten of view-lijsten.

Volledige Tekst Zoekfilters

Als je het aangepaste veld hebt gedefinieerd als een ‘Volledige Tekst’ type in je Search API-instellingen, kun je dit veld ook gebruiken als filtercriterium binnen de index view. Dit stelt gebruikers in staat om volledige tekst zoekopdrachten uit te voeren specifiek op dit gecombineerde veld, wat mogelijk de nauwkeurigheid en relevantie van zoekresultaten verbetert.

Conclusie

Deze gids heeft je door het proces geleid van het maken van een aangepaste Search API Processor Plugin in Drupal 8, 9 en 10. De plugin, genaamd FullClubName, combineert de velden title en field_cl_district_name van het Club content type tot één doorzoekbaar veld. Dit verbetert je zoekmogelijkheden en is een perfect voorbeeld van hoe flexibel en uitbreidbaar Drupal kan zijn.

Veel succes met debuggen!

Solr

Hoe maak je een Solr-compatibele Search API Processor Plugin in Drupal 10