Permalink
Browse files

many changes to api and documentation, Closes #9, #8

  • Loading branch information...
1 parent f0c41ea commit cd4407e12f246f6b42ffacc7bcdba9d064d2ad4c @tbranyen committed Nov 26, 2011
Showing with 89 additions and 111 deletions.
  1. +56 −72 README.md
  2. +30 −29 backbone.layoutmanager.js
  3. +3 −10 test/views.js
View
128 README.md
@@ -3,103 +3,87 @@ backbone.layoutmanager
Created by Tim Branyen [@tbranyen](http://twitter.com/tbranyen)
-Provides a logical structure for assembling layouts within Backbone views.
-Designed to be adaptive and configurable, `LayoutManager`, should work with
-any templating implementation.
+Provides a logical structure for assembling layouts with Backbone Views.
+Designed to be adaptive and configurable for painless integration.
-## Basic usage ##
+Depends on Underscore, Backbone and jQuery. You can swap out the
+jQuery dependency completely with a custom configuration.
-### Templates
+## Usage ##
-#### Example index.html ####
+This example renders a View into a template which is injected into a layout.
-_/index.html_
+### Create and render a layout ###
-``` html
-<!DOCTYPE html>
-<head>
- <meta charset=utf-8>
- <title>Example Application</title>
-</head>
-
-<body>
- <!-- Where layouts will be injected -->
- <div class="container"></div>
-
- <!-- Third party libraries -->
- <script src="/assets/js/libs/jquery.js"></script>
- <script src="/assets/js/libs/underscore.js"></script>
- <script src="/assets/js/libs/backbone.js"></script>
- <script src="/assets/js/libs/backbone.layoutmanager.js"></script>
-
- <!-- Application -->
- <script src="/assets/js/application.js"></script>
-
-</body>
-</html>
-```
+This code typically resides in a route callback.
-#### Example Main Layout ####
+``` javascript
+// Create a new layout using the #main template.
+var main = new Backbone.LayoutManager({
+ name: "#main-layout"
+});
-_/assets/templates/layouts/main.html_
+// In the secondary column, put a new Login View.
+main.views[".secondary"] = new LoginView();
-``` html
-<section class="content twelve columns"></section>
-<aside class="secondary four columns"></aside>
+// Render into the container.
+main.render(function(contents) {
+ $(".container").html(contents);
+});
```
-#### Example Login Template ####
+### Structuring a View ###
-_/assets/templates/login.html_
-
-``` html
-<form class="login">
- <p><label for="user">Username</label><input type="text" name="user"></p>
- <p><label for="pass">Password</label><input type="text" name="pass"></p>
- <p><input class="loginBtn" type="submit" value="Login"></p>
-</form>
-```
-
-### View
+Each View needs to have a template associated, via the `template` property.
+This name by default is a jQuery selector, but if you have a custom
+configuration this could potentially be a filename or JST function name.
``` javascript
-var LoginView = Backbone.View.extend({
- template: "/assets/templates/login.html",
+var LoginView = Backbone.LayoutManager.View.extend({
+ // Tell LayoutManager what template to associate with this View.
+ template: "#login-template",
// The render function will be called internally by LayoutManager.
- // Do whatever you'd like inside this render method, but ensure to return
- // layout(this).render(/* Optional object for template engine */);
render: function(layout) {
+ // Wrap the layout with this View and call render.
return layout(this).render();
}
});
```
-### Route/Controller
+Optionally, you can extend from `LayoutManager.View` and omit the `render`
+method. If you need to do custom logic in `render`, you should use the
+other pattern above.
``` javascript
-var Router = Backbone.Router.extend({
- routes: {
- "": "home"
- },
-
- // When someone navigates to /
- home: function() {
- // Fetch the main.html layout
- var main = new Backbone.LayoutManager({
- name: "/assets/templates/layouts/main.html"
- });
+var LoginView = Backbone.LayoutManager.View.extend({
+ template: "#login-template"
+});
+```
- // In the secondary column, put a new Login View.
- main.partials[".secondary"] = new LoginView();
+### Defining the layout and template ###
- // Contents is a DOM node that contains the layout. In this example
- // it is being injected into the container DIV.
- main.render(function(contents) {
- $(".container").html(contents);
- });
- }
-});
+#### Main layout ####
+
+``` html
+<script id="main-layout" type="layout">
+ <section class="content twelve columns"></section>
+
+ <!-- Template below will be injected here -->
+ <aside class="secondary four columns"></aside>
+</script>
+```
+
+#### Login template ####
+
+``` html
+<script id="login-template" type="template">
+ <form class="login">
+ <p><label for="user">Username</label><input type="text" name="user"></p>
+ <p><label for="pass">Password</label><input type="text" name="pass"></p>
+ <p><input class="loginBtn" type="submit" value="Login"></p>
+ </form>
+</script>
```
## Advanced Usage ##
View
@@ -11,20 +11,20 @@
var LayoutManager = Backbone.LayoutManager = Backbone.View.extend({
initialize: function(opts) {
- // Handle partials support
- var partials = {};
+ // Handle views support
+ var views = {};
- // Mix in the partials function
- if (_.isFunction(this.partials)) {
- _.extend(partials, this.partials.call(this));
+ // Mix in the views function
+ if (_.isFunction(this.views)) {
+ _.extend(views, this.views.call(this));
- // Mix in the partials object
- } else if (_.isObject(this.partials)) {
- _.extend(partials, this.partials);
+ // Mix in the views object
+ } else if (_.isObject(this.views)) {
+ _.extend(views, this.views);
}
- // Assign the new partials object
- this.partials = partials;
+ // Assign the new views object
+ this.views = views;
// Merge in the default options
this.options = _.extend({}, Backbone.LayoutManager, this.options);
@@ -64,7 +64,7 @@ var LayoutManager = Backbone.LayoutManager = Backbone.View.extend({
// Ensure the cache is up-to-date
LayoutManager.cache(url, contents);
- // Render the partial into the View's el property.
+ // Render the View into the el property.
view.el.innerHTML = options.render.call(options, contents, context);
// Signal that the fetching is done, wrap in a setTimeout to ensure,
@@ -122,8 +122,8 @@ var LayoutManager = Backbone.LayoutManager = Backbone.View.extend({
manager.el.innerHTML = contents;
}
- // Iterate over each partial and apply the render method
- _.each(manager.partials, function(view, name) {
+ // Iterate over each View and apply the render method
+ _.each(manager.views, function(view, name) {
// TODO: Add reset logic here
// Render into a variable
@@ -192,41 +192,41 @@ var LayoutManager = Backbone.LayoutManager = Backbone.View.extend({
// Directly
Backbone.LayoutManager.prototype.options = _.extend(options, opts);
}
- }
+ },
+
+ View: Backbone.View.extend({
+ render: function(layout) {
+ return layout(this).render();
+ }
+ });
+
});
// Default configuration options; designed to be overriden.
-// Paths : Template and layout properties containing paths to prefix for fetch.
-// Fetch : Returns template contents as a string.
-// Partial: Injects template into the layout.
-// Render : Used to combine context objects to templates.
Backbone.LayoutManager.prototype.options = {
+
// Can be used to supply a different deferred that implements Promises/A.
deferred: function() {
return $.Deferred();
},
+ // Layout and template properties can be assigned here to prefix
+ // template/layout names.
paths: {},
// Fetch is passed a path and is expected to return template contents as a
- // string. As you can see below assigning this.async() to a variable
- // can be used for asynchronous operations.
+ // string.
fetch: function(path) {
- var done = this.async();
-
- // Do a basic GET for the file path and call done.
- $.get(path, function(data) {
- done(data);
- });
+ return $(path).html();
},
// This is really the only way you will want to partially apply a view into
// a layout. Its entirely possible you'll want to do it differently, so
// this method is available to change.
//
- // @Layout : Is the LayoutManager's el property.
- // @Name : Is the key name specified in the partial assignment.
- // @Template : Is the View's el property.
+ // layout : Is the LayoutManager's el property.
+ // name : Is the key name specified in the view assignment.
+ // template : Is the View's el property.
partial: function(layout, name, template) {
$(layout).find(name).html(template);
},
@@ -235,6 +235,7 @@ Backbone.LayoutManager.prototype.options = {
render: function(template, context) {
return _.template(template)(context);
}
+
};
}).call(this);
View
@@ -1,22 +1,15 @@
module("views", {
setup: function() {
- // Set up LayoutManager to be DOM
- Backbone.LayoutManager.configure({
- fetch: function(path) {
- return $(path).html();
- }
- });
-
// Custom View
this.View = Backbone.View.extend({
template: "#test",
render: function(layout) {
- return layout(this).render({ text: "Right" });
+ return layout(this).render({ text: this.msg });
},
initialize: function(msg) {
-
+ this.msg = msg;
}
});
}
@@ -27,7 +20,7 @@ asyncTest("render one partial", function() {
name: "#main"
});
- main.partials[".right"] = new this.View();
+ main.views[".right"] = new this.View("Right");
main.render(function(contents) {
var trimmed = $.trim( $(contents).find(".right div").html() );

0 comments on commit cd4407e

Please sign in to comment.