grav plugins

Ganchos de eventos

Event Hooks

Tabla de contenido

  1. Orden de Eventos
  2. Core Grav Event Hooks
  3. Hooks de Evento Twig
  4. Hooks de Evento de Colección
  5. Hooks de Evento de Página

En el artículo de Crear un plugin, es posible que hayas notado que la lógica de un 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:

  1. onFatalException (sin orden, puede ocurrir en cualquier momento)
  2. PluginsLoadedEvent class (1.7)
  3. PluginsLoadedEvent class (1.7)
  4. onPluginsInitialized
  5. FlexRegisterEvent class (1.7)
  6. onThemeInitialized
  7. onRequestHandlerInit (1.6)
  8. onTask (1.6)
    1. onTask.{task}
  9. onAction (1.6)
    1. onAction.{action} (1.6)
  10. onBackupsInitialized
  11. onSchedulerInitialized (1.6)
  12. onAssetsInitialized
  13. onTwigTemplatePaths
  14. onTwigLoader
  15. onTwigInitialized
  16. onTwigExtensions
  17. onBuildPagesInitialized (una vez cuando las páginas se reprocesan)
    1. onPageProcessed (cada página que aún no está en caché)
    2. onFormPageHeaderProcessed (1.6) (cada página que aún no está en caché)
    3. onFolderProcessed (para cada carpeta encontrada)
  18. onPagesInitialized
  19. onPageInitialized
    1. onPageContentRaw (cada página que aún no está en caché)
    2. onMarkdownInitialized
    3. onPageContentProcessed (cada página que aún no está en caché)
    4. onPageContent (llamado la primera vez que se llama a Page::content() incluso cuando está en caché)
  20. onPageNotFound
  21. onPageAction (1.6)
    1. onPageAction.{action} (1.6)
  22. onPageTask (1.6)
    1. onPageTask.{task} (1.6)
  23. onTwigPageVariables (cada página que aún no está en caché)
  24. onHttpPostFilter (1.5.2)
  25. onTwigSiteVariables
  26. onCollectionProcessed (cuando se solicita la colección)
  27. onOutputGenerated
  28. onPageHeaders
  29. onOutputRendered
  30. onShutdown

Eventos misceláneos:

  1. onBlueprintCreated
  2. onTwigTemplateVariables
  3. onTwigStringVariables
  4. onBeforeDownload
  5. onPageFallBackUrl
  6. onMediaLocate
  7. onGetPageBlueprints
  8. onGetPageTemplates
  9. onFlexObjectRender (1.6)
  10. onFlexCollectionRender (1.6)
  11. onBeforeCacheClear
  12. onImageMediumSaved (ImageFile)
  13. onAfterCacheClear (1.7)
  14. onHttpPostFilter (1.7)
  15. PermissionsRegisterEventclass (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).