Backbone UI

↓ Compressed (11kb) ↓ Source (90kb)

Overview

Backbone UI provides a simple way to represent your Backbone Models and Collections as UI components. The need to shuffle data in and out of your UI is replaced with simple data binding techniques. All components are skinnable with CSS, and will render consistently accross browsers. The source is hosted on github with an MIT license.

Philosophy

This framework is written to embrace the DOM rather than fight it. You won't see any messy HTML templates or innerHTML references hanging around. What you will see is heavy use of the Laconic library to help ease the pain of DOM manipluation so we can happily stay in the context of writing JavaScript.

Not all people will agree with this philosophy, and not all projects will benefit from embracing it. This framework facilitates the creation of highly dynamic front-end clients that request only data from the back-end, not markup. If you have a more traditional application in which your markup is generated before your JavaScript executes, you may still find this framework useful, but keep in mind that it was not designed for such a case.

Another major theme you'll encounter is the concept of data binding. This means that you tell your component which property of the model it's responsible for rendering, and then you forget about shuffling data back and forth. If the model's value changes, the component will re-render. If the user changes the value, the model will be updated. Easy.

Dependencies

Backbone UI depends on Backbone, jQuery (or Zepto), and Laconic. If you'd like to use the calendar or date picker components, than you'll also need a copy of moment.js.

Components

All components inherit from Backbone.View, and each render method will return a reference to the view itself. Feel free to pass any standard Backbone View option when creating these components. As a convenience, the underscored version of the component's class name will be added to each component's element.

Components can be broken down into four categories:

The following data will be used throughout the examples:

Model-Bound

Model-Bound components are those that interact directly with one property of a single model.

Options

Button

Options

  • disabled
    true will disable the button (muted non-clickable)
  • active
    true will activate the button (depressed and non-clickable)
  • onClick
    A callback to invoke when the button is clicked
  • isSubmit
    renders this button as an input type=submit element as opposed to an anchor.

Calendar

Options

  • weekStart
    the week's start day (0 = Sunday, 1 = Monday, etc.)
  • onSelect
    a callback to invoke when a new date selection is made. The selected date will be passed in as the first argument
  • date
    the selected calendar date

Checkbox

Options

  • disabled
    enables / disables the checkbox
  • labelContent
    The property of the model describing the label that should be placed next to the checkbox

Date Picker

Options

  • format
    a moment.js format : http://momentjs.com/docs/#/display/format

Text Area

Options

  • disabled
    disables the text area
  • textAreaId
    id to use on the actual textArea

Text Field

Options

  • type
    The type of input (text, password, number, email, etc.)
  • disabled
    disables the input text
  • onKeyPress
    a callback to invoke when a key is pressed within the text field
  • tabIndex
    the tab index to set on the underlying input field
  • name
    the value to use for both the name and id attribute of the underlying input element
  • maxLength
    if given, the text field will limit it's character count

Time Picker

Options

  • interval
    minute interval to use for pulldown menu
  • disabled
    text field is disabled or enabled
  • format
    a moment.js format : http://momentjs.com/docs/#/display/format
  • name
    the name given to the text field's input element

Model-Bound with Alternatives

These components are similar to regular Model-Bound components, but also include a bound collection of alternatives. The model and property options are still used to define the selected value, and following additional options describe the collection of alternatives:

Options

Pulldown

Options

  • placeholder
    text to place in the pulldown button before a selection has been made
  • onChange
    A callback to invoke with a particular item when that item is selected from the pulldown menu.
  • emptyItem
    an additional item to render at the top of the menu to denote the lack of a selection
  • alignRight
    If true, the menu will be aligned to the right side
  • onMenuShow
    A callback to invoke when the pulldown menu is shown, passing the button click event.
  • onMenuHide
    A callback to invoke when the pulldown menu is hidden, if the menu was hidden as a result of a second click on the pulldown button, the button click event will be passed.

Radio Group

Options

  • onChange
    A callback to invoke with the selected item whenever the selection changes

Collection-Bound

These components are bound to a Backbone.Collection as opposed to a Model. The rendering of a particular item in the collection is defined by the given itemView implementation.

Options

List View

Options

  • itemView
    A Backbone.View implementation describing how to render a particular item in the collection. For simple use cases, you can pass a String instead which will be interpreted as the property of the model to display.

Table View

Table Views are similar to List Views, but allow you to pass a small amount of table meta-data as opposed to writing your own itemView implementation.

Options

  • onSort
    A callback to invoke when the table is to be sorted. The callback will be passed the column on which to sort.
  • emptyContent
    A string, element, or function describing what should be displayed when the table is empty.
  • onItemClick
    A callback to invoke when a row is clicked. If this callback is present, the rows will highlight on hover.
  • columns
    Each column should contain a title property to describe the column's heading, a content property to declare which property the cell is bound to, an optional two-argument comparator with which to sort each column if the table is sortable, and an optional width property to declare the width of the column in pixels.
  • sortable
    Clicking on the column headers will sort the table. See comparator property description on columns. The table is sorted by the first column by default.

Non-Bound

The following components are not meant to be bound to a model or collection, and exist as general-purpose UI elements.

Scroller

Options

  • scrollAmount
    The amount to scroll on each wheel click
  • onScroll
    A callback to invoke when scrolling occurs
  • content
    The content to be scrolled. This element should be of a fixed height.

Tab Set

Options

  • selectedTab
    The index of the tab to initially select
  • alternatives
    Tabs to initially add to this tab set. Each entry may contain a label, content, and onActivate option.

UI Skinning

Skinning of UI components should be done using CSS and image resources. The default skin is fully functional without any image resources, however; this documentation uses an example skin as a reference for building your own. The following will enable this skin: 

Backbone.UI.setSkin('perka');

Browser Support

Backbone UI has been tested on most modern browsers, as well as IE8+. If you're using the HTML 5 Doctype, you may need to use the following meta tag to force IE into standards mode: 

<meta http-equiv="X-UA-Compatible" value="IE=edge" />

Example Application

What would a framework be these days without an example task list application.

The entirety of this application is listed below: