trigger_api

The Trigger API module aims to provide tools for developper that simplify and unify the way to send data from PHP to JS.
This module allows backend developpers to add data in a queue that will be reachable by JS process thanks to events. The advantage of the trigger api is the unique way to send data from PHP in several context (default HTML Response, or AJax Response).
It also provides tools for contributors to trigger data from a CKEditor plugin or a Webform Element.

This tools is mainly useful for triggering data use for user experience analysis or tracking tools like GTM, Matomo or whatever.

The process

Backend side, the api provides a TriggerQueue service that will stock the event to trigger to the Frontend. This queue can receive an array of data and a string type (to identify which kind of data is triggered, and how the frontend will treat this data). Then this data will be sent to the front either via drupalSettings or an ajax command depending on the request context.
The trigger api provides a javascript library that will parse all the queued data (independently of the context) and the redispatch an document event identified by the string type passed to the queue.
Then the triggered event can be catch by a custom javascript script that can treat the triggered data in the same way independently of the context.

Features

Dispatch events from PHP

For example, if you want to trigger a data {"type_page":"my_page_type"} for "gtm", you can use the trigger api :

  TriggerQueue::me()->add(
    new TriggerQueueData(
      // The type of event.
      'gtm', 
      // The event data.
      [
        'typepage' => 'my_page_type',
      ]
   )
);

Then, in your custom javascript pocess you can catch this event simply as this :

document.addEventListener('gtm', (data) => {
   // data : {"type_page":"my_page_type"}
   console.log('You can treat the data passed from PHP', data);
})

Dispatch event from HTML

The trigger API provides an attributes system that allows you to define events in HTML.
You can define theses attributes :

data-trigger-api-type : the type of event.
data-trigger-api-on: the js event that trigger ("appear" to trigger when element is added in the DOM)
data-trigger-api-data : the data in json string

For example :

<h1 data-trigger-api-type="gtm" data-trigger-api-on="appear" data-trigger-api-data={"title":"My Title"}>My Title</h1>
<a href="#test" data-trigger-api-type="gtm" data-trigger-api-on="click" data-trigger-api-data={"type":"Click me button"}>Click me !</a>

Use the Ckeditor plugin

The Trigger API provides a Ckeditor Plugin where contributors can directly add custom events from an interface :

Use the webform element

The module provides a trigger api element in the CKeditor. It's mainly useful to trigger specific event via the trigger api in a stepped form.

Dispatch from javascript

You can dispatch event using this method :
Drupal.behaviors.trigger_api.dispatch('gtm', {test:"value"});

You can also enable or disable logging events directly in your developer console using :
window.triggerApiEnableLog() and window.triggerApiDisableLog()