Entity API en Drupal 8 y 9

Introducción

Drupal se ha caracterizado desde sus primeras versiones en la implementación de estructuras de almacenamiento de información complejas, que permite extender funcionalidades a través de los módulos Contrib y Custom, en la versión 7 se implementó un esquema de almacenamiento basado en entidades básicas, las cuales se construyeron para el manejo de tipos de contenido, Usuarios, Taxonomías y comentarios.

¿Qué es una entidad?

Una entidad en Drupal es una estructura para almacenar información.

El concepto de Entidades nació en Drupal 7, en donde se incluyó una Entity API en el Core de Drupal, esta se encargaba de manejar propiamente las entidades del Core, Nodos, Usuarios, Comentarios y Taxonomías, en esta versión de Drupal, ya se comenzaba a organizar la información en estas entidades que dieron pie a la creación de múltiples módulos Contrib, para la expansión de la funcionalidad nativa de Drupal.

En Drupal 8 se implementó oficialmente el concepto de Entidades, en donde toda la información se almacena en una entidad, ya sea una entidad de configuración o en una entidad de contenido, con esta implementación se pueden crear nuevas entidades para almacenar información, para no depender del sistema de almacenamiento de tipos de contenido como lo son los nodos.

Tipos de entidades

En Drupal 8 existen dos tipos de entidades, entidades que se usan para todo el almacenamiento de la información, una entidad es la conocida como Config entities (Entidades de configuración), las cuales son las encargadas de almacenar la información de valores de configuración de cada módulo que lo requiera, esta información generalmente es exportada a archivos YML, los cuales son útiles para poder compartirlas entre diferentes ambientes.

El otro tipo de entidad son Content entities (Entidades de contenido), este tipo de entidad permite la creación de campos, son las utilizadas para almacenar información como lo son Noticias, Eventos, Comentarios, etc.

Aquí se presenta una comparación entre los dos tipos de entidades.

Bundles

Los Bundles se considera como una subclasificación de la entidad, los campos que se crean a la entidad, se relacionan directamente con los Bundles. Por ejemplo, en un Tipo de contenido se pueden tener campos que pertenecen al bundle “Articles”, que a su vez pueden ser usados en el bundle “News”, internamente en la base de datos, en la tabla de almacenamiento del campo, se tendrá una columna que identifica el bundle, al que hace parte dicha información.

Campos

Los campos son para guardar información adicional a las entidades. Cada campo tiene una configuración base y una configuración de instancia. Esta última nos permite reutilizar campos en distintos bundles sin importar la entidad, pero compartiendo la configuración base. Por ejemplo, el campo País se puede compartir entre diferentes entidades, ejemplo la entidad Cliente, Proveedor, Usuario, las 3 pueden tener un campo de País, que es único en el sistema, que a través del Bundle se puede diferenciar, de esta forma se reutilizan campos.

Ejemplo de creación de una entidad

En este caso, iniciaremos creando un módulo custom llamado Ejemplo, utilizaremos Drupal console para la creación de la estructura base.

Ubicados en la raíz del proyecto Drupal, ejecutamos el siguiente comando de Drupal console

drupal generate:module

Nos solicitará el nombre del módulo, en este caso le asignaremos Ejemplo

Luego nos pedirá que ingresemos el nombre de máquina, por defecto nos dejara el mismo nombre que le acabamos de asignar al módulo, podemos dejarlo igual o asignarle otro.

Nos pedirá la ruta en donde va a crear el nuevo módulo, por defecto va a sugerir la ruta de la carpeta para los módulos, en este caso nos sugiere la ruta de los módulos custom, se recomienda dejar esta ruta, para organización del proyecto.

Nos pedirá que le asignemos una descripción al módulo, esta será la que se visualizara en el módulo en la sección de Extends de Drupal en el listado de módulos.

Seguido a este proceso nos pedirá el nombre del package al que pertenecerá el módulo, en este caso lo dejaremos en Custom.

Continuando con el proceso, nos pedirá la versión del módulo, lo dejamos en el valor recomendado en este caso 8.x

Nos pregunta si deseamos incluir el archivo .module, este archivo es de propósito general para el módulo, se utilizará para la inclusión de los hook que sean necesarios, le dejamos el valor predeterminado yes.

A continuación, viene una serie de opciones de creación del módulo que si se desea se puede incluir o no, en este caso de ejemplo quedarían de la siguiente forma.

Por último se procede a la generación del módulo respondiendo yes a la siguiente pregunta.

Con esto se ha terminado la generación de un nuevo módulo en su parte más básica, indicando los archivos generados

Procedemos a instalar el módulo normalmente como cualquier otro módulo, para tenerlo disponible para la creación de nuestra entidad.

Listo, ya tenemos nuestro módulo base, ahora sobre ese módulo, vamos a crear la entidad, en este caso, vamos a crear una entidad llamada Cliente, esta entidad será una entidad de contenido, igualmente vamos a usar drupal console para la creación de esta entidad. El comando a utilizar es el siguiente:

drupal generate:entity:content

Lo primero que nos pregunta es el nombre del modulo en el cual vamos a generar la nueva entidad, en este caso vamos a indicar que la vamos a querer en el nuevo módulo Ejemplo, que ya tenemos instalado, aquí indicamos el nombre de máquina del módulo es decir: ejemplo.

A continuación, nos pide el nombre de la clase principal de la entidad, le indicamos que la clase se llamara ClienteEntity.

Posterior a esto nos solicitará indicarle algunas características de la entidad, por ejemplo, si es Traducible, o si va a tener la opción de revisiones del contenido. Las cuales se evidencian a continuación.

Con esto se finaliza el proceso de creación de una entidad en su versión básica, todos los archivos mínimos y necesarias para el manejo y configuración de la entidad ya están en la carpeta del módulo.

Si nos dirigimos a la interfaz de Drupal, vamos a encontrar en la sesión de structure dos links a funcionalidades de la entidad Cliente, un acceso a la Configuración de la Entidad, como por ejemplo la creación de campos personalizados, igual que un tipo de contenido, al usar el módulo Entity API, su funcionamiento es idéntico a como lo hacen las entidades oficiales del core de Drupal

Y la otra funcionalidad es el listado del contenido en si de la entidad, los registros que se almacenan a través del formulario de creación de registros, igualmente como lo hace Drupal con El Add Content, es un formulario que permite el ingreso de los datos en los campos configurados para dicha entidad.

Entity API - Archivos que lo componen

Ya teniendo nuestra entidad creada, vamos a explicar cada una de las partes que la conforman.

Permisos

Se genera un archivo para la definición de los permisos que se tendran a disposición para cada una de las funcionalidades de la entidad, estos permisos se asignan en un archivo yml, el cual el nombre esta compuesto por el nombre del mudulo y la palabra permissions con extension yml, en este caso seria ejemplo.permissions.yml.

Links task

Los links task, se utilizan como enlaces auxiliares que permiten dar acceso a funcionalidades de la entidad, para este caso se crean estos links, para proporcionar opciones a los registros existentes de la entidad, dando la posibilidad de borrar, editar, ver el registro, o sus correspondientes revisiones. estos links se crean en un archivo llamado ejemplo.links.task.yml

Links Action

Esta funcionalidad es un disparador de una funcionalidad, la cual se encuentra inmersa dentro de una interfaz, para el caso de la entidad, esta incluida en el listado de registros, en donde a través de un boton permite el llamado a un formulario, el cual servira para la creación de un nuevo registro. su construcción se realiza en un archivo yml, el cual lleva por nombre ejemplo.links.action.yml.

Links Menu

Para dar acceso a las dos funcionalidades importantes de la entidad, en este caso la configuración y la administración de registros de la entidad, se tiene a disposición un archivo donde se definen los enlaces de menú que serán utilizados, se definen dentro de un archivo que lleva por nombre ejemplo.links.menu.yml, en este archivo es donde se deberán incluir cada uno de los enlaces que se deseen visualizar desde el menú administrativo de drupal.

Entidad

El archivo que define la clase de la entidad se llama en nuestro ejemplo ClienteEntity.php, se encuentra ubicado dentro del módulo en la carpeta src/Entity, y es el archivo principal de la entidad, aquí se define como va a funcionar la entidad, que manejadores, formularios, rutas y configuraciones se van a tener disponibles.

Anotaciones

Las anotaciones son un sistema que ya viene integrado con el núcleo de Drupal, estas tienen una apariencia de comentarios de docblock en el código fuente, sin embargo su sintaxis es analizada sintácticamente en tiempo de ejecución por el motor de anotaciones de drupal, este motor es proporcionado por Doctrine el cual toma estas anotaciones y las convierte en un Objeto PHP y luego son almacenados en la cache.

La sintaxis de la anotación está rodeada por @ClassName (), se compone predominantemente de pares clave / valor y puede contener matrices que usan llaves. Las claves de nivel superior no deben estar entre comillas, mientras que las claves de matriz deben hacerlo. Cada par clave / valor debe estar en su propia línea, y esa línea debe terminar con una coma. Ciertas funciones se pueden ejecutar en valores, en particular la función @Translation().

Los manejadores que se tendrán a disposición se incluye en esta anotación, cada uno en una línea independiente conservando el estándar clave / valor.

Las tablas en donde se almacenará la información de la entidad también se definen aquí, igualmente el concepto de revisión y el manejo de traducciones de los registros de la entidad, tal y como se puede ver en la siguiente imagen:

De igual forma se incluyen los links que se tendrán a disposición en la entidad, esta configuración es la utilizada en los archivos de links.task.yml, links.menu, links.action.yml

Metodo baseFieldDefinitions

Este método permite la creación de los campos de la entidad, al crear la entidad de manera automática se tienen a disposición los siguientes campos

• user_id : usuario creador del registro en la entidad
• name : Nombre del registro con el que se va a relacionar la entidad
• status : Estado del registro, puede ser Publicado o no
• created: Fecha de creación del registro
• changed : Fecha de actualización del registro

Estos campos son los básicos y mínimos que debe tener una entidad. de ahí en adelante se puede extender a los campos que se requieran. Su creación es muy sencilla y se realiza de la misma forma que Drupal permite la creación de campos para sus entidades internas.

Drupal se basa en el uso del estándar de programación proporcionado por Symfony, el cual a su vez mantiene y promueve el uso de Programación Orientada a Objetos, en donde el uso de interfaces es fundamental a la hora de la construcción de código fuente, y en este caso para la construcción de las entidades no es la excepción, así que la clase principal de la entidad realiza una implementación de una interfaz, en donde se definen los métodos mínimos que tendrá que utilizar la entidad,

y la interfaz contiene los siguientes métodos a implementar.

• getName();
• setName($name);
• getCreatedTime();
• setCreatedTime($timestamp);
• getRevisionCreationTime();
• setRevisionCreationTime($timestamp);
• getRevisionUser();
• setRevisionUserId($uid);

Listado de Registros

El listado de registros es la funcionalidad que proporciona la entidad para poder visualizar, y administrar los registros creados en la entidad, dando la opción de Editar, Eliminar, Ver y también acceder a las revisiones de cada uno de los registros, de igual forma, desde esta interfaz de listado se puede acceder al formulario de creación de nuevos registros de la entidad, esta funcionalidad esta soportada en el archivo entityListBuilder.php, con el prefijo de la entidad para nuestro ejemplo en curso seria cliente, entonces el nombre oficial del archivo seria ClienteEntityListBuilder.php.

En este archivo se construye una clase, la cual es la encargada de generar la tabla de listado de registros. y se compone de dos métodos únicamente, el generador del Header y el generador de los Rows o filas.

En caso que la entidad tenga muchos más campos, se pueden incluir en este listado, incluyendo en el método buildHeader la cantidad de columnas que se necesiten y posteriormente en el método buildRow, siempre deben estar en parejas esta definición de campos.

Con esto ya tenemos una entidad creada y funcional, lista para comenzar a utilizar, se puede extender en la cantidad de campos que sean necesarios, utilizando el API de Formularios para la creación de campos, de la misma forma que se usa para los campos en los tipos de contenido.

Conclusión

Usar entidades en Drupal es muy sencillo, y más aun utilizando herramientas de generación de código como lo es Drupal console, aunque el código generado dentro del módulo puede llegar a ser bastante, su uso es muy intuitivo, y la capacidad de extender su funcionalidad se puede dar a través de código, o por la interfaz administrativa, aunque en Drupal se puede modelar cualquier proyecto basado en tipos de contenido, generar relaciones y extender en campos la funcionalidad de los tipos de contenido, siempre se tendrá la incertidumbre de almacenar toda la información en las tablas de node.

Las entidades permiten emplear todo lo mejor del mundo de los nodos y almacenarlo en tablas independientes, para control de la información, y también del mismo proyecto.