Ejemplos para Desarrolladores
Una colección completa de módulos de ejemplo bien documentados que demuestran las APIs y características principales de Drupal para que los desarrolladores aprendan.
examples
Install
composer require 'drupal/examples:^4.0'
Overview
El proyecto Examples for Developers proporciona un conjunto de módulos de ejemplo funcionales destinados a demostrar las características y APIs de Drupal. Cada submódulo está diseñado para ser simple, bien documentado y fácil de modificar, ayudando a los desarrolladores a comprender rápidamente el funcionamiento interno de Drupal.
El proyecto abarca una amplia gama de funcionalidades del núcleo de Drupal, incluyendo Form API, Field API, Entity API, Render API, Plugin API, Database API (DBTNG), Cache API, Queue API, File API, REST API, Events, Hooks, Theming, integración con JavaScript y más. En lugar de proporcionar soluciones listas para producción, estos módulos sirven como recursos educativos con documentación en línea y comentarios de código extensos.
Cuando está habilitado, el módulo principal agrega un elemento "Examples" en la barra de herramientas que proporciona acceso rápido a todos los submódulos de ejemplo habilitados. Cada módulo de ejemplo típicamente incluye una página de descripción que explica su propósito y enlaces a páginas de demostración.
Features
- 33 submódulos de ejemplo independientes que demuestran las principales APIs de Drupal
- Integración con la barra de herramientas que proporciona navegación rápida a todos los ejemplos habilitados
- Ejemplos completos de Form API incluyendo formularios AJAX, formularios de múltiples pasos y diálogos modales
- Demostración de Field API con tipo de campo personalizado, widgets y formateadores para valores de color RGB
- Ejemplos de creación de Config Entity y Content Entity con operaciones CRUD completas
- Ejemplos de Block plugin incluyendo bloques vacíos, de texto configurable y de transformación a mayúsculas
- Ejemplos de Database API (DBTNG) para consultas, inserciones, actualizaciones y operaciones avanzadas
- Demostración de Cache API mostrando patrones de uso adecuado de caché
- Ejemplos de Queue API y hook Cron con queue workers
- Ejemplos del sistema de Events para despachar y suscribirse a eventos
- Ejemplos de implementación de Hooks incluyendo definición e invocación de hooks personalizados
- Ejemplo de definición de tipo de Plugin personalizado con plugins Sandwich
- Ejemplo de implementación de Stream wrapper para esquemas URI personalizados
- Ejemplos de envío y alteración de correo electrónico usando hook_mail y hook_mail_alter
- Ejemplo de cliente REST para comunicarse con instancias remotas de Drupal
- Ejemplos de Render API demostrando arrays de renderizado y alter hooks
- Ejemplos de Theming con plantillas personalizadas y funciones de preprocesamiento
- Ejemplos de integración con JavaScript con definiciones de bibliotecas y Drupal behaviors
- Ejemplos de Tabledrag y tablesort para interfaces de tablas interactivas
- Ejemplo de Batch API para operaciones de larga duración
- Ejemplo de paginador para visualización de contenido paginado
- Ejemplo de manejo de sesiones demostrando almacenamiento de sesión de usuario
- Ejemplo de plugin Image effect con funcionalidad de colorización
- Ejemplos de permisos de acceso a Node y Field
- Ejemplos del framework de pruebas PHPUnit
Use Cases
Aprendiendo la Form API de Drupal
Los desarrolladores pueden habilitar form_api_example para ver implementaciones funcionales de varios elementos de formulario, formularios AJAX, formularios de múltiples pasos y diálogos modales. Los extensos comentarios en línea explican cada característica de la Form API.
Creando tipos de Field personalizados
El módulo field_example demuestra el proceso completo de creación de un tipo de Field personalizado (color RGB) con múltiples variantes de widget y formatters. Los desarrolladores pueden usar esto como plantilla para sus propias implementaciones de Field.
Implementando Entities personalizadas
Los módulos config_entity_example (Robot) y content_entity_example (Contact) proporcionan ejemplos completos y funcionales de ambos tipos de Entity con formularios, constructores de listas, control de acceso e interfaces administrativas.
Entendiendo el sistema de Plugin
El plugin_type_example demuestra la creación de un tipo de Plugin personalizado (Sandwich) con gestor de Plugin, descubrimiento y anotaciones. Combinado con block_example y field_example, los desarrolladores aprenden el ecosistema completo de Plugin.
Operaciones de base de datos con DBTNG
El módulo dbtng_example muestra el uso correcto de la API de base de datos para operaciones de inserción, actualización, selección y operaciones complejas de join sin escribir consultas SQL directas.
Arquitectura basada en eventos
El events_example demuestra el patrón de despachador de eventos de Symfony en Drupal, mostrando cómo crear, despachar y suscribirse a eventos para una arquitectura de código desacoplada.
Procesamiento de Cron y Queue
El uso combinado de cron_example y queue_example demuestra patrones de procesamiento en segundo plano para tareas de larga duración que no deberían bloquear las solicitudes del usuario.
Stream Wrappers personalizados
El stream_wrapper_example muestra cómo implementar esquemas URI personalizados (session://) para backends alternativos de almacenamiento de archivos.
Integración con REST API
El rest_example proporciona un cliente REST funcional que demuestra cómo comunicarse con instancias remotas de Drupal, útil para implementaciones de Drupal headless.
Entendiendo los Hooks de Drupal
El módulo hooks_example demuestra la implementación de hooks existentes, la definición de hooks personalizados con patrones alter y la invocación de hooks, fundamental para el modelo de extensibilidad de Drupal.
Tips
- Habilite solo los módulos de ejemplo específicos que necesita estudiar en lugar de todos a la vez para reducir la complejidad.
- Lea extensamente los comentarios en línea del código: explican no solo qué hace el código sino por qué se utilizan ciertos patrones.
- Use la documentación de la API en api.drupal.org/api/examples para documentación HTML con referencias cruzadas de todos los ejemplos.
- Experimente modificando el código de ejemplo para entender cómo los cambios afectan el comportamiento: los ejemplos están diseñados para ser fáciles de modificar.
- Consulte los archivos *.api.php en hooks_example y plugin_type_example para documentación sobre la definición de hooks y plugins personalizados.
- Use el módulo testing_example para aprender patrones adecuados de escritura de tests incluyendo unit tests, kernel tests y functional tests.
- El batch_example es particularmente útil cuando se construye funcionalidad de importación/migración que procesa grandes conjuntos de datos.
- Para el desarrollo de REST API, el rest_example proporciona un patrón completo de implementación de cliente para comunicarse con sitios Drupal externos.
Technical Details
Admin Pages 35
/examples/ajax-example
Página de resumen con enlaces a varias demostraciones de formularios AJAX, incluyendo el ejemplo más simple, AJAX activado por envío, menús desplegables dependientes, secciones de formulario dinámicas y formularios de asistente.
/examples/batch_example
Formulario que demuestra operaciones por lotes con opciones para seleccionar el tamaño del lote y ejecutar el procesamiento por lotes.
/examples/block-example
Página de resumen que explica la creación de bloques con enlaces a la página de administración de bloques donde se pueden colocar los bloques de ejemplo.
/examples/cache-example
Formulario que demuestra operaciones de caché, incluyendo almacenar, recuperar y limpiar datos en caché.
/examples/config-entity-example
Página de listado que muestra todas las entidades de configuración Robot con opciones para agregar, editar y eliminar robots.
/admin/config/form-api-example/config-simple-form
Formulario de configuración que demuestra el almacenamiento simple de configuración traducible.
/content_entity_example_contact/list
Página de listado que muestra todas las entidades de contenido Contact con opciones para agregar, editar, ver y eliminar contactos.
/admin/structure/content_entity_example_contact_settings
Página de configuración para el tipo de entidad Contact.
/examples/cron-example
Formulario para probar la funcionalidad de cron con configuración de intervalo y ejecución manual de cron.
/examples/dbtng-example
Página de resumen que muestra entradas de base de datos con subpáginas para agregar, actualizar y consultas avanzadas.
/examples/dbtng-example/add
Formulario para agregar nuevas entradas a la base de datos demostrando operaciones de inserción.
/examples/email-example
Formulario para enviar correos electrónicos de prueba demostrando la implementación de hook_mail.
/examples/events-example
Formulario que demuestra el despacho y suscripción de eventos con tipo de evento configurable.
/examples/field-example
Página de resumen que explica la implementación del campo de color RGB con enlaces a la configuración del tipo de contenido.
/examples/field-permission-example
Página de resumen que explica los permisos a nivel de campo con enlaces a la configuración de permisos.
/examples/file_example
Formulario que demuestra operaciones de File API incluyendo lectura, escritura y gestión de archivos a través de diferentes stream wrappers.
/examples/form-api-example
Página de resumen con enlaces a varias demostraciones de Form API incluyendo formularios simples, elementos de entrada, contenedores, AJAX y modales.
/examples/hooks-example
Página de resumen que explica las implementaciones de hooks con enlaces para demostrar hook_node_view y hook_form_alter.
/examples/image-example/styles
Formulario para probar efectos de imagen incluyendo el efecto de colorización personalizado con selector de color.
/examples/js-example
Página de resumen con enlaces a demostraciones de JavaScript incluyendo ejemplos de colores/ponderación y acordeón.
/examples/menu-example
Página de resumen que demuestra las características del sistema de menú con enlaces a varios ejemplos de menú incluyendo acceso restringido, pestañas, argumentos de URL y callbacks.
/examples/node-type-example
Página de resumen que explica la creación de tipos de nodo a través de configuración con enlaces a la administración de tipos de contenido.
/examples/page-example
Página de resumen que demuestra la creación básica de páginas con enlaces a ejemplos de página simple y página con argumentos.
/examples/pager-example
Demostración de tabla paginada que muestra cómo mostrar grandes conjuntos de datos a través de múltiples páginas.
/examples/plugin-type-example
Página de resumen que explica la definición de tipos de plugin personalizados con demostración de plugins Sandwich.
/examples/queue_example
Formulario que demuestra operaciones de Queue API incluyendo agregar elementos, reclamar elementos y procesar colas.
/examples/render-example
Página de resumen con enlaces a ejemplos de construcción de render arrays y demostraciones de alter hooks.
/examples/rest-getting-started
Página de resumen que explica la configuración del cliente REST con enlaces a configuración y operaciones de nodo.
/examples/rest-client-settings
Formulario para configurar la conexión del cliente REST a una instancia Drupal remota.
/examples/session_example
Formulario que demuestra el almacenamiento de sesión con campos que persisten valores en la sesión del usuario.
/examples/stream_wrapper_example
Página de resumen que explica la implementación de stream wrapper personalizado para almacenamiento de archivos basado en sesión.
/examples/tabledrag-example
Página de resumen con enlaces a varias demostraciones de tabledrag incluyendo filas simples, jerarquías anidadas y patrones de raíces/hojas.
/examples/tablesort-example
Demostración de tabla ordenable con encabezados de columna clicables para ordenamiento dinámico.
/examples/testing-example
Página de resumen que explica el framework de pruebas PHPUnit con enlaces a demostraciones de pruebas y documentación.
/examples/theming_example
Página de resumen con enlaces a demostraciones de theming incluyendo ejemplos de theming de listas y theming de formularios.
Permissions 19
Hooks 18
hook_toolbar
Añade un elemento de la barra de herramientas de Examples con enlaces a todos los módulos de ejemplo habilitados.
hook_block_view_alter
Modifica la salida del Block; el ejemplo cambia las etiquetas del Block a mayúsculas si contienen la palabra 'uppercase'.
hook_cron
Implementa el procesamiento de cron; ejecuta tareas en segundo plano a intervalos especificados.
hook_mail
Define plantillas de correo electrónico; establece el asunto y el cuerpo del mensaje según la clave del correo.
hook_mail_alter
Altera los correos electrónicos salientes; añade una firma del sitio a todos los mensajes de correo.
hook_entity_field_access
Controla los permisos de acceso a Field basándose en la operación, la definición del Field, la cuenta y la propiedad de la Entity.
hook_file_download
Controla los permisos de descarga de archivos; verifica los permisos del usuario para archivos privados, temporales o de sesión.
hook_help
Proporciona texto de ayuda del módulo que se muestra en las páginas admin/help.
hook_node_view
Procesa la vista del Node; rastrea el conteo de visualizaciones del Node en la sesión e invoca hooks personalizados.
hook_form_alter
Modifica formularios; el ejemplo altera el formulario de inicio de sesión del usuario para cambiar la descripción del campo de nombre de usuario.
hook_hooks_example_count_incremented
Implementación de hook personalizado que demuestra cómo los módulos pueden definir e invocar sus propios hooks.
hook_image_effect_info_alter
Altera la información de efectos de imagen; modifica las descripciones de los efectos de imagen.
hook_theme
Define implementaciones de Theme incluyendo plantillas y variables.
hook_preprocess_page
Preprocesa el render array de la página; puede mover las migas de pan, invertir las barras laterales, mostrar información de depuración.
hook_preprocess_block
Preprocesa el render array del Block; puede envolver los Blocks con marcado adicional.
hook_preprocess_form_element_label
Preprocesa las etiquetas de elementos de formulario; añade formato en negrita basándose en atributos de datos.
hook_node_access
Control de acceso a Node; restringe las operaciones de actualización y eliminación basándose en permisos y autoría.
hook_sandwich_info_alter
Hook de alteración personalizado para definiciones del Plugin Sandwich; modifica las descripciones del Plugin.
Troubleshooting 6
Asegúrese de que el módulo principal 'Examples for Developers' esté habilitado. El módulo toolbar también debe estar habilitado ya que es una dependencia requerida.
Verifique que el usuario tenga los permisos apropiados. Muchas páginas de ejemplo requieren el permiso 'access content', mientras que los ejemplos de Entity requieren permisos específicos como 'administer robots' o 'view contact entity'.
Asegúrese de que JavaScript esté habilitado en el navegador. Algunos ejemplos AJAX tienen variantes 'nojs' que demuestran la degradación elegante. Verifique la consola del navegador en busca de errores de JavaScript.
Verifique que el sitio Drupal remoto tenga los módulos REST y HAL habilitados con autenticación adecuada. El sitio remoto debe permitir Basic Auth para que el ejemplo REST funcione.
Después de habilitar field_example, limpie las cachés. El tipo de Field RGB debería aparecer al agregar Fields a los tipos de contenido.
El efecto de colorización requiere la biblioteca PHP GD con la función imagefilter(). Verifique la configuración de PHP y asegúrese de que la extensión GD esté cargada.
Security Notes 4
- Los ejemplos están destinados para propósitos de aprendizaje en sitios de desarrollo. Algunos ejemplos demuestran intencionalmente patrones simplificados que pueden necesitar refuerzo de seguridad adicional para uso en producción.
- El ejemplo REST almacena credenciales en la configuración; en producción, use mecanismos de almacenamiento de credenciales más seguros.
- El ejemplo de permisos de Field demuestra patrones adecuados de control de acceso a nivel de Field que deben aplicarse al crear Fields personalizados con datos sensibles.
- El file_example demuestra el control de acceso de stream wrapper: siempre implemente verificaciones de acceso adecuadas al crear stream wrappers personalizados.