This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

EventCatcherWidget

2nd December 2020 at 8:07pm
Widgets

Introduction

New in: 5.1.23

This is an advanced widget intended for use by those familiar with HTML, CSS and JavaScript handling of DOM events.

The event catcher widget traps DOM-initiated Javascript events dispatched within its child content, and allows invoking a series of ActionWidgets in response to those events.

In order for the events to be trapped they must:

  • be of one of the events specified in the event catcher widget's events attribute
  • arise within a DOM node specified by the widget's selector attribute
  • support event bubbling

Use of the event catcher widget is beneficial when using large numbers of other trigger widgets such as the ButtonWidget is causing performance problems. The workflow it enables is akin to what is referred to as "event delegation" in JavaScript parlance.

Content and Attributes

The content of the <$eventcatcher> widget is displayed normally.

AttributeDescription
eventsSpace separated list of JavaScript events to be trapped, for example "click" or "click dblclick"
selectorA CSS selector. Only events originating inside a DOM node with this selector will be trapped
actions-*Action strings to be invoked when a matching event is trapped. Each event is mapped to an action attribute name of the form actions-event where event represents the type of the event. For example: actions-click or actions-dblclick
tagOptional. The HTML element the widget creates to capture the events, defaults to:
» span when parsed in inline-mode
» div when parsed in block-mode
classOptional. A CSS class name (or names) to be assigned to the widget HTML element

Variables

The following variables are made available to the actions:

VariablesDescription
dom-*All DOM attributes of the node matching the given selector are made available as variables, with the prefix dom-
modifierThe modifier Variable contains the Modifier Key held during the event (can be "normal", "ctrl", "shift", "alt" or combinations thereof)
event-mousebuttonThe mouse button (if any) used to trigger the event (can be "left", "right" or "middle"). Note that not all event types support the mousebutton property
event-typeThe type property of the JavaScript event
event-detail-*Any properties in the detail attribute of the event are made available with the prefix event-detail-
tv-popup-coordsA co-ordinate string that can be used with the ActionPopupWidget to trigger a popup at the DOM node matching the selector where the event originated
tv-selectednode-posxx offset position of the selected DOM node
tv-selectednode-posyy offset position of the selected DOM node
tv-selectednode-widthoffsetWidth of the selected DOM node
tv-selectednode-heightoffsetHeight of the selected DOM node
event-fromselected-posxx position of the event relative to the selected DOM node
event-fromselected-posyy position of the event relative to the selected DOM node
event-fromcatcher-posxx position of the event relative to the event catcher DOM node
event-fromcatcher-posyy position of the event relative to the event catcher DOM node

Example

This example uses the ActionLogWidget and will log the data-item-id attribute of the clicked DOM node to the browser's JavaScript console

\define clickactions()
<$action-log item=<<dom-data-item-id>> event=<<event-type>>/>
\end

\define contextmenu-actions()
<$action-log item=<<dom-data-item-id>> event=<<event-type>>/>
\end

<$eventcatcher events="click contextmenu" selector=".item" actions-click=<<clickactions>> actions-contextmenu=<<contextmenu-actions>> tag="div">

<div class="item" data-item-id="item1">
Click events here will be trapped
</div>

<div class="item" data-item-id="item2">
And here too
</div>

<div data-item-id="item3">
Not here
</div>

<div class="item" data-item-id="item4">
And here
</div>

</$eventcatcher>