Event Handlers (Clicking)

mouseClick: Clicking the Mouse on an Element

The mouseClick LogUI event handler provides enhanced handling of mouse click events that take place on the element(s) that you specify. This custom event handler is supported as of LogUI Client version 0.5.3e.

The mouseClick event handler supports the ability to detect clicks on an element with either the primary, secondary, or auxiliary mouse buttons. This is opposed to the standard click event, which works only with the primary mouse button. While support for detecting click events on auxiliary buttons is possible with contemporary browsers, support is still not widespread — Safari, for example, does not support it. The mouseClick events implements detection of a click event across all these buttons, and works on all contemporary web browsers.

To be explicit, the following buttons are supported. Note that the operating system decides what buttons are which, and is customisable by the user of the system. This is why we don't use left, middle, or right to name mouse buttons.

• The primary button. This is by default the left button on the mouse, or a tap/click on the trackpad.
• The secondary button. This is usually the right button on the mouse, or two fingers tapping on a trackpad.
• The auxiliary button. This is usually a click of the scrollwheel in the middle of the mouse, or the middle button (if no scrollwheel is present). Typically, this event is not captured on a trackpad.

LogUI also supports the ability to track clicks from two further, seldom found buttons. These are often found on higher-end mice.

• The auxiliary2 button. This is usually mapped to the browser's back navigation button.
• The auxiliary3 button. This is usually mapped to the browser's forward navigation button.

We don't recommend that you track for auxiliary2 or auxiliary3 events; you'll probably be disappointed unless you know your users will have these buttons available to them (and actually use them!).

Be careful tracking secondary click events. If you have context menus appear when the user clicks the secondary button (as is what happens by default on a web browser), the event can be missed. LogUI does not alter the behaviour of your application; if you wish to guarantee this behaviour be recorded, you must suppress context menus appearing when the user clicks the secondary button on their mouse/trackpad.

A click event constitutes two native events on an element: a mousedown event, which is triggered when the mouse button/trackpad is pushed down, and a mouseup event, which is triggered when the button/trackpad is released. The duration of the click is recorded (from mousedown to mouseup), as well as which button was used on the mouse to initiate the mouseClick.

Example Usage

Specify the following configuration to use the mouseClick event. Note that metadata can be recorded for the element(s) in question in the normal way.

    '<GROUPING_NAME>': {
        selector: <SELECTOR>,
        event: 'mouseClick',
        properties: {
            <BUTTON>: {
                name: '<NAME>',
            },
        },
    },

See the following.

• Replace <GROUPING_NAME> with a unique, human-readable name for the grouping.
• Replace <SELECTOR> with the selector to select the element(s) you wish to apply the mouseClick event to.
• Replace <BUTTON> with the name of the button you wish to capture clicks with.
• Replace <NAME> with an identifiable name for your logs for your event. This is optional; but we highly recommend it. It will make parsing your logs so much easier.

For a complete example, have a look below. Note that you can specify multiple mouse buttons within a single grouping!

    'element-click-primary-aux': {
        selector: '#element-to-click',
        event: 'mouseClick',
        properties: {
            primary: {
                name: 'MOUSE_CLICK',
            },
            auxiliary: {
                name: 'MOUSE_CLICK',
            },
        },
    },

In this example, when a user clicks on the element selected by #element-to-click with either their primary or auxiliary mouse button, events will be fired with MOUSE_CLICK for the name. Note here that the name is the same for both primary and auxiliary to give the effect of the same event (for easier log parsing). You will still be able to discern what button was pushed (see the example output below).

If we removes the auxiliary entry, no event would be fired when the user clicks on the element selected by #element-to-click when the auxiliary mouse button is pushed. As such, only clicks are logged when the relevant property is specified correctly.

By default, applying mouseClick to an element without any properties will have no effect (i.e., no event will be logged). Be sure to specify at least button in your properties object!

Logged Output

The following JSON output provides an example event that is called using the mouseClick event handler. In the example below, the example event above is used (when the user clicked the primary mouse button).

Pay particular attention to the eventDetails object.

• The eventType is an interactionEvent as usual for a user interaction.
• The type of the event is a mouseClick.
• button yields the button that was used for the mouseClick event.
  • primary denotes the primary mouse button (by default, the left button).
  • secondary denotes the secondary mouse button (by default, the right button).
  • auxiliary denotes the auxiliary mouse button (by default, the scrollwheel button, or a middle button).
  • auxiliary2 denotes the second auxiliary button, usually found on high-end gaming mice. This is usually tied to the back navigation button on the mouse (by default).
  • auxiliary3 denotes the third auxiliary button, usually found on high-end gaming mice. This is usually tied to the forward navigation button on the mouse (by default).
• clickDuration reports the time, in milliseonds, of the click duration.

Metadata and application specific data is reported in the usual way.

{
    "applicationSpecificData": {
        ...
    },
    "eventDetails": {
        "clickDuration": 115.9849999967264,
        "type": "mouseClick",
        "button": "primary",
        "name": "MOUSE_CLICK"
    },
    "eventType": "interactionEvent",
    "metadata": [
    	...
    ],
    "sessionID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "timestamps": {
        "eventTimestamp": "Wed May 05 2021 22:16:59 GMT+0100 (British Summer Time)",
        "sinceSessionStartMillis": 4701037,
        "sinceLogUILoadMillis": 1774
    }
}