# Link-Based Triggers 🧪

Certain triggers such as click 

## Syntax Expansion

Likely we'll support named or "slotted" formats; 

* `##` - Generic trigger prefix
  * e.g. `##glossaryterm`
* `#1#` - Typed trigger prefix
  * e.g. `#1#abc`

Essentially;

* Identify a trigger-capable area ( can be page-wide )
* Find links that begin with `#`
* and contain
  * May be able to regex match `#..#..` in selector. 

{% code overflow="wrap" %}

```javascript
const elements = [...document.querySelectorAll('a[href^="#"][href*="#"]:not([href="#"])')].filter(el => {
    const match = el.getAttribute('href').match(/^#(\w*)#(\w+)$/);
    return match !== null;
});
```

{% endcode %}

Extract the name, trigger the name. 

On page load, build a list of trigger targets, e.g. IX buttons

Typed trigger wiring process;

* Match to known targets, by name 

## Registered Type Handlers

* ix
* gista ( register and define these as typed trigger handlers in the config code ) 

### Generic trigger

* Create attribute first 
  * wfu-trigger-type
  * wfu-trigger-id 
* wfu-trigger-target-type
* wfu-trigger-target-id

## Other Trigger Types

## Future 

### What is a Trigger?

Currently SA5 supports the click trigger type only.  In this context a trigger is an element such as a link, button, or DIV that is clicked. 

In SA5 terms, a trigger may have these properties;

* Handler. Identifies how the trigger will be handled. Determined as follows;
  * If the trigger element has the attribute `wfu-trigger-handler` - identifies the handler for the trigger. 
  * If unspecified, and the trigger is in a group, that handler is used instead. 
  * If there is no group-specified handler, then the trigger is "unhandled," and defaults to a click handler. 
* ID. Uniquely identifies the trigger, or more specifically the triggering action you want performed. In the case of a click trigger, this identifies the click target. 
  * `wfu-trigger-id` - the unique ID of the trigger 
* Group (optional). If the trigger is in a named group, that group name is applied to the trigger. It acts as a namespace. 
  * wfu-trigger-group
* Content. A trigger element may also contain content;
  * Plain-text content ( innerText )
  * HTML content ( innerHTML )

### What are Trigger Handlers?

Trigger handlers identify how a particular trigger is handled. For example- 

* Click a matching target link.
* Prompt an AI chatbot
* Center a pin in Google maps
* Start a WhatsApp message
* Invoke custom code

The trigger's *handler* is determined as follows;

* If the trigger itself has a `wfu-trigger-handler`, that handler is used
* If not, we check for a trigger group, and a `wfu-trigger-group-handler`. 
* If not, the trigger is considered *unhandled*. It defaults to using the **click handler**, and can be captured in custom code.  

### What is a Trigger Group?

A trigger group is defined as the nearest ancestor ( containing ) element of a trigger which has the custom attribute of `wfu-trigger-group`. 

A group serves two purposes. 

* It can be named, as in `wfu-trigger-group` = (name), in which case that name becomes a namespace for the triggers. Some handlers will use this as a scoping mechanism, so that only targets also matching that group will be triggered
* Default trigger handlers. A group can additionally define a `wfu-trigger-group-handler` which acts as the handler for any *unhandled* triggers within. 

### What are Trigger Targets? 

Some trigger handlers such as the **click handler** can utilize a target element that you specify. 

These are identified by wfu-trigger-target = ID. OPTIONALLY They can be namespaced, by wfu-trigger-target-group, which must match. 

##

### Configure the Trigger Library ( optional )

Register handlers, such as Gista. 

{% code overflow="wrap" %}

```html
<script>
window.sa5 = window.sa5 || [];
window.sa5.push(['triggerConfig', 
  (config) => {
    config.handlers.add ('gista'); 
    return config;
  }]); 
</script> 
```

{% endcode %}

### Custom Code in the the Trigger Callback ( optional )

Custom-code to handle specific trigger events.&#x20;

{% code overflow="wrap" %}

```html
<script>
window.sa5 = window.sa5 || [];
window.sa5.push(['triggerEvent', 
  (event) => {
    console.log("TRIGGER FIRED", event); 
  }]); 
</script> 
```

{% endcode %}

### Setup

A **click trigger** can be placed on any element that can be clicked. It is governed by;

* `wfu-trigger-type` - the type of trigger, which functions as a namespace
* `wfu-trigger-handler` - identifies the handler for the trigger. If unspecified, and the trigger is in a group, that handler is used instead. If there is no group-specified handler, then the trigger is "unhandled," and will only fire events in code. &#x20;
* `wfu-trigger-id` - the unique ID of the trigger&#x20;
* It can also contain content

All click triggers MAY be in a trigger group. This would be the nearest containing element which has the attributes;

* `wfu-trigger-group` - an optional name
* `wfu-trigger-group-type` - an optional default type, which will be applied to untyped (generic) triggers

A **trigger target** can also be placed on any element that can be clicked. Typically this would be a button that is associated with an interaction. It is goverened by;

* wfu-trigger-target-type - type type of target, which functions as a namespace and must match the trigger
* wfu-trigger-target-id - unique ID of the target&#x20;

### Activation

When a trigger is activated, an event is raised in custom code, with-

* Trigger container name
* Trigger type
* Trigger ID

If trigger target elements are found which match that trigger, they will also be clicked.&#x20;

If a handler has been associated with the trigger type, it will be invoked, e.g. Gista.&#x20;

### How it Works

Pre-processing;

* Identifies relevant areas to process links in. These are referred to as `trigger-containers`.
  * Identified with a wfu-trigger-area custom attribute. It can optionally be given a unique name
  * Optionally, set the default type with wfu-trigger-default-type =&#x20;
* Resolves links in those areas, including the parent node&#x20;

### Triggers Invoking Multiple Different Events&#x20;

We're considering the ability for a *single* Trigger to invoke *multiple* Events.&#x20;

For example, `wfu-trigger-click` = `event1,event2,event3`&#x20;

If built, this may be limited to certain trigger types, owever at this point we have not identified key use cases where this adds substantial value.&#x20;

### Chained Events&#x20;

We're also considering the concept of a Trigger as an Action type, so that we can chain Trigger-Event-Action sequences.&#x20;

##

&#x20;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://attr.sygnal.com/overview/events/events/future-plans.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.