Backpack.js User Guide

Introduction

Backpack.js is a lightweight Backbone extension for composing and structuring UI components, and was built by a couple of Airbnb Engineers.

Backpack's focus is to be a helper for storing and structuring decoupled, extensible UI components. Think of it as a roll-your-own YUI or jQuery UI, with components built with Backbone.Views. It's a micro-library that you build on as you go.

Your Backpack will come with some common UI components that you can easily extend. As you build out your app, you'll start throwing more components in your backpack. Then you just pull out the components you need when you need them.

This initial release is the result of our work abstracting components that we built for the Airbnb mobile site. We would like to open this initial release to the community to hear your thoughts and welcome contributions and ideas for its future.

Overview

Backpack

Backpack is the global namespace everything gets attached too. Backpack also comes equiped with a ham radio. It extends Backbone.Events, so you have a global dispatcher/observer at your disposal.

Backpack.Component

Component is the base View which all Backpack.js components extend. It provides convenient helper methods for manipulating the component and it’s content, many of which follow a syntax similar to jQuery in that methods can be chained, or alternatively can be passed in upon initialization of the component.

Component provides the following convenience methods to all components:

```
render
```
```
show
```
```
hide
```
```
close
```
```
remove
```
```
before
```
```
after
```
```
append
```
```
prepend
```
```
content
```
```
setContent
```
```
parent
```
```
addClass
```
```
removeClass
```
```
css
```
```
name
```
```
slug
```

Backpack.Tabs

Tabs are a grouping of TabItems, responsible for automatically displaying the content associated with any given tab. Clicking on a TabItem automatically displays the content, and can also be extended to execute any number of given arbitrary functions.

var tabs = new Backpack.Tabs({
      add: [{
        content:    'Tab 1',
        tabContent: 'Some tab 1 content'
      },{
        content:    'Tab 2',
        tabContent: 'Some tab 2 content'
      }]
});

var tabs = new Backpack.Tabs({});

tabs.add({
  content:    'Tab 1',
  tabContent: 'Some tab 1 content'
});

tabs.add({
  content:    'Tab 2',
  tabContent: 'Some tab 2 content'
});

tabs.add({
    content:    'Tab 3',
    tabContent: 'Some tab 3 content'
  },{
    content:    'Tab 4',
    tabContent: 'Some tab 4 content'
});

Menu is a means of displaying many MenuItem objects. A MenuItem can consist of text, or any amount of arbitrary HTML (images, for example). When clicked, a MenuItem is capable of redirecting a user to a simple URL or executing any arbitrary function.

var menu = new Backpack.Menu({
      parent: this, 
      add: [{
          content: 'Menu Item 1',
          events:  '#Menu'
      },{
          content: 'Airbnb',
          events:  'http://airbnb.com'
      },{
          content: 'Menu Item 2',
          events:  function() {
                    return console.log('test');
                   }           
      },{
          content: 'Menu Item 3',
          events:  {
            'click': 
                  function() {
                    console.log('click'); 
                  },

            'mouseenter':
                  function() {
                    console.log('mouseenter');
                  }
          }                       
      }]
});

var menu = new Backpack.Menu({
      parent: this, 
      addClass: 'press',
      add: [{
          content: 'Menu Item 1',
          events:  '#Menu'
      },{
          content: 'Airbnb',
          events:  'http://airbnb.com'
      },{
          content: 'Menu Item 2',
          events:  function() {
                    return console.log('test');
                   }           
      },{
          content: 'Menu Item 3',
          events:  {
            'click': 
                  function() {
                    console.log('click'); 
                  },

            'mouseenter':
                  function() {
                    console.log('mouseenter');
                  }
          }                       
      }]
});

var menu = new Backpack.Menu({
      parent: this, 
      addClass: 'backpack-list',
      add: [{
          content: 'Menu Item 1',
          events:  '#Menu'
      },{
          content: 'Airbnb',
          events:  'http://airbnb.com'
      },{
          content: 'Menu Item 2',
          events:  function() {
                    return console.log('test');
                   }           
      },{
          content: 'Menu Item 3',
          events:  {
            'click': 
                  function() {
                    console.log('click'); 
                  },

            'mouseenter':
                  function() {
                    console.log('mouseenter');
                  }
          }                       
      }]
});

Backpack.Layout

Layout is a simple grid helper for component placement. Set the number of columns and gutter size and Layout will figure out the sizing of everything. No need to worry about class names or calculating widths.

var testComponent = new Backpack.Component({
      name: 'test component',
      css: {
        'background-color': 'lightgrey',
        'padding': '20px'
      }
    });

var basic = new Backpack.Layout({
      add: [{
            content: testComponent
        },{
            content: testComponent
        },{
            content: testComponent
      }]
});

Swipe.js Example Component

It's easy to create components from existing libraries. Here's an example of how to create a Backpack component out of the Swipe.js library.

window.mySwipe = new Backpack.Swipe({
          parent: '.swipe-gallery',
          content: ["<img src='assets/img/swipe/1.jpg'>",
                    "<img src='assets/img/swipe/2.jpg'>",
                    "<img src='assets/img/swipe/3.jpg'>",
                    "<img src='assets/img/swipe/4.jpg'>",
                    "<img src='assets/img/swipe/5.jpg'>"],
          speed: 400,
          continuous: true,
          disableScroll: false,
          callback: function(index, elem) {},
          transitionEnd: function(index, elem) {}
});

class Backpack.Swipe extends Backpack.Component

  id: 'slider'

  config:
    'type': 'swipe'
    'renderType': 'append'
    'startSlide': 0
    'speed': 300
    'auto': 4000
    'continuous': true
    'disableScroll': false
    'callback': ->
    'transitionEnd': ->

  initialize: ->
    super()
    # being lazy and attaching it to window for now
    window.s = new window.Swipe(@el, @options)

  content: (slides) =>
    for content in arguments
        @$el.append(content)
    @

Hack on Backpack

Backpack.js is still in it's early-days. We’re open-sourcing our progress thus far with the hope to continue to build Backpack.js with the help of the Backbone community.

Getting Started

git clone git@github.com:airbnb/backpack.js.git
cd backpack.js && npm install

Cake Build Tools

cake compile        # Compile CoffeeScript source files

cake build          # Creates /lib_path/Backpack-bundle.js & 
                    # /lib_path/Backpack-bundle.min.js & 
                    # /lib_path/js/*.js

cake test           # Opens Jasmine SpecRunner. Watches
                    # BackpackSpec-Bundle.js for changes

cake docs           # Generate annotated source code 
                    # with Docco

cake watch          # Recompile CoffeeScript source files when 
                    # modified to Backpack-bundle.js

cake watch:js       # Recompile CoffeeScript source files when 
                    # modified to individual .js files

Testing

Backpack.js tests are written using jasmine with sinon.js and jasmine-sinon.

You can run the test suite with

cake test

.

Backpack.js

Grab your backpack and enjoy the Views

Backpack.js is a lightweight Backbone extension for composing and structuring UI components