Tokens Personalizados
Permite a los administradores del sitio crear tokens personalizados con contenido definido por el usuario que se pueden utilizar en todo el sitio Drupal a través de la Token API.
token_custom
Instalar
composer require 'drupal/token_custom:8.x-1.0'
Overview
El módulo Custom Tokens proporciona una interfaz administrativa completa para crear y gestionar tokens personalizados dentro de Drupal. Los tokens son marcadores de posición reutilizables que se reemplazan con contenido dinámico cuando se procesan, y este módulo extiende la Token API permitiendo a los usuarios definir sus propios tokens personalizados sin escribir código.
Los tokens personalizados se organizan en tipos (categorías), lo que permite agrupar lógicamente los tokens relacionados. Cada token contiene contenido de texto formateado que admite cualquier formato de texto disponible en el sitio, incluyendo HTML filtrado. El módulo es totalmente compatible con la traducción, permitiendo que los nombres, descripciones y contenidos de los tokens se traduzcan a múltiples idiomas.
Cuando se utiliza un token personalizado en contenido o campos de configuración que admiten el reemplazo de tokens, el módulo sustituye automáticamente el marcador de posición del token por su contenido definido. Esto lo hace ideal para gestionar fragmentos de texto reutilizables, información de contacto, avisos legales o cualquier otro contenido que necesite aparecer de manera consistente en múltiples ubicaciones.
Features
- Crear tipos de tokens personalizados (categorías) para organizar los tokens de forma lógica
- Definir tokens personalizados con machine names para usar en campos habilitados para tokens
- Soporte para contenido de texto formateado utilizando cualquier formato de texto disponible (Plain text, Basic HTML, Full HTML, etc.)
- Soporte completo de traducción para descripciones y contenido de tokens a través del sistema de traducción de Drupal
- Integración automática con la Token API de Drupal mediante hook_token_info() y hook_tokens()
- Implementación consciente de la caché con invalidación automática cuando se crean, actualizan o eliminan tokens
- Control de acceso basado en permisos para ver, crear, editar y eliminar tokens y tipos de tokens
- Páginas de listado administrativo con operaciones para gestionar tokens y tipos
- Protección contra la eliminación de tipos de tokens que están siendo utilizados por tokens existentes
Use Cases
Información de Contacto Reutilizable
Crea tokens para los detalles de contacto de la empresa como dirección, número de teléfono y correo electrónico. Usa tokens como [custom:company-address] y [custom:support-email] en todo el sitio. Cuando la información de contacto cambie, actualiza el token en un solo lugar y se actualizará automáticamente en todas partes.
Avisos Legales y Texto Estándar
Almacena avisos legales, notas de copyright o fragmentos de términos de servicio como tokens. Inserta [custom:copyright-notice] o [custom:privacy-disclaimer] en tipos de contenido, bloques o plantillas de correo electrónico para asegurar texto legal consistente en todo el sitio.
Fragmentos de Contenido Dinámico
Crea tokens para contenido que cambia frecuentemente como mensajes promocionales, saludos estacionales o códigos de campaña. Los editores de contenido pueden actualizar el contenido del token [custom:promo-message] sin tocar las páginas donde aparece.
Tokens de Contenido Multilingüe
En sitios multilingües, crea tokens con contenido traducido para cada idioma. El módulo sirve automáticamente la traducción correcta basándose en el contexto del idioma actual, asegurando que [custom:welcome-message] se muestre apropiadamente en inglés, español, francés, etc.
Categorías de Tokens Organizadas
Crea tipos de tokens personalizados para organizar los tokens por propósito: 'company' para información empresarial ([company:address], [company:hours]), 'legal' para texto legal ([legal:terms], [legal:privacy]), 'promo' para marketing ([promo:current-offer]). Esto mejora la descubribilidad en los navegadores de tokens.
Variables de Plantillas de Correo Electrónico
Usa tokens personalizados en plantillas de correo electrónico configuradas con módulos como Webform o Commerce. Tokens como [custom:email-footer] o [custom:support-hours] pueden usarse consistentemente en todas las comunicaciones por correo electrónico y actualizarse de forma centralizada.
Tips
- Usa machine names descriptivos para los tokens que indiquen su propósito, como 'company-phone' en lugar de 'phone1'
- Crea múltiples tipos de tokens para organizar los tokens de forma lógica - por ejemplo, tipos separados para contenido de 'contact', 'legal' y 'marketing'
- Recuerda que el contenido de los tokens admite formatos de texto, por lo que puedes incluir HTML formateado, enlaces y otro contenido enriquecido
- El módulo Token proporciona un navegador de tokens que muestra todos los tokens personalizados disponibles - accede a él a través de campos que admiten tokens
- Al actualizar el contenido de un token, los cambios tienen efecto inmediatamente después de limpiar la caché - no es necesario volver a guardar el contenido que usa ese token
- Los tokens personalizados funcionan en cualquier lugar donde el módulo Token esté integrado, incluyendo patrones de Pathauto, valores de Metatag, correos electrónicos de Webform y más
- Para sitios multilingües, traduce el contenido de los tokens a través del flujo de trabajo de traducción estándar para mantener mensajes consistentes entre idiomas
Technical Details
Admin Pages 8
/admin/structure/token-custom
Lista todos los tokens personalizados definidos en el sitio. Desde esta página puedes ver, editar y eliminar tokens existentes, así como añadir nuevos tokens. El listado muestra el machine name, tipo, nombre, descripción y contenido sin formato de cada token.
/admin/structure/token-custom/add
Crear un nuevo token personalizado. Si existen múltiples tipos de tokens, primero seleccionarás a qué tipo debe pertenecer el token. El token puede usarse en cualquier campo habilitado para tokens usando el formato [type:machine-name].
/admin/structure/token-custom/manage/{token_custom}/edit
Editar un token personalizado existente. El machine name no puede cambiarse después de la creación para evitar romper referencias de tokens existentes.
/admin/structure/token-custom/manage/{token_custom}/delete
Página de confirmación para eliminar un token personalizado. Eliminar un token hará que cualquier contenido que use ese token muestre el marcador de posición del token sin procesar en lugar del contenido de reemplazo.
/admin/structure/token-custom/type
Lista todos los tipos de tokens personalizados (categorías) definidos en el sitio. Los tipos de tokens proporcionan espacios de nombres para organizar los tokens. Un tipo 'Custom' predeterminado se instala con el módulo.
/admin/structure/token-custom/type/add
Crear un nuevo tipo de token para organizar los tokens personalizados. El machine name se convierte en el prefijo del espacio de nombres del token, por ejemplo, crear un tipo con machine name 'company' permite tokens como [company:address].
/admin/structure/token-custom/type/manage/{token_custom_type}/edit
Editar el nombre y la descripción de un tipo de token existente. El machine name no puede cambiarse después de la creación.
/admin/structure/token-custom/type/manage/{token_custom_type}/delete
Página de confirmación para eliminar un tipo de token. Los tipos que tienen tokens asignados no pueden eliminarse - primero debes eliminar o reasignar todos los tokens que usan ese tipo.
Permisos 3
Hooks 2
hook_token_info
Registra los tipos de tokens personalizados y tokens con la Token API. Este hook se implementa para exponer todas las entidades TokenCustomType como tipos de tokens y todas las entidades TokenCustom como tokens disponibles dentro de sus respectivos tipos.
hook_tokens
Proporciona los valores de reemplazo reales para los tokens personalizados. Cuando se está reemplazando un token, este hook carga la entidad TokenCustom correspondiente y devuelve su contenido formateado. Maneja la traducción y añade los metadatos de caché apropiados.
Troubleshooting 5
Limpia todas las cachés usando drush cr o Administración > Configuración > Rendimiento > Limpiar todas las cachés. Verifica que el machine name del token coincida exactamente (distingue mayúsculas y minúsculas). Asegúrate de que el campo o contexto admita el reemplazo de tokens.
Los tipos de tokens no pueden eliminarse si algún token pertenece a ese tipo. Primero elimina todos los tokens que usan ese tipo, o edita los tokens para asignarlos a un tipo diferente, luego elimina el tipo.
Limpia la caché del sitio y la caché estática de tokens. El módulo implementa invalidación de caché pero puede ser necesaria una limpieza manual de caché. Verifica que tanto el tipo de token como el token estén habilitados.
Asegúrate de que el contenido del token tenga el formato de texto correcto seleccionado. Si el token se creó con formato 'Plain text', el HTML se escapará. Edita el token y selecciona un formato apropiado como 'Basic HTML' o 'Full HTML'.
Debe existir al menos un tipo de token para crear tokens. Si se eliminó el tipo 'Custom' predeterminado, crea primero un nuevo tipo de token en Administración > Estructura > Custom tokens > Custom Token Types > Añadir Tipo de Token.
Security Notes 4
- El permiso 'administer custom tokens' está marcado como restringido porque los tokens pueden contener contenido HTML que se renderiza en el sitio. Solo otorga este permiso a roles de confianza.
- El contenido de los tokens respeta los permisos de formato de texto. Los usuarios que crean tokens solo pueden usar formatos de texto a los que tienen acceso.
- Ten cuidado con qué contenido almacenas en los tokens, ya que los tokens pueden mostrarse a usuarios anónimos dependiendo de dónde se usen.
- El permiso 'administer custom token types' está restringido ya que afecta la organización de todos los tokens personalizados en el sitio.