Backbone.Giraffe

Notice

Giraffe is currently in maintenance-only mode. Bugs will be fixed but otherwise development has been halted. If you are interested in becoming the maintainer of the project, please open an issue. We'd be happy to turn the reins over to someone who would like to continue its development!

Introduction

Backbone.Giraffe is a light and flexible library that extends Backbone.js to new heights. Giraffe's goal is to follow the Backbone philosophy of unopinionated simplicity to provide commonly needed features with few assumptions. It differs from other Backbone libraries like Marionette and Chaplin in its reduced scope and size, and it takes a different approach to the problems of route handling, object lifecycles, event aggregation, and view management.

Overview

• Giraffe.View is a nestable and flexible class that provides lifecycle management and many other useful features. It defaults to Underscore templates and easily supports any form of templating.

• Giraffe.App is a special view that helps your views, models, collections, and routers communicate by acting as an event hub. Multiple apps can coexist and teardown is as simple as it gets.

• Giraffe.Router leverages an app's events to trigger routing events that any object can listen for. It also has reverse routes to allow the construction of URLs using app events and arguments.

• Giraffe.Model and Giraffe.Collection are thin wrappers that add Giraffe's lifecycle management and app events. Any object can mix in this functionality via Giraffe.configure.

Documentation

Read the API docs and check out our live examples.

How Giraffe is Different

Giraffe was created by the needs of our team as we built Barc. We tried many existing libraries but some did way too much, others added too many layers, and others performed poorly.

Giraffe does not have all the bells and whistles of the larger frameworks. We found the effort to customize them for our needs was more effort than simply building upon Backbone with a minimalist approach. For example, there is no concept of specialized containers like regions or layouts, as any view in Giraffe can act as a parent of one or more child views. Giraffe also has no CollectionView or ItemView (see Giraffe.Contrib.CollectionView and Giraffe.Contrib.FastCollectionView), but we are open to suggestions to make Giraffe as useful as possible to Backbone developers who want an extension library with few opinions.

Is this framework for you? It depends. We feel Giraffe adds essential features to make you more productive with Backbone.

Highlights

• Routes emit events instead of being tied to functions. This makes it extremely simple for a deeply nested view to act on a route.

• Reverse routes with arguments provide a way to trigger routes in the application using app events without having to know a URL path.

• Giraffe.App is a special view that acts as an event hub to help your app communicate and respond to routes, and all Giraffe objects have convenient appEvents bindings inspired by Backbone.View#events.

• Giraffe.View#attachTo(someElement) allows views to move anywhere on the DOM without clobbering each other's events, and it automatically sets up parent-child relationships for memory management.

• Lifecycle management mitigates memory leaks. It's automatic for nested views and can be used for any object with a dispose method via Giraffe.View#addChild.

• (A)sync app initialization helps an app reach its ready state. For example, an app may need to wait for asynchronous bootstrap data or a websocket connection before starting.

• Declarative event handling in markup provides simple one-way binding. (does not try to be Knockout or AngularJS)

• Optional Giraffe.Contrib extensions include a simple Controller class with Giraffe's lifecycle and appEvents features, a CollectionView that renders a collection with a view per model, and a FastCollectionView that renders a collection with a single view more efficiently than Giraffe.Contrib.CollectionView and Marionette.CollectionView.

Download

Version 0.2.8

backbone.giraffe.js 70.5k

backbone.giraffe.min.js 18.4k

backbone.giraffe.contrib.js 18.3k

backbone.giraffe.contrib.min.js 6.2k

Building

npm install [email protected] -g
npm install -d
pm run all
pm run all -ws # watches for file changes and runs local server at local.projmate.com:1080/dist/

Changelog

0.2.8

• Fixed AMD loader.
• Added Giraffe.noConflict and Giraffe.Contrib.noConflict.
• Contrib now attaches itself as root.GiraffeContrib in addition to the existing Giraffe.Contrib.

0.2.7

• Fixed module loader for r.js optimizer.

0.2.6

• Configured objects (including all Giraffe objects) now have the following no-op function hooks for you to implement: beforeDispose, afterDispose, beforeInitialize, and afterInitialize.

• Disposed objects have a new property _dispose set to true.

0.2.5

• Support optional params for Router#isCaused and Router#cause. Optional static routes remain unsupported. See issue 19 for more.
• Contrib can now be required from the root: require('backbone.giraffe/contrib').
• All invariants now throw errors instead of logging.

0.2.4

• Allow passing routing options to Giraffe.Router#cause.

0.2.3

• Fixed support for 0 as a path param.

0.2.2

• Added Backbone and Underscore CommonJS requires to Giraffe.Contrib.

0.2.1

• Fixed AMD loader check.

0.2.0

• Added support for AMD and node-style loaders.

• Put contributors in one place, the AUTHORS file.

• Using accurate semantic versioning, starting...now.

0.1.5

• Added events around several view methods: rendering, rendered, attaching, attached, detaching, detached

• BREAKING CHANGE: dispose now acts on this instead of taking the target object as an argument. Removed disposeThis as it's now redundant.

• Registered as a Bower package: bower install backbone.giraffe

0.1.4

• Added the function Giraffe.configure which mixes several Giraffe features into any object. Used in the constructors of all Giraffe objects.

• omittedOptions can be used to prevent Giraffe.configure from extending particular properties. If the value is true, all properties are omitted.

• The document event prefix 'data-gf-' is now configurable via Giraffe.View.setDocumentEventPrefix and as a parameter to Giraffe.View.setDocumentEvents and Giraffe.View.removeDocumentEvents.

• BREAKING CHANGE: dispose is now mixed into configured objects with a default function, and is only copied if it doesn't exist. As a result, calls to super in dispose no longer make sense. Use Giraffe.dispose instead.

• beforeDispose, afterDispose, beforeInitialize, and afterInitialize are called if defined on all configured objects. Some are used by Giraffe objects so override with care.

• Added Giraffe.wrapFn which calls 'beforeFnName' and 'afterFnName' versions of a function name on an object. Here's a reference for future development - Backbone.Advice

Contributors

View Giraffe's contributors here or see the file AUTHORS.

Suggestions and pull requests are welcome!

License

Copyright (c) 2013 Barc Inc.

See the file LICENSE for copying permission.