Simple Custom Attributes

This will allow you to define and use custom attributes in the DOM.

About

If you are used to using any modern front end frameworks, you are probably also used to doing things like:

<div ng-click='someMethod'> // Angular
<div rv-on-click='someMethod'> // Rivets
<div on-click='someMethod'> // Riot.js

This library makes custom attribute binding super easy without having to use some massive lame framework.

You can define your own with a simple attribute binding API.

Using The Library

1. npm install --save-dev simple-custom-attributes
2. Require it in, and run the register method passing a dom element and a scope object.

   var simpleCustomAttributes = require('simple-custom-attributes');
   
   simpleCustomAttributes.register(object, rootElement);

   Then when you are done, you unregister.

   simpleCustomAttributes.unregister(object, rootElement);

This will register all custom attributes in the root element. No need to do it one at a time like I have done in the examples below.

Note: The this scope of the method (if you are passing a method to the binding) is the object you registered.

Examples

Lets say you have a off-canvas menu and you wanted to make a swipe gesture close it. You would add a on-swipe-right attribute passing a method you want to call when the swipe right is complete.

The DOM.

<div class='off-canvas-nav-thing' on-swipe-right='closeNav'>
  // Nav HTML HERE
</div>

The view

var simpleCustomAttributes = require('simple-custom-attributes'),
    view = {
        closeNav : function() {
            // code to close the nav.
            // Note: `this` in here === the `view`
        }
    };

simpleCustomAttributes.register(view, document.querySelector('.off-canvas-nav-thing'));

When the user swipes right, it will call that closeNav function.

Lets say you had a element that has some fat paragraph of text in it and you wanted to clamp that to 3 lines.

The DOM.

<div class='some-fat-text-in-here' line-clamp='model.linesToClampTheFatText'>
    400 lines of lorem ipsum.
</div>

The View.

var simpleCustomAttributes = require('simple-custom-attributes'),
    model = {
        linesToClampTheFatText : 3
    };

simpleCustomAttributes.register(view, document.querySelector('.some-fat-text-in-here'));

After the registration is complete, that pile of text will be truncated to 3 lines.

Simple click handler.

The DOM.

<div class='clicky-mc-click-face' on-click='yeahBuddy'>
</div>

The View.

var simpleCustomAttributes = require('simple-custom-attributes'),
    view = {
        yeahBuddy : function() {

        }
    };

simpleCustomAttributes.register(view, document.querySelector('.clicky-mc-click-face'));

Will call the yeahBuddy method when the element is clicked.

Define your own custom attribute.

Each custom attribute must have the following methods.

{
    bind : function(el, value) {
        // el === The element in question.
        // value === could be a function, a value, anything really. Depends on what you passed the binding.

        // NOTE: The scope of this closure is the bound object. so, `this` === the view you are binding

        // You add event listeners, do work etc here.
    },
    unbind : function(el, value) {
        // undo everything you did in the previous method.
    }
}

To include this custom attribute into the library, either make a pull request. OR. Call the addAttribute method.

When you call addAttribute you will pass a string corresponding with the attribute name and a object containing the above mentioned properties. (you can also use this to override existing attributes.)

If I wanted to define a on-input handler for an input element. Like so:

var simpleCustomAttributes = require('simple-custom-attributes');

simpleCustomAttributes.addAttribute('on-input', {
    bind : function(el, value) {
        el.addEventListener('input', value, false);
    },
    unbind : function(el, value) {
        el.removeEventListener('input', value, false);
    }
})

Semi Baked in Attributes

Right now, we included the following into the library cause I use them all the time: They are in the repo, but you will need to call addAttribute on the instance to actually use them.

line-clamp='model.linesToClamp'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('line-clamp', require('simple-custom-attributes/attributes/line-clamp'));

<div line-clamp='4'>
    This text will be clamped to 4 lines with an ellipsis at the end.
</div>

on-mouse-in='someMethod'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-mouse-in', require('simple-custom-attributes/attributes/on-mouse-in'));

<div on-mouse-in='someMethod'></div>

on-mouse-out='someMethod'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-mouse-out', require('simple-custom-attributes/attributes/on-mouse-out'));

<div on-mouse-out='someMethod'></div>

on-swipe-left='someMethod'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-swipe-left', require('simple-custom-attributes/attributes/on-swipe-left'));

<div on-swipe-left='someMethod'></div>

on-swipe-right='someMethod'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-swipe-right', require('simple-custom-attributes/attributes/on-swipe-right'));

<div on-swipe-right='someMethod'></div>

on-click='someMethod'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-click', require('simple-custom-attributes/attributes/on-click'));

<div on-click='someMethod'></div>

on-event='{ event : method, event : method }'

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-event', require('simple-custom-attributes/attributes/on-event'));

<div on-event='{ mouseover : handleMouseOver, mouseout : handleMouseOut }'></div>

on-click-and-hold

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-click-and-hold', require('simple-custom-attributes/attributes/on-click-and-hold'));

<div on-click-and-hold='someMethod'></div>

on-enter-viewport (NOTE!!!! THIS ONLY WORKS IN CHROME 51 BECAUSE IT USES INTERSECTION OBSERVERS)

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-enter-viewport', require('simple-custom-attributes/attributes/on-enter-viewport'));

<div on-enter-viewport='someMethod'></div> // Note: SomeMethod will be called with the % the element is in the viewport.

on-exit-viewport (NOTE!!!! THIS ONLY WORKS IN CHROME 51 BECAUSE IT USES INTERSECTION OBSERVERS)

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-exit-viewport', require('simple-custom-attributes/attributes/on-exit-viewport'));

<div on-exit-viewport='someMethod'></div>

inner-html

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('inner-html', require('simple-custom-attributes/attributes/inner-html'));

<div inner-html='someHtmlString'></div>

on-progress (Used for video elements)

var customAttributes = require('simple-custom-attributes');

customAttributes.addAttribute('on-progress', require('simple-custom-attributes/attributes/on-progress'));

<video on-progress='someMethod'>

Let me know how it goes!!!