/ >

ClickableJS

Documentation on the first script released as part of my AbleJS plugin Library. This plugin makes any element respond to a click event by adding/removing a css class from itself and any number of other targets. It's a constantly evolving animal, but I will endeavor to keep this resource up to date with the latest releases.

ClickableJS

How it works

Clickable acts on a single element. It turns a click of that element into an interactive event, where a class gets added or removed from the element and any number of target elements. This can be used to implement menus, accordians, pop-ups, or any number of interactive UI elements. The beauty of it is that it is fast and as mobile responsive as can be, because all animations or state changes are handled by CSS. However, this means by default, you won't see anything happen in a UI until the CSS has been implemented as well as the script.

It is also highly customisable. It can remove classes only, or add them only, and it can reverse target elements (or do a whole host of other extendable options to them), changing the default behaviour of targets - they do not have to do the same thing as the main element.

Initialisation

<elem data-plugin="clickable"></elem>

The data-plugin attribute can be added to any element which will auto-initialise Clickable in that element. Any settings to be passed in can be added directly to that element by prefixing them with data- and setting them to a valid value for that property.

Example:

<button data-plugin="clickable" data-target="body, .side-nav" data-classname="open" data-bindtoswipe="true" >Menu +<button>

$(elem).clickable([settings, callback])

.clickable() is added to the jQuery library, so you can call this on any element. If nothing is passed in, it will initialise Clickable and bind itself to the click event.

Example:

$(document).ready(function() {
                    $('.menu-button').clickable({
                        target: "body, .side-nav",
                        classname: "open",
                        bindtoswipe: true,
                        callback: function() {
                            alert("menu button clicked");
                        }
                    }, function(){
                        alert("A callback could go here instead. Its will over-ride any included in the settings object.")
                    });
                });
            

Customisable Settings

string classname

Default: "clicked"

Specify a custom value for the applied class to run your CSS from.

selector target

Default: false

Specify any targets as a css selector. Upon click, they will also receive the classname value and can be styled accordingly. To include multiples, use a comma separator as you would in standard css selectors.

bool bindtoswipe

Default: false

Switch from a click event to a swipe event on a mobile. Useful for menus. Requires a "swipeElement" and swipe events to be specified and supported by an associated library.

selector swipeElement

Default: ".touch body"

The element to apply the swipe binding to. When used in conjunction with Modernizr, the default element will only be selected if the device is touch enabled.

string swipeOnEvent

Default: "swipeleft"

The event on which to bind the "on" event. The default value will only work if jQuery.Mobile is enabled. If using a different swipe provider, that library's event name should be used

string swipeOffEvent

Default: "swiperight"

The event on which to bind the "off" event. The default value will only work if jQuery.Mobile is enabled. If using a different swipe provider, that libraries event name should be used

selector swipeEscape

Default: ".no-swipe"

Any matching selectors will not trigger the swipe event if they are the event target. For example, if using a swipeable slider, its class should be included in the swipeEscape property to avoid Clickable firing whilst trying to swipe through the slider.

selector reap

Default: false

Specify any targets to be 'unclick' as a css selector. Upon click, they will have the classname value removed. Useful for accordian lists where other items in the list collapse as another item is opened. To include multiples, use a comma separator as you would in standard css selectors. Specific cases are built in for the following selectors:

default: "#id, .class" Unclicks the specified elements with the same classname value as the current instance of Clickable.
"parents" Unclicks direct parent and its siblings as well as their children, so long as they have the same classname value as the current instance of Clickable.
"siblings" Unclicks all siblings of the clicked element with the same classname value as the current instance of Clickable.
"all" Unclicks any elements in the entire document that are clicked with the same classname value as the current instance of Clickable.

function callback

Default: false

A function to be called after Clickable has completed everything else. It receives one argument which is the specific Clickable instance, giving access to the config and exposing the prototype. Can only be passed in via JavaScript.

string reapingClass

Default: "reaping"

A class that is applied to the parent element during the reaping.

bool contain

Default: false

If true, Clickable will ignore event propagation, meaning it will only run if the event target is the Clickable element itself. It will also prevent the default event from firing.

Destruction

$(elem).clickable("destroy")

To unbind and remove all trace of Clickable after initialisation, call Clickable on the element and pass in a single string value "destroy". To rebind, you will have to pass in your settings again.

Hijack after initialisation

$(elem).clickable(["turnOn" | "turnOff" | "destroy"])

Some of the prototype methods of Clickable are accessible by passing in a string value. We have looked at "destroy". You can also force a state change of an initialised Clickable element by passing in a single string value of "turnOff" or "turnOn".

$(elem).data("clickable")

Clickable stores its instance as a data value on each intialised element. You can hijack the Clickable instance, to directly change settings or add new functionality, by calling this stored data:

var instance = $(elem).data("clickable")

To overwrite settings you can then access the config object off of this: instance.config, or you can access the methods to add in your own functionality, although this can change the way Clickable works so is not advised.

$(elem).on("clickabled", function(){}), $(elem).on("unclickabled", function(){})

Clickable triggers custom events on the Clickable element. Different events are fired upon click and unclick: "clickabled" and "unclickabled". Adding event handlers to these will allow custom functions to be fired after clickable has completed its cycle, but before any other callbacks that are attached already.

Other Resources:

Comments

Post your own

There's no more content down here, what's with the crazy scrolling...