Skip to content

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

License

Notifications You must be signed in to change notification settings

gebruederheitz/clicktrigger2

Repository files navigation

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.

Option Availability Type Default value Description
scroll global & element object see below
scroll.doScroll boolean false whether to enable scrolling to a trigger's target when it's opened
scroll.buffer string number ''
scroll.scrollBack boolean true When enabled, will attempt to scroll so the trigger is near the centre of the viewport when closing the target
scroll.breakpoints object Allows to configure scrolling for individual breakpoints in responsive views, see below.
scroll.locationOnly boolean false When enabled, scrolling will only be performed when triggered by location
reposition global & element boolean false Whether to reposition the target element to fit into a row underneath the current row of triggers. In flex-mode this requires a flex-basis in percent to be set on the trigger.
method global & element string 'jQuery' Which method to use for showing/hiding the target. The default uses jQuery's slideDown() and slideUp(), any other value will leave it to you (or the default stylesheets) to handle CSS animations based on the classnames.
classes global & element object see below Allows you to customize the classnames given to the various element states
classes.target.visible string 'gh-ct-visible' Any visible target will receive this class
classes.target.hidden string 'gh-ct-hidden' Any non-visible target will receive this class once it's been hidden for the first time
classes.trigger.active string 'gh-trigger-active' Any trigger whose target is visible will receive this class
classes.trigger.inactive string 'gh-trigger-inactive' Any non-active trigger, i.e. whose target is hidden, has this class from initialization
classes.trigger.contrast string 'gh-trigger-contrast' Any non-active trigger will receive this class while another trigger is active
type element `'toggle' 'hide' 'show'`
slug element string random UUID Define a custom slug which allows triggering the element via a location hash (mysite.com/page#element-slug)
groupName element string '' Out of any group a maximum of one element can be open at any time. If a different trigger in the same group is clicked, the previously open element is closed. The contrast class is also based on a trigger's group assignment.
target element DOMSelectorString '' A selector string identifying the target element. You can use a special "parent of" syntax to beat the cascade if required: $parent::$parent::#my_element selects the grandparent of #my-element.
secondary element boolean false Defines a trigger as a secondary trigger. Only the primary trigger will be considered for scrolling (scrollback) and repositioning calculations. When defining multiple triggers without defining them as secondary, the primary trigger is overwritten.

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.

data-attribute equivalent config key notes
triggertype type has an additional "toggleClass" type, which sets "method" to non-jQuery and uses type "toggle"
triggertarget target The required attribute declaring any element as a trigger.
triggergroup group
triggerslug slug
triggersecondary secondary
triggerglobals -none- a special non-trigger element used to declare global settings
triggerscroll scroll.doScroll & scroll.buffer Do scroll is false when absent, true otherwise. The value defined the scroll buffer.
triggernoscrollback scroll.scrollBack scrollback is enabled by default and can be unset by setting a value
triggeractive classes.trigger.active comma-separated list of classnames to apply to the active trigger element
triggerinactive classes.trigger.inactive comma-separated list of classnames to apply to all inactive trigger elements while a trigger is active
triggerreposition reposition
triggermethod method

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.