Sinónimos 8.x

En este artículo quiero presentar la versión 8.x del módulo Synonyms (https://www.drupal.org/project/synonyms). En términos generales dicho módulo tiene las siguientes funciones:

• Guarda los sinónimos de entidades dentro de sus campos (Fields y Base Fields)
• Provee los controles select con sinónimos y autocompletar con sinónimos para los campos de referencia a entidad
• Provee de filtros y argumentos con sinónimos en las vistas (views)

Entonces se introduce el concepto de los sinónimos de entidad. Un sinónimo es simplemente una frase (cadena de caracteres) que se supone tiene un significado sinonímico al nombre de la entidad a la cual pertenece. Por ejemplo, si tenemos países como términos de taxonomía, podría haber el término México con un sinónimo Méjico.

Para empezar, veámos en detalle cómo se puede aprovechar el concepto de sinónimo y luego analizaremos cómo realmente se guardan los sinónimos de las entidades en la base de datos.

Primeramente hay que aclarar que existe la idea de comportamientos (behaviors). Comportamiento es una atómica función que toma sinónimos de tus entidades y puede hacer algo productivo con ellos. El módulo tiene 2 comportamientos: select con sinónimos y autocompletar con sinónimos.

Select con sinónimos

Como bien dice su nombre, ese comportamiento crea un control para los campos de referencia a entidad de lista desplegable. Esta lista va a tener no solo los nombres de las entidades que pueden ser referidas sino también sus sinónimos. En conjunto con jQuery.Chosen (https://www.drupal.org/project/chosen) se produce una herramienta poderosa.

Cabe señalar que los usuarios avanzados también pueden utilizar ese select con sinónimos dentro de sus formas:

<?php

$form[‘synonyms_select’] = array(

  ‘#type’ => ‘synonyms_entity_select’,

  ‘#key_column’ => ‘target_id’,

  ‘#target_type’ => ‘user’, // Tipo de entidad que generar.

  ‘#handler’ => ‘default’, // Tipo de EntityReferenceSelection Plugin que utilizar.

  ‘#handler_settings’ => array(), // Configuración de EntityReferenceSelection Plugin.

  ‘#multiple’ => FALSE, // Si hacer el select multiple.

  ‘#default_value’ => array(1), // Lista de IDs de las entidades que deben de ser eligidas por default.

);

?>

 Autocompletar con sinónimos

De manera parecida, ese comportamiento crea un control para los campos de referencia a entidad de autocompletar, pero las sugerencias vienen no solo basadas en los nombres de las entidades sino también en sus sinónimos.

Ese control tiene algunas configuraciones:

• Cuántas sugerencias producir como máximo. Por defecto no se hacen más que 10 sugerencias, lo cual es bastante razonable. Pero siempre se puede ajustar.
• Si se debe sugerir la misma entidad únicamente a través de una sola sugerencia: a veces la misma entidad puede ser sugerida por su nombre y por alguno de sus sinónimos a la vez. Si activas esta opción será sugerida solo una vez, ya sea por su nombre o por alguno de sus sinónimos.
• Tipo de búsqueda que realizar: sugerir solo los nombres o sinónimos que empiezan con la palabra clave o los que contienen la palabra clave.

De igual forma, como en el caso de select con sinónimos, los Drupaleros avanzados pueden utilizar ese control directamente en sus formas:

<?php

$form[‘synonyms_autocomplete’] = array(

   '#type' => 'synonyms_entity_autocomplete',

   '#target_type' => ‘user’, // Tipo de entidad que sugerir.

   '#target_bundles' => array(‘user’), // Vector de bundles que sugerir o NULL para segerir todas las bundles dentro del tipo de entidad especificado.

   '#suggestion_size' => 10, // Cuántas sugerencias producir como el máximo.

   '#suggest_only_unique' => FALSE, // Si una entidad solo se puede sugerir a través de una sola sugerencia.

   '#match' => ‘CONTAINS’, // Cómo ejecutar la búsqueda. Puede ser CONTAINS o STARTS_WITH.

   '#default_value' => array(User::load(1)), // Vector de entidades que tienen que estar pre-elegidas dentro del campo de autcompletar.

);

?>

Filtros y argumentos de las vistas

Se puede crear un filtro de vistas para entidades y tomará forma de los consabidos controles (select con sinónimos o autocompletar con sinónimos). Lo más probable es que vayas a requerirlo como un filtro expuesto para que así los usuarios de tu vista puedan filtrar (y encontrar entidades a base de cuales hacer el filtro) más fácil.

También existe la opción para especificar el criterio sinónimo o el nombre de la entidad en un argumento de la vista. Eso puede ser de gran utilidad para generar URLs más amigables de tus vistas. Por ejemplo, si tenemos nuestros términos de taxonomía (países), y tenemos allí México con el sinónimo MX. El URL de tu vista puede ir desde http://example.com/mi-vista/mexico a http://example.com/mi-vista/mx (y de forma parecida para todos los países restantes).

Usos más avanzados

Para los más atrevidos también existen pequeñas sorpresas. El módulo provee un par de servicios (Services) que pueden ser muy útiles dentro de tus módulos. Esos servicios pueden ayudarte a encontrar una entidad (su ID) por su nombre (o presumiblemente su sinónimo).

Servicio synonyms.synonyms_entity_get

Por la palabra clave te encuentra el ID de la entidad cuyo nombre o uno de sus sinónimos equivale a la palabra clave. Un ejemplo:

<?php

$entity_type = \Drupal::entityTypeManager()->getDefinition('user');

$entity_id = \Drupal::getContainer()->get('synonyms.synonyms_entity_get')->entityGetBySynonym($entity_type, 'palabra-clave');

?>

Si no se encontrara ninguna entidad por la palabra clave proporcionada, tendrás 0 en la respuesta.

Servicio synonyms.synonyms_find

Si tu caso es más complejo y se necesita algo más flexible que una simple búsqueda por la palabra clave, también existe el servicio synonyms.synonyms_find. Ese, aunque implique más trabajo, te da más flexibilidad en la especificación de los criterios de búsqueda. En el ejemplo que sigue se hace una búsqueda dentro de los sinónimos de los usuarios con los siguientes criterios:

• Alguno de los sinónimos tiene que empezar con ‘palabra-clave’
• El ID del usuario no puede ser 1

<?php

$entity_type = \Drupal::entityTypeManager()->getDefinitions('user');

$condition = new \Drupal\Core\Database\Query\Condition();

$condition->condition(\Drupal\synonyms\SynonymsProviderInterface\SynonymsFindProviderInterface::COLUMN_SYNONYM_PLACEHOLDER, 'palabra-clave%', 'LIKE');

$condition->condition(\Drupal\synonyms\SynonymsProviderInterface\SynonymsFindProviderInterface::COLUMN_ENTITY_ID_PLACEHOLDER, 1, '!=');

$found_synonyms = \Drupal::getContainer()->get('synonyms.synonyms_find')->synonymsFind($condition, $entity_type);

?>

En el resultado tendrás un vector con la información sobre todos los usuarios que satisfacen tus criterios de búsqueda (tendrás entity_id y synonym (sinónimo que satifizo el criterio de búsqueda)). Trata de examinar el archivo \Drupal\synonyms\SynonymsService\Behavior\AutocompleteService para ver un buen ejemplo de cómo se usa esa herramienta.

 Proveedores de sinónimos

Aunque los sinónimos son cadenas de caracteres, no significa que siempre están guardados en la base de datos como tales. La arquitectura del módulo permite guardar los sinónimos en cualquier formato (es extensible a través de Plugin API). Lo más probable es que querrás guardar tus sinónimos dentro de los campos (Fields o Base Fields). Para ese caso, el módulo ya brinda soporte para “extraer” sinónimos desde los siguientes tipos de campos:

• Texto
• Referencia a entidad (se utiliza el nombre de la entidad referdia como el sinónimo)
• Número entero (Integer) (puede ser útil para precios u otras cifras descriptivas)
• Coma flotante (Float)
• Decimal
• Email
• Teléfono

Entonces, por un lado, se tienen comportamientos que hacen algo productivo con tus sinónimos y, en el lado opuesto, observamos los proveedores de sinónimos que se hacen cargo de guardar y extraer tus sinónimos. Ahora a los administradores de la página, solo les falta habilitar/deshabilitar ciertos comportamientos sobre ciertos proveedores. Eso puede hacerse en la página de configuración de sinónimos (/admin/structure/synonyms). Por ejemplo, se puede habilitar el comportamiento de select con sinónimos sobre el campo de email en los usuarios y habilitar el campo Nombre completo (digamos que existe uno con ese nombre) para el comportamiento de autocompletaje.