Backbone.View.Elements

Backbone.View extension for convenient work with elements, css classes and selectors. Inspired by i-bem.js

How to avoid CSS selectors duplication and cache elements

It's very common situation when we need to use the same selector in different parts of our view. Considering selectors can be complex it's not a good practice to mention them more than once. Using Backbone.View.Elements you can adjust selectors in one place like this:

_selectors: function () {
	return {
		elemName: '.block__elem-name'
	};
}

then in the code you can get the selector using the _selector method

this._selector('elemName'); // returns '.block__elem-name'

but the more often situation is when you need to retrive an element by the selector

this._elem('elemName'); // returns jQuery collection found by '.block__elem-name'

Furthermore the _elem method caches the results so you need not to save elements to properties of views. Another advantage is when an HTML template is changed you have to change JS in only one place.

How to avoid CSS classes duplication and manipulate them easily

The same situation with CSS selectors - we don't want to duplicate them. Classes are placed inside _classes method:

_classes: function () {
	return {
		className: '.block__elem_some_class'
	};
}

then in the code you can get the class using the _class method

this._class('className'); // returns 'block__elem_some_class'

or selector for the class

this._selector('className'); // returns '.block__elem_some_class'

or elements collection

this._elem('className'); // returns jQuery collection found by '.block__elem_some_class'

But more often we need to do some manipulations with classes like adding a class to an element. The _addClass method exists for this reason

this._addClass('className', 'elemName'); // add the 'block__elem_some_class' to elements found by '.block__elem-name'

See also _removeClass, _hasClass, _toggleClass and some others bellow.

You also can read a tutorial in my blog >>>

Installation
Inclusion
- Using globals
- Using RequireJS
Protected API
- Properties
  - _$window
  - _$document
  - _$body
  - _data
- Methods
  - _classes
  - _class
  - _hasClass
  - _addClass
  - _removeClass
  - _toggleClass
  - _selectors
  - _selector
  - _hasDescribedSelector
  - _elem
  - _findElem
  - _dropElemCache
  - _getElemData

TOC generated with DocToc

Installation

To install latest version just type:

bower install backbone.view.elements --save

If you do not have bower:

npm install -g bower

Inclusion

You have two ways to include the script

Using globals

Add script tag with Backbone.View.Elements right after Backbone like this:

<script src="path/to/backbone.js"></script>
<script src="path/to/Backbone.View.Elements.js"></script>

Inherit your view from Backbone.ElementsView

var MyView = Backbone.ElementsView.extend({
    // yout view prototype here
});

Using AMD loader, for example RequireJS

Add info about jQuery and Backbone locations to the shim

requirejs.config({
    paths: {
        underscore: 'path/to/underscore',
        backbone: 'path/to/backbone',
        jquery: 'path/to/jquery'
    },
    shim: {
        jquery: {
            exports: 'jQuery'
        }
    }
});

If you are using old versions of backbone and underscore, you must declare exports and deps for them:

    shim: {
        jquery: {
            exports: 'jQuery'
        },
        underscore: {
            exports: '_'
        },
        backbone: {
            deps: ['jquery', 'underscore'],
            exports: 'Backbone'
        }
    }

Describe your view depending on Backbone.View.Elements and extend it:

require(['path/to/Backbone.View.Elements'], function (ElementsView) {
    var MyView = ElementsView.extend({
        // your view prototype here
    });
});

Protected API

You can use following properties and methods inside your child classes

Properties

_$window

type {jQuery}

Cached window object wrapped to jQuery/Zepto

_$document

type {jQuery}

Cached document object wrapped to jQuery/Zepto

_$body

type {jQuery}

Cached document.body object wrapped to jQuery/Zepto

_data

type {Object}

Data attributes of this.$el

Methods

_classes

returns {Object.<string>}

Place here CSS classes used in a View. Method should return an object, which keys are readable class names and values are CSS classes. You can extend this method in child classes.

Consider your declaration is:

_classes: function(){
    return {
        activeItem: 'very-long-css-class-for-active-state-for-some-item'
    };
}

Then you can get the class this way:

this._class('activeItem');

or selector for the class

this._selector('activeItem'); // returns dot + the class

or even elements with the class

this._elem('activeItem');

Please note the _elem method caches results, so if you dynamically set the class to different elements use _findElem instead

_class

arguments:
- {String} name Key from _classes
- {...string|object} [placeholders] values for placeholders, see examples
returns {String} CSS class
throws {Error} if the name does not match any key in _classes or value for the key is empty

Returns CSS class by its name. Classes are described in _classes. Suppose we have classes described like this:

_classes: function(){
    return {
        activeItem: 'item_active_yes',
        itemOfType: 'item_type_%s',
        namedItem: 'item-%(name)s'
    };
}

Then in code we can get the class this way:

this._class('activeItem');                  // item_active_yes
this._class('itemOfType', 'apple');         // item_type_apple
this._class('namedItem', {name: 'note'});   // item-note

_hasClass

arguments
- {String|Array.<String>} cls class name, if you want to use placeholders pass the array (see examples)
- {String|Array.<String>|jQuery} [elem=this.$el] element name, checks the root element if not specified
returns {Boolean}

Checks the element has CSS class described in _classes. Example: checking Backbone.View.$el has a class specified in _classes as active

this._hasClass('active')

Checking some child element has a class specified in _classes. For retrieving element the _elem method is used

this._hasClass('active', 'someItem')

Usage with placeholders

this._hasClass(['namedItem', 'itsName'], 'elemName')

_addClass

arguments:
- {String|Array.<String>} cls class name, if you want to use placeholders pass the array (see examples)
- {String|Array.<String>|jQuery} [elem=this.$el] element name, adds to the root element if not specified
returns {jQuery}

Add CSS class described in _classes to element. For example if we want to add the class specified in _classes as active to Backbone.View.$el:

this._addClass('active')

Adding a class specified in _classes to some child element. For retrieving element the _elem method is used

this._addClass('active', 'someItem')

Usage with placeholders

this._addClass(['namedItem', 'itsName'], 'elemName')

_removeClass

arguments:
- {String|Array.<String>} cls class name, if you want to use placeholders pass the array (see examples)
- {String|Array.<String>|jQuery} [elem=this.$el] element name, removes from the root element if not specified
returns {jQuery}

Remove CSS class described in _classes from an element. To remove class from from the Backbone.View.$el

this._removeClass('active')

Removing a class specified in _classes from some child element. For retrieving an element the _elem method is used

this._removeClass('active', 'someItem')

Usage with placeholders

this._removeClass(['namedItem', 'itsName'], 'elemName')

_toggleClass

arguments:
- {String|Array.<String>} cls class name, if you want to use placeholders pass the array (see examples)
- {String|Array.<String>|jQuery} [elem=this.$el] element name, toggles to the root element if not specified
- {Boolean} [toggle] flag to add or remove the class
returns {jQuery}

Toggles CSS class described in _classes on element. Example: toggling a class specified in _classes as active on Backbone.View.$el

this._toggleClass('active', true);

Toggling a class specified in _classes on some child element. For retrieving element the _elem method is used

this._toggleClass('active', 'someItem', false)

Usage with placeholders

this._toggleClass(['namedItem', 'itsName'], 'elemName', true)

_selectors

returns {Object.<string>}

Place here selectors used in a View. Method should return an object, which keys are readable selector names and values are CSS selector. You can extend this method in child classes.

Routine use:

_selectors: function(){
    return {
        firstLevelItem: '.list>.item'
    };
}

Then you can get the selector this way:

this._selector('firstLevelItem')

or elements selected by it

this._elem('firstLevelItem')

Using with placeholders

_selectors: function(){
    return {
        itemById: '.item[data-id=%s]',
        namedItem: '.item-%(name)s'
    };
}

then in code

this._selector('itemById', 3);           // .item[data-id=3]
this._elem('namedItem', {name: 'note'}); // finds child elements by .item-note selector

_selector

arguments:
- {string} name Key from _selectors
- {...string|object} [placeholders] values for placeholders, see examples
returns {String} CSS selector
throws {Error} if the name does not match any key in _selectors and _classes

Returns CSS selector by its name. Selectors are described in _selectors

Example: suppose we have selectors described like this:

_selectors: function(){
    return {
        firstLevelItem: '.list>.item',
        itemById: '.item[data-id=%s]',
        namedItem: '.item-%(name)s'
    };
}

Then in code we can get the class this way:

this._selector('firstLevelItem')             // .list>.item
this._selector('itemById', 'apple')          // .item[data-id=apple]
this._selector('namedItem', {name: 'note'})  // .item-note

Using at Backbone.View#events

events: function(){
    var events = {};
    events['click ' + this._selector('firstLevelItem')] = this._onItemClick;
    return events;
}

_hasDescribedSelector

arguments:
- {String} name Selector name
returns {Boolean}

Returns true if selector with the name is descried in _classes or _selectors

_elem

arguments:
- {string} name The name of searching element
- {...string|object} [placeholders] values for placeholders, see examples
returns {jQuery}

Returns jQuery or Zepto collection of elements by the name described in _selectors or _classes. Caches th results so you don't need to remember them to properties. Use _dropElemCache to clean caches

var Page = ElementsView.extend({
    _classes: function () {
        return {
            popup: 'my-class-for-popups'
        };
    },

    _selectors: function () {
        return {
            popupByName: '.popup[data-name=%s]'
        };
    },
    
    initialize: function () {
        ElementsView.prototype.initialize.apply(this, arguments);

        this._elem('popupByName', 'greeting').show();
        var $allPopups = this._elem('popup');
    }
});

_findElem

arguments:
- {string} name
- {...string|object} [placeholders]
returns {jQuery}

Finds element without using cache

var SomeElement = ElementsView.extend({
    _classes: function () {
        return {
            activeDropdown: 'dropdown_active'
        };
    },

    _selectors: function () {
        return {
            dropdownByN: '.dropdown:eq(%s)'
        };
    },

    initialize: function () {
        ElementsView.prototype.initialize.apply(this, arguments);

        this._addClass('activeDropdown', ['dropdownByN', 2]);
        var $activeDropdown = this._elem('activeDropdown'); // caches activeDropdown
        this._removeClass('activeDropdown', ['dropdownByN', 2]);
        this._addClass('activeDropdown', ['dropdownByN', 3]);
        // how to get active dropdown? _elem returns dropdown with number 2 because of the cache
        $activeDropdown = this._findElem('activeDropdown'); // ignores the caches
    }
});

_dropElemCache

arguments:
- {String} [name] The name of the element whose cache will be cleaned up. If it's absent the whole cache will be dropped

Clears the cache for ElementsView._elem

_getElemData

arguments:
- {String} name The name of the searching element
- {String} [attr] The attribute name, if it's absent all attributes will be returned as object
returns {*|Object}

Returns the data attribute value by the name of element described in _selectors or _classes and the name of attribute itself. If you need data attributes of the root element just use the _data property

MrBackKom/backbone.view.elements

Backbone.View.Elements

How to avoid CSS selectors duplication and cache elements

How to avoid CSS classes duplication and manipulate them easily

You also can read a tutorial in my blog >>>

Table of Contents

Installation

Inclusion

Using globals

Using AMD loader, for example RequireJS

Protected API

Properties

_$window

_$document

_$body

_data

Methods

_classes

_class

_hasClass

_addClass

_removeClass

_toggleClass

_selectors

_selector

_hasDescribedSelector

_elem

_findElem

_dropElemCache

_getElemData