Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A powerful, extendible list component for Backbone.js applications
JavaScript
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
src
test
.gitignore
.travis.yml
README.md
backbone-list.min.js
grunt.js
package.json

README.md

Build Status

backbone-list

A powerful, extendible list component for Backbone.js applications. (View demo)

  • Extendable
  • Lightweight (4.8KB gzipped)
  • LESS themes
  • Data persitence
  • Modular (Require.js)
  • Unit tested
  • Built for Backbone 1.0

Usage

Aside from Backbone and it's associated dependecies - Backbone-List requires the Handlebars templating library.

Backbone-List is built with almond, a mini script loader. Include the minified script file backbone-list.min.js in your page and require needed components.

As a minium you will need a List model and a ListView view. When instantiating the view, pass the model as a parameter to bind it to the view. You can then begin adding nodes to the list.

require([
    "list/model/List",
    "list/view/ListView"
], function (List, ListView) {
    var model = new List();
    var view = new ListView({ model: model });
});

Adding nodes

You can add Composite models or Leaf models to your main model. If you add a Composite model, you may add leaves and composites to it - building up a composite hierarchy.

var composite = new Composite({ title: "Pictures" });
composite.add(new Leaf({ title: "Safari.jpg" }));
composite.add(new Composite({ title: Holiday Album }));

model.add(composite);

Rendering

You will only need to render the ListView instance once. This will generate the views el so that you can insert it into the DOM.

$("#list-container").html(view.render().el);

Model Attributes

The following attributes can be set on models.

  • title: The nodes name.
  • onClick: A function to be executed when a node is clicked. Passed the model of the clicked item as a parameter.
  • visible: A boolean denoting whether to collapse or show the node. Only applicable to composites. Default is false.
  • editable: A boolean denoting whether the node can be edited. Default is false.
  • icon: A string representing a Glyphicon icon class.

Events

All model events are piped through a dispatcher which makes it easy to listen to model changes in one place. Require list/Dispatcher.

Dispatcher.on("change:visible", function (model) {
    console.log("A node has been: " + (model.get("visible") ? "expanded" : "collapsed"));
});

Aside from the standard set of Backbone events, you may also listen to the following.

  • clicked: Denotes that the node was clicked. Passed the corresponding model.
  • search: Denotes that a search was performed. Passed an array of matched models.

Serializing For Storage

Call toJSON() on any model to generate a JSON representation. Use the deserialize() method on the List model to rehydrate a new list.

// Fetch some data over XHR and populate the list
$.getJSON("example-data.json", function (data) {
    model.deserialize(data);
    $("#container").append(view.render().el);
});

The generated JSON is an array of top level nodes. Composite items may have a children property which should contain an array of nodes.

[
    {
        "model": "Composite",
        "parameters": {
            "visible": true,
            "title": "Music"
        },
        "children": []
    }
]

Options

You may pass the following properties when instantiating the main ListView.

  • search: Boolean denoting whether to display a search field. Default is false.
  • animate: Boolean denoting whether use animations when expanding and collapsing. Default is false.
var view = new ListView({
    model: model,
    search: true,
    animate: true
});

Themeing

Themes are written in LESS and can be compiled to CSS. The src/style directory lists the default themes. Create a new theme by duplicating one of these directories and modify the LESS files accordingly.

Building

The following command runs the tests and builds the minified source.

$ npm install -d && node -e "require('grunt').cli();"
Something went wrong with that request. Please try again.