Plugins - Parte 4
Ganchos de eventos
En el capítulo anterior del Tutorial de Plugins, es posible que hayas notado que nuestra lógica de plugin estaba comprendida en dos métodos. Cada uno de estos métodos, onPluginsInitialized
y onPageInitialized
, corresponde a eventos hooks que están disponibles a lo largo del ciclo de vida de Grav.
Para aprovechar al máximo el poder de los plugins de Grav, necesitas saber qué eventos hooks están disponibles, en qué orden se llaman estos hooks y qué está disponible durante estas llamadas. Los eventos hooks tienen una relación directa con el Ciclo de Vida de Grav.
Orden de Eventos
La mayoría de los eventos dentro de Grav se disparan en un orden específico y es importante entender este orden si estás creando plugins:
- onFatalException (sin orden, puede ocurrir en cualquier momento)
PluginsLoadedEvent
class (1.7)PluginsLoadedEvent
class (1.7)- onPluginsInitialized
FlexRegisterEvent
class (1.7)- onThemeInitialized
- onRequestHandlerInit (1.6)
- onTask (1.6)
- onTask.{task}
- onAction (1.6)
- onAction.{action} (1.6)
- onBackupsInitialized
- onSchedulerInitialized (1.6)
- onAssetsInitialized
- onTwigTemplatePaths
- onTwigLoader
- onTwigInitialized
- onTwigExtensions
- onBuildPagesInitialized (una vez cuando las páginas se reprocesan)
- onPageProcessed (cada página que aún no está en caché)
- onFormPageHeaderProcessed (1.6) (cada página que aún no está en caché)
- onFolderProcessed (para cada carpeta encontrada)
- onPagesInitialized
- onPageInitialized
- onPageContentRaw (cada página que aún no está en caché)
- onMarkdownInitialized
- onPageContentProcessed (cada página que aún no está en caché)
- onPageContent (llamado la primera vez que se llama a Page::content() incluso cuando está en caché)
- onPageNotFound
- onPageAction (1.6)
- onPageAction.{action} (1.6)
- onPageTask (1.6)
- onPageTask.{task} (1.6)
- onTwigPageVariables (cada página que aún no está en caché)
- onHttpPostFilter (1.5.2)
- onTwigSiteVariables
- onCollectionProcessed (cuando se solicita la colección)
- onOutputGenerated
- onPageHeaders
- onOutputRendered
- onShutdown
Eventos misceláneos:
- onBlueprintCreated
- onTwigTemplateVariables
- onTwigStringVariables
- onBeforeDownload
- onPageFallBackUrl
- onMediaLocate
- onGetPageBlueprints
- onGetPageTemplates
- onFlexObjectRender (1.6)
- onFlexCollectionRender (1.6)
- onBeforeCacheClear
- onImageMediumSaved (ImageFile)
- onAfterCacheClear (1.7)
- onHttpPostFilter (1.7)
PermissionsRegisterEvent
class (1.7)
Core Grav Event Hooks
Hay varios eventos hooks centrales de Grav que se activan durante el procesamiento de una página:
onFatalException
Este es un evento que puede activarse en cualquier momento si PHP lanza una excepción fatal. Actualmente, es utilizado por el plugin problems
para manejar la visualización de una lista de posibles razones por las que Grav lanza la excepción fatal.
onPluginsInitialized
Este es el primer evento de plugin disponible. En este punto, los siguientes objetos han sido iniciados:
- Uri
- Config
- Debugger
- Cache
- Plugins
Un plugin no se cargará en absoluto si se ha establecido la opción de configuración enabled: false
para ese plugin en particular.
onAssetsInitialized
El evento indica que el administrador de activos ha sido inicializado y está listo para que se agreguen y gestionen activos.
onPagesInitialized
Este evento significa que todas las páginas en la carpeta user/pages
de Grav han sido cargadas como objetos y están disponibles en el objeto Pages.
onPageNotFound
Este es un evento que puede activarse si no se encuentra una página esperada. Actualmente, es utilizado por el plugin error
para mostrar una bonita página de error 404.
onPageInitialized
La página actual solicitada por una URL ha sido cargada en el objeto Page.
onOutputGenerated
La salida ha sido procesada por el motor de plantillas Twig y ahora es solo una cadena de HTML.
onPageHeaders
Permite la manipulación del objeto de encabezados de la página.
onOutputRendered
La salida ha sido completamente procesada y enviada a la pantalla.
onShutdown
Un nuevo y muy poderoso evento que te permite realizar acciones después de que Grav ha terminado de procesar y la conexión con el cliente se ha cerrado. Esto es particularmente útil para realizar acciones que no necesitan interacción del usuario y que potencialmente podrían afectar el rendimiento. Posibles usos incluyen el seguimiento de usuarios y el procesamiento de trabajos.
onBeforeDownload
Este nuevo evento pasa un objeto de evento que contiene un archivo
. Este evento puede usarse para realizar registros o conceder/negar acceso para descargar dicho archivo.
onGetPageTemplates
Este evento permite a los plugins proporcionar sus propias plantillas además de las recopiladas de la estructura de directorios del tema y el núcleo. Esto es especialmente útil si deseas que el plugin proporcione su propia plantilla.
Ejemplo
/**
* Agregar tipos de plantillas de página.
*/
public function onGetPageTemplates(Event $event)
{
/** @var Types $types */
$types = $event->types;
$types->register('downloads');
}
Esto permite que un plugin registre una plantilla (que podría proporcionar) para que aparezca en la lista desplegable de tipos de plantillas de página (como cuando se edita una página). En el ejemplo anterior, se agrega un tipo de plantilla downloads
ya que hay un archivo downloads.html.twig
en el directorio downloads
.
onGetPageBlueprints
Este evento, al igual que onGetPageTemplates
, permite que el plugin proporcione sus propios recursos además de los específicos del núcleo y del tema. En este caso, son los blueprints.
Ejemplo
$scanBlueprintsAndTemplates = function () use ($grav) {
// Escanear blueprints
$event = new Event();
$event->types = self::$types;
$grav->fireEvent('onGetPageBlueprints', $event);
self::$types->scanBlueprints('theme://blueprints/');
// Escanear plantillas
$event = new Event();
$event->types = self::$types;
$grav->fireEvent('onGetPageTemplates', $event);
self::$types->scanTemplates('theme://templates/');
};
En este ejemplo, estamos utilizando tanto los hooks onGetPageTemplates
como onGetPageBlueprints
para hacer que estos recursos proporcionados por el plugin (plantillas y blueprints) estén disponibles para Grav para herencia y otros usos.
Hooks de Evento Twig
Twig tiene su propio conjunto de hooks de evento.
onTwigTemplatePaths
Las ubicaciones base para las rutas de plantillas se han establecido en el objeto Twig. Si necesitas agregar otras ubicaciones donde Twig buscará rutas de plantillas, este es el evento que debes usar.
Ejemplo
/**
* Agregar directorio de plantillas a la ruta de búsqueda de Twig.
*/
public function onTwigTemplatePaths()
{
$this->grav['twig']->twig_paths[] = __DIR__ . '/templates';
}
onTwigInitialized
El motor de plantillas Twig se ha inicializado en este punto.
onTwigExtensions
Las extensiones principales de Twig se han cargado, pero si necesitas agregar tu propia extensión Twig, puedes hacerlo con este hook de evento.
onTwigPageVariables
Donde Twig procesa una página directamente, es decir, cuando configuras process: twig: true
en los encabezados YAML de una página. Aquí es donde debes agregar cualquier variable a Twig que necesite estar disponible para Twig durante este proceso.
onTwigSiteVariables
Donde Twig procesa toda la jerarquía de plantillas del sitio. Aquí es donde debes agregar cualquier variable a Twig que necesite estar disponible para Twig durante este proceso.
Hooks de Evento de Colección
onCollectionProcessed
Si necesitas manipular una colección después de que haya sido procesada, este es el momento de hacerlo.
Hooks de Evento de Página
onBuildPagesInitialized
Este evento se dispara una vez cuando las páginas se van a reprocesar. Esto generalmente ocurre si la caché ha expirado o necesita ser actualizada. Este es un evento útil para usar en plugins que necesitan manipular contenido y almacenar en caché los resultados.
onBlueprintCreated
Se utiliza para procesar y manejar formularios.
onPageContentRaw
Después de que se ha encontrado una página, se han procesado los encabezados, pero el contenido no se ha procesado. Esto se dispara para cada página en el sistema Grav. El rendimiento no es un problema porque este evento no se ejecutará en una página en caché, solo cuando se borra la caché o se produce un evento que la borra.
onPageProcessed
Después de que una página ha sido analizada y procesada. Esto se dispara para cada página en el sistema Grav. El rendimiento no es un problema porque este evento no se ejecutará en una página en caché, solo cuando se borra la caché o se produce un evento que la borra.
onMarkdownInitialized
Se llama cuando Markdown ha sido inicializado. Permite anular la implementación de procesamiento predeterminada de Parsedown. Ver un ejemplo de uso en el PR que lo introdujo.
onPageContentProcessed
Este evento se dispara después de que el método content()
de la página ha procesado el contenido de la página. Esto es particularmente útil si deseas realizar acciones en el contenido post-procesado pero asegurar que los resultados se almacenen en caché. El rendimiento no es un problema porque este evento no se ejecutará en una página en caché, solo cuando se borra la caché o se produce un evento que la borra.
onFolderProcessed
Después de que una carpeta ha sido analizada y procesada. Esto se dispara para cada carpeta en el sistema Grav. El rendimiento no es un problema porque este evento no se ejecutará en una página en caché, solo cuando se borra la caché o se produce un evento que la borra.
onPageFallBackUrl
Si una ruta no se reconoce como una página, Grav intenta acceder a un recurso multimedia de la página. El evento se dispara tan pronto como comienza el procedimiento, por lo que los plugins pueden engancharse y proporcionar funcionalidad adicional.
onMediaLocate
Agrega soporte para ubicaciones de medios personalizadas para extractos.
onTwigLoader
Agrega soporte para el uso de namespaces en conjunto con dos nuevos métodos en la clase Twig: Twig::addPath($path, $namespace)
y Twig::prependPath($path, $namespace)
.