ClickTrigger2

Turn DOM Elements into triggers that initiate action upon clicking them.

Installation

> npm i @gebruederheitz/clicktrigger2

Usage

Clicktrigger2 is a utility to easily attach mouse click listeners and events to DOM elements using classnames, data-attributes or a script config.

import { FactoryDOMConfig, FactoryDataAttributeConfig } from '@gebruederheitz/clicktrigger2';

Or use the UMD bundle directly:

<script src="/path/to/node_modules/@gebruederheitz/clicktrigger2/dist/bundle.js"></script>
<script>
    const factory = ghct.FactoryDOMConfig;
</script>

Or use the autoloading bundle that initializes the appropriate factory as soon as the DOM is ready:

<script src="/path/to/node_modules/@gebruederheitz/clicktrigger2/dist/auto-bundle.js"></script>

Configuration

Configuration options

Most configuration options can apply globally (so they only need to be set once) as well as for single trigger elements (so they can be overridden individually) as indicated by the "Availability" column.

Using a global DOM object

Scrolling

You can define breakpoints to customise scrolling behaviour for different screen sizes:

let config = {
    // ...
    scroll: {
        doScroll: true,
        breakpoints: {
            0: {
                doScroll: true,
                buffer: 50,
            },
            756: {
                doScroll: false,
            },
            1200: {
                doScroll: true,
                buffer: '100vh',
            },
        },
    },
};

This configuration will

• scroll 100vh on screens wider than 1200px,
• not scroll on screens between 756px and 1200px,
• and scroll 50px for any screen narrower than that.

You can also apply scrolling only when the target is being triggered by a LocationTrigger, i.e. in response to a navigation or hashchange event, but not when targeted by a ClickTrigger, i.e. a mouse click / tap.

let config = {
    // ...
    scroll: {
        doScroll: true,
        locationOnly: true,
        buffer: 50,
    },
};

// Can also be used with breakpoints:
config = {
    scroll: {
        doScroll: true,
        breakpoints: {
            0: {
                doScroll: true,
                locationOnly: true,
                buffer: 50,
            },
            756: {
                doScroll: false,
            },
            1200: {
                doScroll: true,
                buffer: '100vh',
            },
        },
    },
};

Using data attributes

As this tool was originally written to provide a simple interface usable with a no-code tool such as Webflow, most configuration can be performed without a single line of JavaScript, using element data attributes for configuration.

<div
    data-triggertype='toggle'
    data-triggertarget='#test1'
    data-triggergroup="gr1"
    data-triggerslug="test1"
>
    Trigger
</div>

<div id="test1">Target</div>

You can use the following attributes, some of which are directly equivalent to their JS configuration counterparts. In general, all settings apply only to the trigger element they are declared on, the special element with data-triggerglobals being the exception.

Styling

You may use and extend the default styles provided by this package in your (S)CSS:

// Your frontend SASS file

// Import the stylesheet
@use 'node_modules/@gebruederheitz/clicktrigger2/scss/clicktrigger2' with (
  $variable: 'value',
);

Take a look at scss/clicktrigger2.scss for a list of available overrides.

Or use the precompiled CSS file:

<link
    rel="stylesheet"
    href="/path/to/node_modules/@gebruederheitz/clicktrigger2/dist/clicktrigger2.css"
/>

Development

Factory serves more or less as an abstract class for the different configuration method-dependent Factories.

ClickTrigger acts as a very simple interface to the DOM click event via the trigger HTML element, whose class assignment it also handles.

Target is more or less the main controlling element, subscribing to both its trigger(s) and group and broadcasting any state changes to any interested parties.

Group acts as a simple interface to collect and forward events from all Targets that subscribe to it. Additionally, it keeps track on whether there's an element currently open.

Dependencies

• nodeJS LTS (16.x)
• nice to have:
  • GNU make or drop-in alternative
  • NVM

Quickstart

You can use the watch task:

$> npm run watch
# or
make
# or, more explicitly
make dev

After making your changes, run

npm run build
# or
make build

to create the ES5 build at dist/bundle.js, the auto-init bundle at dist/auto-bundle.js and the ES-module build at dist/index.mjs and make certain everything runs smoothly. You should also run make lint at least once to avoid simple linting issues.

When you're finished, you can use make release on the main branch to publish your changes.