29 de agosto de 2023

En Drupal, es común integrarse con Solr para obtener una potente funcionalidad de búsqueda. A veces, es posible que necesites combinar información de varios campos para crear un nuevo campo personalizado para la búsqueda de Solr. Esta guía te muestra cómo crear un Plugin Procesador de API de Búsqueda Compatible con Solr en Drupal 10. Esta guía también es compatible con Drupal 8 y 9.

Prerrequisitos

Una instalación funcional de Drupal 8, 9 o 10
Motor de búsqueda Solr integrado con Drupal
Un tipo de contenido personalizado llamado Club con un campo personalizado field_cl_district_name. (Nota: El campo title es una propiedad predeterminada para cualquier tipo de contenido de Drupal. Para el propósito de este artículo, se agrega un campo personalizado para el nombre del distrito al tipo de contenido. Debes crear o usar un tipo de contenido real relevante para tu proyecto).
El módulo Search API de Drupal instalado y habilitado
El módulo Search API Solr instalado y habilitado
Módulo personalizado llamado my_custom_module (puedes nombrarlo como desees)

Compatibilidad con Solr

Esta guía está diseñada para ser compatible con Solr, uno de los backends de búsqueda más populares utilizados con Drupal. El Plugin Procesador de API de Búsqueda personalizado que crearás se puede configurar para que funcione sin problemas con Solr, mejorando las capacidades de búsqueda de tu sitio.

Creación del Plugin Procesador de API de Búsqueda

Paso 1: Prepara tu Módulo Personalizado

Si aún no has creado un módulo personalizado, primero debes configurarlo. Crea una carpeta en modules/custom llamada my_custom_module. Dentro de ella, necesitarás un archivo my_custom_module.info.yml con el siguiente contenido:

name: 'Mi Módulo Personalizado'
type: module
description: 'Un módulo personalizado para extender las funcionalidades de Drupal.'
core_version_requirement: ^8 || ^9 || ^10
package: Custom

Paso 2: Crea la Clase del Plugin

Crea un archivo PHP llamado FullClubName.php dentro de modules / custom / my_custom_module / src / Plugin / search_api / processor.

Así es como se vería el archivo 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("Nombre Completo del Club"),
 *   description = @Translation("Combina los campos Título y Distrito para los clubes."),
 *   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('Nombre Completo del Club'),
        'description' => $this->t('Combina los campos Título y Distrito para los clubes.'),
        '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);
      }
    }
  }
}

Anotación Explicada

@SearchApiProcessor: Esta anotación declara la clase como un Plugin Procesador de API de Búsqueda.
id = "full_club_name": El nombre interno de la máquina para el plugin, que debe ser único.
label = @Translation("Nombre Completo del Club"): La etiqueta legible por humanos para el plugin, que se puede traducir.
description = @Translation("Combina los campos Título y Distrito para los clubes."): Proporciona más información sobre lo que hace este plugin procesador.
stages = { "add_properties" = 0 }: Especifica que este plugin opera en la etapa “add_properties” con un peso de 0.
locked = true: El procesador está bloqueado en el índice y no se puede eliminar a través de la interfaz de administración.
hidden = true: El procesador está oculto en la interfaz de administración.

Esta anotación es esencial ya que define cómo Drupal debe tratar la clase que sigue. Especifica todo, desde el ID y la etiqueta del plugin hasta un comportamiento más matizado, como las etapas en las que participa y si está bloqueado u oculto en la interfaz de usuario.

Métodos Explicados

Después de definir la anotación del plugin, el núcleo de tu plugin reside en los métodos que implementas. Aquí están los métodos esenciales que típicamente necesitarás en un Plugin Procesador de API de Búsqueda y lo que hace cada uno:

getPropertyDefinitions(DatasourceInterface $datasource = NULL)

Este método es responsable de definir nuevas propiedades que el plugin agregará o manipulará. Se invoca durante la etapa “add_properties” como se especifica en la anotación de nuestro plugin. Si tu plugin necesita crear nuevos campos para el índice de búsqueda, aquí es donde los defines.

addFieldValues(ItemInterface $item)

Este método se invoca para poblar los valores de los campos que has definido en getPropertyDefinitions(). Si estás manipulando campos existentes o agregando nuevos, especificas la lógica aquí. Recibe un objeto de elemento que contiene todos los elementos a punto de ser indexados, lo que te permite cambiar sus propiedades antes de que se envíen al índice de búsqueda.

Paso 3: Habilitar el Plugin y Limpiar la Caché

Después de escribir el código para tu Plugin Procesador de API de Búsqueda personalizado, debes asegurarte de que sea reconocido por Drupal y la API de Búsqueda.

Si el módulo aún no está habilitado

Si tu módulo personalizado aún no está habilitado, navega a la página Extend (/admin/modules) en tu interfaz de administración de Drupal, busca tu módulo personalizado y habilítalo.

Si el módulo ya está habilitado

Si tu módulo personalizado que contiene el plugin ya está habilitado, Drupal no detectará automáticamente el nuevo plugin. Necesitarás limpiar la caché para que los cambios surtan efecto. Puedes limpiar la caché a través de la interfaz de administración navegando a Configuración > Desarrollo > Rendimiento (/admin / config / development / performance) y haciendo clic en “Limpiar todas las cachés”.

Alternativamente, puedes limpiar la caché usando Drush con el siguiente comando:

drush cr

Paso 4: Configura el Índice de la API de Búsqueda

Después de habilitar el módulo y limpiar la caché, navega a la configuración de campos de tu índice de la API de Búsqueda yendo a /admin/config/search/search-api/index/your-index/fields.

Haz clic en el botón “Añadir campos”, que generalmente se encuentra en la parte superior de la página. Esta acción mostrará una lista de campos disponibles.
En esta lista, deberías encontrar tu campo personalizado recién agregado etiquetado como Nombre Completo del Club.
Selecciona este campo y luego haz clic en el botón “Añadir” junto al nombre del campo para incluirlo en tu índice.
Haz clic en Hecho.
Finalmente, vuelve a indexar tu contenido para asegurarte de que el nuevo campo personalizado se rellene y esté disponible para la búsqueda.

Campos personalizados añadidos al índice

Utilización del Campo Personalizado en Vistas y Búsqueda

Una vez que hayas habilitado tu módulo personalizado y limpiado la caché, tu Plugin Procesador de API de Búsqueda personalizado debería estar activado. Lo que esto significa para ti:

Disponibilidad de Campos en Vistas de Índice

Tu nuevo campo personalizado Nombre Completo del Club estará disponible en la lista de campos cuando estés creando o editando una vista de índice en Drupal. Esto te da la capacidad de incluir estos datos agregados como parte de tus resultados de búsqueda o listados de vistas.

Filtros de Búsqueda de Texto Completo

Si has definido el campo personalizado como un tipo de ‘Texto Completo’ en la configuración de tu API de Búsqueda, también puedes usar este campo como criterio de filtro dentro de la vista de índice. Esto permite a los usuarios realizar consultas de búsqueda de texto completo específicamente en este campo combinado, mejorando potencialmente la precisión y relevancia de los resultados de búsqueda.

Conclusión

Esta guía te ha guiado a través del proceso de creación de un Plugin Procesador de API de Búsqueda personalizado en Drupal 8, 9 y 10. El plugin, llamado FullClubName, combina los campos title y field_cl_district_name del tipo de contenido Club en un único campo buscable. Esto mejora tus capacidades de búsqueda y es un ejemplo perfecto de cuán flexible y extensible puede ser Drupal.

¡Feliz Depuración!

Solr

Cómo Crear un Plugin Procesador de API de Búsqueda Compatible con Solr en Drupal 10