backbone-kinview

    1.0.2 • Public • Published

    KinView

    KinView is a Backbone.js view that provides a simple api to manage child views and auto-appends them to the parent $el. It also allows for the child element to have a state attached to it, and properly removes the children when the parent is remove()ed.

    Installation

    KinView has been designed to require'd by browserify, and is currently only supported in that environment. To install:

    npm install backbone-kinview --save
    

    Code

    CI

    KinView continuous integrations is handled by Wercker:

    wercker status

    Testing

    KinView proudly maintains 100% test coverage. To manually run the tests, install with with --dev (as above) and run:

    gulp testc
    

    You can optionally generate an HTML code coverage report by appending the --html argument

    Issues

    Issues can be opened in the usual location, pull requests welcome!

    Usage

    Getting started

    Start by creating a new KinView:

    var KinView = require('backbone-kinview')
     
    var kin = new KinView.extend({
        // regular Backbone.View opts here
    })

    You can now add one or more child view, which all be appended to the parent:

    // must always pass a 'view' param with a valid view!
    kin.add({view: new Backbone.View()})

    Positioning children in the parent

    Sometimes you may wish to add a child element to the parent view at a specific position. With KinView thats easy to do:

    kin.add(
        {view: new Backbone.View()},
        {
            at: 4,           // specify the position (zero index)
            positioned: true // tells KinView that you want the element at the `at` position
        }
    )

    Once set, a child cannot be repositioned.

    Positioning a child in a subelement

    Add a view directly to the parent is useful when children view are the only element in the parent, like this:

    <div class="parent">
        <div class="child"></div>
        <div class="child"></div>
        <div class="child"></div>
    </div>

    If the parent view has a template or an otherwise compartmentalized hierarchy, you can specify where in the parent a given child should be appended to, use the to option. Pass a selector string thats relative to the parent. to delegates to Backbone's view.$(selector) method:

    var KinView = require('backbone-kinview')
     
    var kin = new KinView.extend({
        template: _.template('<div class="parent">'
            + '<div class="child1"></div>'
            + '<div class="child2"></div>'
            + '</div>'),
        initialize: function() {
            this.render()
        },
        render: function() {
            this.$el.html(this.template())
     
            // add child1
            this.add(
                {view: new Backbone.View()}
                {to: '.child1'}
            )
     
            // add child2
            this.add(
                {view: new Backbone.View()}
                {to: '.child2'}
            )
        }
    })

    State

    Setting state

    KinView can keep track of a view's state.

    State doesn't directly affect the view - it's simply 'metadata' that can be used to store what the state should be. Your view must listen to changes on the model in order to know when the state changes. This is a bit unconventional, as you need to first create a view, then create a new child, passing it the view, and finally have the view listen to its model. See below for an example.

    Adding a view with a given state is simple:

    kin.add({view: new Backbone.View(), state: 'someState'})

    To change a state, simply find the views model and set it's state:

    kin.children.at(6).set('state', 'someState')

    Exclusivity

    KinView also offers state exclusivity. When a KinView has state exclusivity, only one child view can hold a given state an any given time. When a child's state is changed, all other children will have their state set to a default value. By default, state is binary (i.e. either true or false). To get more elaborate states, overwrite the Model used by the KinView.children collection, mainly the toggleState() method.

    To activate exclusivity, when instantiate KinView set exclusiveState to true:

    var kin = new KinView.extend({
        exclusiveState: true
    })

    When exclusiveState is true, KinView will listen for an event (or events) and will call the toggleValue() method on the child. While this event defaults to click, it can be set to anything that jQuery.on() can accept. I.e:

    var kin = new KinView.extend({
        exclusiveState: true,
        exclusiveEvent: 'mouseover' // by default, is 'click'
    })

    Updating the view when state changes

    As explained above, the view is never manipulated when its model changes. You must manually listen for changes on the model and update your view appropriately. This is a bit unconventional as the model cannot be directly passed to view. Here is an example of how to have the view listening to the model:

    var model = kin.add({view: Backbone.View()})
    var view  = model.get('view')
    view.listenTo(model, 'change:state', view.changeHandler)

    Lifecycle

    KinView will automatically remove all views, calling their remove() method, when it is removed. If you have any elaborate cleanup you need to do in your children, be sure to add that the child's remove(). To remove KinView, just call remove():

    kin.remove()

    Install

    npm i backbone-kinview

    DownloadsWeekly Downloads

    559

    Version

    1.0.2

    License

    ISC

    Last publish

    Collaborators

    • avatar