Skip to content
A powerful, extendible list component for Backbone.js applications
JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit 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();"
You can’t perform that action at this time.