Skip to content
Newer
Older
100644 594 lines (437 sloc) 17.9 KB
b573c7a @derickbailey Update readme.md
authored
1 Make your Backbone.js apps dance with a composite application architecture!
2730e21 @derickbailey initial repository with jasmine structure, readme and license in place
authored
2
3 ## Backbone.Marionette
4
5 Backbone.Marionette is a composite application libarary for Backbone.js that
6 aims to simplify the construction of large scale JavaScript application through
7 common design and implementation patterns found in composite application
8 architectures, such as Microsoft's "Prism" framework.
9
10 Unlike other composite application frameworks, Backbone.Marionette is designed
11 to be a lightweigt and flexible library of tools that you can use when you want
12 to. Like Backbone.js itself, you're not required to use all of
13 Backbone.Marionette just because you want to use some of it.
14
4305c2a @derickbailey added jQuery to the module definition
authored
15 ## Download And Annotated Source Code
16
17 You can download the raw source code above. For the development version, grab
18 "backbone.marionette.js". For the production version, grab
19 "backbone.marionette.min.js".
2cf4c8e @derickbailey runtime and test suite requirements
authored
20
a0088fc @derickbailey adding better documentation for the core of the project
authored
21 For a good time, call.. err... read through [the annotated source code](http://derickbailey.github.com/backbone.marionette/docs/backbone.marionette.html).
2cf4c8e @derickbailey runtime and test suite requirements
authored
22
a0088fc @derickbailey adding better documentation for the core of the project
authored
23 ## Marionette's Pieces
2cf4c8e @derickbailey runtime and test suite requirements
authored
24
a0088fc @derickbailey adding better documentation for the core of the project
authored
25 There are only a few pieces to the marionette at this point:
26
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
27 * **Backbone.Marionette.Application**: An application object that starts your app via initializers, and more
28 * **Backbone.Marionette.ItemView**: A view that renders a single item
29 * **Backbone.Marionette.CollectionView**: A view that iterates over a collection, and renders individual `ItemView` instances for each model
a0088fc @derickbailey adding better documentation for the core of the project
authored
30 * **Backbone.Marionette.RegionManager**: Manage visual regions of your application, including display and removal of content
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
31 * **Backbone.Marionette.BindTo**: An event binding manager, to facilitate binding and unbinding of events
32 * **Application.vent**: Every instance of `Application` comes with a `.vent` property, an event aggregator
a0088fc @derickbailey adding better documentation for the core of the project
authored
33
1ab7bff @derickbailey minor update to docs regarding extend
authored
34 The `Application`, `RegionManager`, `ItemView` and `CollectionView` use the
35 `extend` syntax and functionality from Backbone, allowing you to define new
36 versions of these objects with custom behavior.
a0088fc @derickbailey adding better documentation for the core of the project
authored
37
a47cc55 @derickbailey adjusting documentation to be one level less in hierarchy, and move t…
authored
38 ## Marionette.Application
f83e47e @derickbailey tweaking the opening text of the 'building an app' documentation
authored
39
40 The `Backbone.Marionette.Application` object is the hub of your composite
41 application. It organizes, initializes and coordinate the various pieces of your
42 app. It also provides a starting point for you to call into, from your HTML
43 script block or from your JavaScript files directly if you prefer to go that
44 route.
a0088fc @derickbailey adding better documentation for the core of the project
authored
45
46 The `Application` is meant to be instantiate directly, although you can extend
47 it to add your own functionality.
48
58e22ca @nono Add syntax highlighting for examples in the README
nono authored
49 ```js
a0088fc @derickbailey adding better documentation for the core of the project
authored
50 MyApp = new Backbone.Marionette.Application();
58e22ca @nono Add syntax highlighting for examples in the README
nono authored
51 ```
a0088fc @derickbailey adding better documentation for the core of the project
authored
52
a47cc55 @derickbailey adjusting documentation to be one level less in hierarchy, and move t…
authored
53 ### Adding Initializers
54
55 Your application needs to do useful things, like displaying content in your
56 regions, starting up your routers, and more. To accomplish these tasks and
57 ensure that your `Application` is fully configured, you can add initializer
58 callbacks to the application.
59
60 ```js
61 MyApp.addInitializer(function(options){
62 // do useful stuff here
63 var myView = new MyView({
64 model: options.someModel
65 });
66 MyApp.mainRegion.show(myView);
67 });
68
69 MyApp.addInitializer(function(options){
70 new MyAppRouter();
71 Backbone.history.start();
72 });
73 ```
74
75 These callbacks will be executed when you start your application. The `options`
76 parameters is passed through the `start` method (see below).
77
78 ### Application Events
79
80 The `Application` object raises a few events during its lifecycle. These events
81 can be used to do additional processing of your application. For example, you
82 may want to pre-process some data just before initialization happens. Or you may
83 want to wait until your entire application is initialized to start the
84 `Backbone.history`.
85
86 The two events that are currently triggered, are:
87
88 * **"initialize:before"**: fired just before the initializers kick off
89 * **"initialize:after"**: fires just after the initializers have finished
90
91 ```js
92 MyApp.bind("initialize:before", function(options){
93 options.moreData = "Yo dawg, I heard you like options so I put some options in your options!"
94 });
95
96 MyApp.bind("initialize:after", function(options){
97 if (Backbone.history){
98 Backbone.history.start();
99 }
100 });
101 ```
102
103 The `options` parameter is passed through the `start` method of the application
104 object (see below).
105
2f07aa1 @derickbailey reordering the Application docs section
authored
106 ### Starting An Application
107
108 Once you have your application configured, you can kick everything off by
109 calling: `MyApp.start(options)`.
110
111 This function takes a single optional parameter. This parameter will be passed
112 to each of your initializer functions, as well as the initialize events. This
113 allows you to provide extra configuration for various parts of your app, at
114 initialization/start of the app, instead of just at definition.
115
116 ```js
117 var options = {
118 something: "some value",
119 another: "#some-selector"
120 };
121
122 MyApp.start(options);
123 ```
124
a47cc55 @derickbailey adjusting documentation to be one level less in hierarchy, and move t…
authored
125 ### Event Aggregator
126
127 An event aggregator is an application level pub/sub mechanism that allows various
128 pieces of an otherwise segmented and disconnected system to communicate with
129 each other. Backbone.Marionette provides an event aggregator with each
130 application instance: `MyApp.vent`.
131
132 You can use this event aggregator to communicate between various modules of your
133 application, ensuring correct decoupling while also facilitating functionality
134 that needs more than one of your application's modules.
135
136 ```js
137 (function(MyApp){
138
139 MyApp.vent.bind("some:event", function(){
140 alert("Some event was fired!!!!");
141 });
142
143 })(MyApp);
144
145 MyApp.vent.trigger("some:event");
146 ```
147
148 For a more detailed discussion and example of using an event aggregator with
149 Backbone applications, see the blog post: [References, Routing, and The Event
150 Aggregator: Coordinating Views In Backbone.js](http://lostechies.com/derickbailey/2011/07/19/references-routing-and-the-event-aggregator-coordinating-views-in-backbone-js/)
151
152 ## Marionette.RegionManager
153
154 Regions can be added to the application by calling the `addRegions` method on
155 your application instance. This method expects a single hash parameter, with
156 named regions and either jQuery selectors or `RegionManager` objects. You may
157 call this method as many times as you like, and it will continue adding regions
158 to the app. If you specify the same name twice, last one in wins.
159
160 ```js
161 MyApp.addRegions({
162 mainRegion: "#main-content",
163 navigationRegion: "#navigation"
164 });
165
166 var FooterRegion = Backbone.Marionette.RegionManager.extend({
167 el: "#footer"
168 });
169
170 MyApp.addRegions({footerRegion: FooterRegion});
171 ```
172
173 Note that if you define your own `RegionManager` object, you must provide an
174 `el` for it. If you don't, you will receive an runtime exception saying that
175 an `el` is required.
176
177 Additionally, when you pass a `RegionManager` directly into to the `addRegions`
178 method, you must specify the constructor function for your region manager, not
179 an instance of it.
180
fa9d1cf @derickbailey document tweaks
authored
181 ## Marionette.ItemView
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
182
183 An `ItemView` is a view that represents a single item. That item may be a
184 `Backbone.Model` or may be a `Backbone.Collection`. Whichever it is, though, it
cc914fe @derickbailey more docs for ItemView
authored
185 will be treated as a single item.
186
7b2f816 @derickbailey reducing documentation hierarchy again
authored
187 ### ItemView render
cc914fe @derickbailey more docs for ItemView
authored
188
189 An item view has a `render` method built in to it. By default it uses
190 underscore.js templates.
191
192 The default implementation will use a template that you specify (see
193 below) and serialize the model or collection for you (see below).
194
195 You can provide a custom implementation of a method called
196 `renderTemplate` to change template engines. For example, if you want
197 to use jQuery templates, you can do this:
198
199 ```js
200 Backbone.Marionette.ItemView.extend({
201 renderTemplate: function(template, data){
b748a28 @derickbailey fixed the renderTemplate and getTemplate methods
authored
202 return template.tmpl(data);
cc914fe @derickbailey more docs for ItemView
authored
203 }
204 });
205 ```
206
b748a28 @derickbailey fixed the renderTemplate and getTemplate methods
authored
207 The `template` parameter is a jQuery object with the contents of the
208 template that was specified in the view (see below).
cc914fe @derickbailey more docs for ItemView
authored
209
210 The `data` parameter is the serialized data for either the model or
211 the collection of the view (see below).
212
213 After the view has been rendered, a `onRender` method will be called.
214 You can implement this in your view to provide custom code for dealing
215 with the view's `el` after it has been rendered:
216
217 ```js
218 Backbone.Marionette.ItemView.extend({
219 onRender: function(){
220 // manipulate the `el` here. it's already
221 // been rendered, and is full of the view's
222 // HTML, ready to go.
223 }
224 });
225 ```
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
226
7b2f816 @derickbailey reducing documentation hierarchy again
authored
227 ### ItemView template
4e12227 @derickbailey working on documentation for ItemView
authored
228
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
229 Item views should be configured with a template. The `template` attribute should
230 be either a valid jQuery selector, or a function that returns a valid jQuery
231 selector:
232
233 ```js
234 MyView = Backbone.Marionette.ItemView.extend({
235 template: "#some-template"
236 });
237
238 AnotherView = Backbone.Marionette.ItemView.extend({
239 template: function(){
240 return $("#some-template")
241 }
242 });
4e12227 @derickbailey working on documentation for ItemView
authored
243
244 new SomeItemView({
245 template: "#some-template"
246 });
247 ```
248
7b2f816 @derickbailey reducing documentation hierarchy again
authored
249 ### ItemView serializeData
4e12227 @derickbailey working on documentation for ItemView
authored
250
251 Item views will serialize a model or collection, by default, by
252 calling `.toJSON` on either the model or collection. If both a model
253 and collection are attached to an item view, the model will be used
254 as the data source. The results of the data serialization will be passed to the template
255 that is rendered.
256
257 If the serialization is a model, the results are passed in directly:
258
259 ```js
260 var myModel = new MyModel({foo: "bar"});
261
262 new MyItemView({
263 template: "#myItemTemplate",
264 model: myModel
265 });
266
267 MyItemView.render();
268 ```
269
270 ```html
271 <script id="myItemTemplate" type="template">
272 Foo is: <%= foo %>
273 </script>
274 ```
275
276 If the serialization is a collection, the results are passed in as an
277 `items` array:
278
279 ```js
280 var myCollection = new MyCollection([{foo: "bar"}, {foo: "baz"}]);
281
282 new MyItemView({
283 template: "#myCollectionTemplate",
284 collection: myCollection
285 });
286
287 MyItemView.render();
288 ```
289
290 ```html
291 <script id="myCollectionTemplate" type="template">
292 <% _.each(items, function(item){ %>
293 Foo is: <%= foo %>
294 <% }); %>
295 </script>
296 ```
297
298 If you need custom serialization for your data, you can provide a
299 `serializeData` method on your view. It must return a valid JSON
300 object, as if you had called `.toJSON` on a model or collection.
301
302 ```js
303 Backbone.Marionette.ItemView.extend({
304 serializeData: function(){
305 return {
306 "some attribute": "some value"
307 }
308 }
309 });
310 ```
311
7b2f816 @derickbailey reducing documentation hierarchy again
authored
312 ### ItemView events
4e12227 @derickbailey working on documentation for ItemView
authored
313
314 ItemView extends `Marionette.BindTo`. It is recommended that you use
315 the `bindTo` method to bind model and collection events.
316
317 ```js
318 MyView = Backbone.Marionette.ItemView.extend({
319 initialize: function(){
320 this.bindTo(this.model, "change:foo", this.modelChanged);
321 this.bindTo(this.collection, "add", this.modelAdded);
322 },
323
324 modelChanged: function(model, value){
325 },
326
327 modelAdded: function(model){
328 }
329 });
330 ```
331
332 The context (`this`) will automatically be set to the view. You can
333 optionally set the context by passing in the context object as the
334 4th parameter of `bindTo`.
335
7b2f816 @derickbailey reducing documentation hierarchy again
authored
336 ### ItemView close
4e12227 @derickbailey working on documentation for ItemView
authored
337
338 ItemView implements a `close` method, which is called by the region
339 managers automatically. As part of the implementation, the following
340 are performed:
341
342 * unbind all `bindTo` events
343 * unbind all custom view events
344 * unbind all DOM events
345 * remove `this.el` from teh DOM
346 * call an `onClose` event on the view, if one is provided
347
348 By providing an `onClose` event in your view definition, you can
349 run custom code for your view that is fired after your view has been
350 closed and cleaned up. This lets you handle any additional clean up
351 code without having to override the `close` method.
352
353 ```js
354 Backbone.Marionette.ItemView.extend({
355 onClose: function(){
356 // custom cleanup or closing code, here
357 }
358 });
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
359 ```
360
b8aab04 @derickbailey docs for first bits of collection view
authored
361 ## Marionette.CollectionView
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
362
b8aab04 @derickbailey docs for first bits of collection view
authored
363 The `CollectionView` will loop through all of the models in the
364 specified collection, render each of them using a specified `itemView`,
365 then append the results of the item view's `el` to the collection view's
366 `el`.
367
368 ### CollectionView's itemView
369
370 Specify an `itemView` in your collection view definition. This must be
371 a Backbone view object definition (not instance). It can be any
372 `Backbone.View` or be derived from `Marionette.ItemView`.
373
374 ```js
375 MyItemView = Backbone.Marionette.ItemView.extend({});
376
377 Backbone.Marionette.CollectionView.extend({
378 itemView: MyItemView
379 });
380 ```
381
382 ### CollectionView's appendHtml
383
384 By default the collection view will call jQuery's `.append` to
385 move the HTML contents from the item view instance in to the collection
386 view's `el`.
387
388 You can override this by specifying an `appendHtml` method in your
389 view definition. This method takes two parameters and has no return
390 value.
391
392 Parameter `el`: the collection view's `el`, as a jQuery selector
393 object.
394
395 Parameter `html`: the HTML contents that were generated by the
396 item view.
397
398 ```js
399 Backbone.Marionette.CollectionView.extend({
400 appendHtml: function(el, html){
401 el.prepend(html);
402 }
403 });
404 ```
4e12227 @derickbailey working on documentation for ItemView
authored
405
f88b330 @derickbailey adding a close to the collection view, having it close all children. …
authored
406 ### CollectionView close
407
408 CollectionView implements a `close` method, which is called by the
409 region managers automatically. As part of the implementation, the
410 following are performed:
411
412 * unbind all `bindTo` events
413 * unbind all custom view events
414 * unbind all DOM events
415 * unbind all item views that were rendered
416 * remove `this.el` from teh DOM
417 * call an `onClose` event on the view, if one is provided
418
419 By providing an `onClose` event in your view definition, you can
420 run custom code for your view that is fired after your view has been
421 closed and cleaned up. This lets you handle any additional clean up
422 code without having to override the `close` method.
423
424 ```js
425 Backbone.Marionette.CollectionView.extend({
426 onClose: function(){
427 // custom cleanup or closing code, here
428 }
429 });
430 ```
431
fa9d1cf @derickbailey document tweaks
authored
432 ## Marionette.BindTo
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
433
434 The `BindTo` object provides event binding management and facilitates simple
435 event binding and unbinding for any object that extends from `Backbone.Events`.
436
437 Bind an event:
438
439 ```js
440 var binder = _.extend({}, Backbone.Marionette.BindTo);
441
442 var model = new MyModel();
443
444 var handler = {
445 doIt: function(){}
446 }
447 binder.bind(model, "change:foo", handler.doIt);
448 ```
449
2ccd695 @derickbailey better docs for BindTo
authored
450 You can optionally specify a 4th parameter as the context in which the callback
451 method for the event will be executed:
452
453 ```js
454 binder.bind(model, "change:foo", someCallback, someContext);
455 ```
456
457 You can call `unbindAll` to unbind all events that were bound with the
458 `bindTo` method:
9592ca0 @derickbailey starting to work on documentation for item view and bindto
authored
459
460 ```js
461 binder.unbindAll();
462 ```
463
816a657 @derickbailey fixed title of sample app section in docs
authored
464 ## Backbone.Marionette Example Apps
0b160f3 @derickbailey adding a simple example to the docs
authored
465
b97e16a @derickbailey added Steve Gentile's sample apps to the list of apps
authored
466 There are several sample apps available.
467
468 ### BBCloneMail
469
470 I'm building a medium sized app to demonstrate Backbone.Marionette. It's a simple
471 clone of a GMail like interface, with email and contact management. There is no
472 back end for data, currently. The sample app does run on top of Ruby and
473 Sinatra, but all the data is hard coded into the HTML/JavaScript right now.
474
475 You can find BBCloneMail online at:
22aed59 @derickbailey updated readme to include links to BBCloneMail
authored
476
477 http://bbclonemail.heroku.com
478
479 And you can find the source code at:
480
4301f6e @derickbailey fixed link to bbclonemail source
authored
481 http://github.com/derickbailey/bbclonemail
22aed59 @derickbailey updated readme to include links to BBCloneMail
authored
482
b97e16a @derickbailey added Steve Gentile's sample apps to the list of apps
authored
483 ### Steve Gentile' Contact Manager
484
485 Steve Gentile is building two versions of the same contact manager app. One of
486 them runs on NodeJS as a back-end, and the other runs on ASP.NET MVC as the
487 back-end.
488
489 The NodeJS version is here:
490
491 https://github.com/sgentile/BackboneNodeContacts
492
493 And the ASP.NET MVC version is here:
494
495 https://github.com/sgentile/BackboneContacts
496
22aed59 @derickbailey updated readme to include links to BBCloneMail
authored
497 ### Quick & Dirty Sample
498
499 Here's a quick and dirty example to show how to use some of the pieces of
500 Marionette:
0b160f3 @derickbailey adding a simple example to the docs
authored
501
58e22ca @nono Add syntax highlighting for examples in the README
nono authored
502 ```js
0b160f3 @derickbailey adding a simple example to the docs
authored
503 // define the application
38121af @derickbailey allow options to be passed into Application initializer, copying them…
authored
504 // options we pass in are copied on to the instance
505 MyApp = new Backbone.Marionette.Application({
506 someOption: "some value";
507 });
0b160f3 @derickbailey adding a simple example to the docs
authored
508
509 // add a region to the app
e5a89f5 @derickbailey updated example app w/ addRegion
authored
510 myRegion = Backbone.Marionette.Region.extend({
0b160f3 @derickbailey adding a simple example to the docs
authored
511 el: "#my-region"
512 });
e5a89f5 @derickbailey updated example app w/ addRegion
authored
513 MyApp.addRegion(myRegion: MyRegion);
0b160f3 @derickbailey adding a simple example to the docs
authored
514
515 // define some functionality for the app
516 (function(MyApp, Backbone){
517
518 // a view to render into the region
c09aa0f @derickbailey scoped a global that was there by accident, in the example module in …
authored
519 var SomeView = Backbone.View.extend({
0b160f3 @derickbailey adding a simple example to the docs
authored
520 render: function(){
38121af @derickbailey allow options to be passed into Application initializer, copying them…
authored
521
522 // get "someOption" from the app, since we
523 // passed it into the app initializer, above
524 $(this.el).html(MyApp.someOption);
0b160f3 @derickbailey adding a simple example to the docs
authored
525 },
526
527 doSomething: function(){
528 // the applicaiton has an event aggregator on instantiation
529 // call out to the event aggregator to raise an event
530 MyApp.vent.trigger("something:happened");
531 }
532 });
533
534 // an initializer to run this functional area
535 // when the app starts up
536 MyApp.addInitializer(function(){
537 var someView = new SomeView();
e5a89f5 @derickbailey updated example app w/ addRegion
authored
538 MyApp.myRegion.show(someView);
0b160f3 @derickbailey adding a simple example to the docs
authored
539 someView.doSomething();
540 });
541
542 })(MyApp, Backbone);
543
544 // calling start will run all of the initializers
545 // this can be done from your JS file directly, or
546 // from a script block in your HTML
4bd2d61 @derickbailey tweak the quick sample to run on jquery dom ready
authored
547 $(function(){
548 MyApp.start();
549 });
58e22ca @nono Add syntax highlighting for examples in the README
nono authored
550 ```
0b160f3 @derickbailey adding a simple example to the docs
authored
551
a0088fc @derickbailey adding better documentation for the core of the project
authored
552 ## Requirements
553
554 Backbone.Marionette is built and tested with the following libraries:
555
556 * Underscore.js v1.2.3
557 * Backbone.js v0.5.3
558 * jQuery v1.7.1
559
560 You may not need to be up to date with these exact versions. However, there is
561 no guarantee that the code will work correctly if you are not.
562
563 ### Test Suite Requirements
2cf4c8e @derickbailey runtime and test suite requirements
authored
564
565 Backbone.Marionette is also tested with the Jasmine JavaScript test utility,
566 using the Jasmine Ruby gem.
567
568 To get the test suite up and running, you need a Ruby installation with the
569 latest RubyGems. Install the 'bundler' gem and then run 'bunle install' from
570 the project's root folder. Then run `rake jasmine` to run the test suite, and
571 load up http://localhost:8888 to see the test suite in action.
572
a0088fc @derickbailey adding better documentation for the core of the project
authored
573 ### Annotated Source Code Generation
574
575 I'm using [Docco](http://jashkenas.github.com/docco/) to generate the annotated source code.
576
577 ## Release Notes
578
eba9730 @derickbailey set version at v0.1.0
authored
579 ### v0.1.0
0b160f3 @derickbailey adding a simple example to the docs
authored
580
a0088fc @derickbailey adding better documentation for the core of the project
authored
581 * Initial release
582 * Created documentation
583 * Generated annotated source code
0b160f3 @derickbailey adding a simple example to the docs
authored
584
2730e21 @derickbailey initial repository with jasmine structure, readme and license in place
authored
585 ## Legal Mumbo Jumbo (MIT License)
586
587 Copyright (c) 2011 Derick Bailey, Muted Solutions, LLC
588
589 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
590
591 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
592
593 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.