<commit_before>backbone.layoutmanager
=======================

Created by <NAME> [@tbranyen](http://twitter.com/tbranyen) with contributions from [@nedcampion](https://github.com/nedcampion)

Provides a logical structure for assembling layouts with Backbone Views.
Designed to be adaptive and configurable for painless integration.

Depends on Underscore, Backbone and jQuery.  You can swap out the 
jQuery dependency completely with a custom configuration.

## Tutorials and Screencasts ##

[Initial Screencast](http://vimeo.com/32765088)

## Download & Include ##

Development is fully commented source, Production is minified and stripped of
all comments except for license/credits.

* [Development](https://raw.github.com/tbranyen/backbone.layoutmanager/master/backbone.layoutmanager.js)
* [Production](https://raw.github.com/tbranyen/backbone.layoutmanager/master/dist/backbone.layoutmanager.min.js)

Include in your application *after* jQuery, Underscore, and Backbone have been included.

``` html
<script src="/js/jquery.js"></script>
<script src="/js/underscore.js"></script>
<script src="/js/backbone.js"></script>

<script src="/js/backbone.layoutmanager.js"></script>
```

## Usage ##

This example renders a View into a template which is injected into a layout.

### Create and render a layout ###

This code typically resides in a route callback.  If you want to provide a
custom object for your template engine to the layout, use the `serialize`
property.

``` javascript
// Create a new layout using the #main template.
var main = new Backbone.LayoutManager({
  template: "#main-layout",

  // In the secondary column, put a new Login View.
  views: {
    ".secondary": new LoginView()
  }
});

// Render into <body>.
main.render(function(el) {
  $("body").html(el);
});
```

Views may also be alternatively defined later:

``` javascript
main.view(".header", new HeaderView);
main.view(".footer", new FooterView);
```

Use the above syntax to change out views at a later time as well, remember to
call the View's `render` method after swapping out to have it displayed.

### Nested Views ###

You may have a situation where a View is defined that encapsulates other nested
Views.  In these cases you should use nested views inside your LayoutManager
View assignments.

Check out this example to see how easy this is:

``` javascript
var main = new Backbone.LayoutManager({
  template: "#some-layout",

  views: {
    ".partial": new PartialView({
      views: {
        ".inner": new InnerView()
      }
    })
  }
});
```

You can nest Views infinitely.

### Structuring a 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({
  // Tell LayoutManager what template to associate with this View.
  template: "#login-template",

  // The render function will be called internally by LayoutManager.
  render: function(layout) {
    // Wrap the layout with this View and call render.
    return layout(this).render();
  }
});
```

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 LoginView = Backbone.LayoutManager.View.extend({
  template: "#login-template"
});
```

#### Re-rendering Views ####

Instead of re-rendering the entire layout after data in a single View changes,
you can simply call `render()` on the View and it will automatically update
the DOM.  You **cannot** bind to the initial render reference, like so

*Assume that you have a model that when changed, causes a redraw.*

``` javascript
var MyView = Backbone.LayoutManager.View.extend({
  initialize: function() {
    this.model.bind("change", this.render, this);
  }
});
```

You must use this syntax instead, calling it from a function:

``` javascript
var MyView = Backbone.LayoutManager.View.extend({
  initialize: function() {
    this.model.bind("change", function() {
      this.render();
    }, this);
  }
});
```

This necessity may be alleviated in a future version.

#### Working with context ####<commit_msg>added documentation for rendering a list<commit_after>backbone.layoutmanager
=======================

Created by <NAME> [@tbranyen](http://twitter.com/tbranyen) with contributions from [@nedcampion](https://github.com/nedcampion)

Provides a logical structure for assembling layouts with Backbone Views.
Designed to be adaptive and configurable for painless integration.

Depends on Underscore, Backbone and jQuery.  You can swap out the 
jQuery dependency completely with a custom configuration.

## Tutorials and Screencasts ##

[Initial Screencast](http://vimeo.com/32765088)

## Download & Include ##

Development is fully commented source, Production is minified and stripped of
all comments except for license/credits.

* [Development](https://raw.github.com/tbranyen/backbone.layoutmanager/master/backbone.layoutmanager.js)
* [Production](https://raw.github.com/tbranyen/backbone.layoutmanager/master/dist/backbone.layoutmanager.min.js)

Include in your application *after* jQuery, Underscore, and Backbone have been included.

``` html
<script src="/js/jquery.js"></script>
<script src="/js/underscore.js"></script>
<script src="/js/backbone.js"></script>

<script src="/js/backbone.layoutmanager.js"></script>
```

## Usage ##

This example renders a View into a template which is injected into a layout.

### Create and render a layout ###

This code typically resides in a route callback.  If you want to provide a
custom object for your template engine to the layout, use the `serialize`
property.

``` javascript
// Create a new layout using the #main template.
var main = new Backbone.LayoutManager({
  template: "#main-layout",

  // In the secondary column, put a new Login View.
  views: {
    ".secondary": new LoginView()
  }
});

// Render into <body>.
main.render(function(el) {
  $("body").html(el);
});
```

Views may also be alternatively defined later:

``` javascript
main.view(".header", new HeaderView);
main.view(".footer", new FooterView);
```

Use the above syntax to change out views at a later time as well, remember to
call the View's `render` method after swapping out to have it displayed.

### Nested Views ###

You may have a situation where a View is defined that encapsulates other nested
Views.  In these cases you should use nested views inside your LayoutManager
View assignments.

Check out this example to see how easy this is:

``` javascript
var main = new Backbone.LayoutManager({
  template: "#some-layout",

  views: {
    ".partial": new PartialView({
      views: {
        ".inner": new InnerView()
      }
    })
  }
});
```

You can nest Views infinitely.

### Structuring a 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({
  // Tell LayoutManager what template to associate with this View.
  template: "#login-template",

  // The render function will be called internally by LayoutManager.
  render: function(layout) {
    // Wrap the layout with this View and call render.
    return layout(this).render();
  }
});
```

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 LoginView = Backbone.LayoutManager.View.extend({
  template: "#login-template"
});
```

#### Re-rendering Views ####

Instead of re-rendering the entire layout after data in a single View changes,
you can simply call `render()` on the View and it will automatically update
the DOM.  You **cannot** bind to the initial render reference, like so

*Assume that you have a model that when changed, causes a redraw.*

``` javascript
var MyView = Backbone.LayoutManager.View.extend({
  initialize: function() {
    this.model.bind("change", this.render, this);
  }
});
```

You must use this syntax instead, calling it from a function:

``` javascript
var MyView = Backbone.LayoutManager.View.extend({
  initialize: function() {
    this.model.bind("change", function() {
      this.render();
    }, this);
  }
});
```

This necessity may be alleviated in a future version.

#### Rendering consecutive views ####

There are many times in which you will end up with a list of nested views
that result from either iterating a `Backbone.Collection` or array
and will need to dynamically add these nested views into a main view.

LayoutManager solves this by exposing a method to change the insert mode
from replacing the `innerHTML` to `appendChild` instead.  Whenever you
use the `insert` method inside a render function you will put the
nested view into this special mode.

All sub views are inserted in order, regardless if the `fetch` method has
been overwritten to be asynchronous.

An example will illustrate the pattern easier:

``` javascript
// An example item View
// You may find it easier to have Backbone render the LI/TD/etc element
// instead of including this in your template.  This is purely convention
// use what works for you.
var SomeItem = Backbone.LayoutManager.View.extend({
  template: "#list",

  // In this case we'll say the item is an <LI>
  tagName: "li"
});

// The view that contains the <ul> <table> w/e is used to contain your element.
// 
// Since this method is used inside a custom render method, LayoutManager.View
// isn't useful for rendering a collection list.
var SomeList = Backbone.View.extend({
  template: "#item",

  render: function(layout) {
    // Assign the layout view custom object to the 
    var view = layout(this);

    // Iterate over the passed collection and create a view for each item
    this.collection.each(function(model) {
      // Pass the model to the new SomeItem view
      view.insert("ul", new SomeItem({
        model: model
      });
    });

    // You still must return this view to render, works identical to the
    // existing functionality.
    return view.render();
  }
});
```

#### Working with context ####
{'fraction_non_alphanumeric': 0.11098232396406839, 'fraction_numerical': 0.0015454457645127017, 'mean_word_length': 4.043351193375548, 'pattern_counts': {'":': 6, '<': 26, '<?xml version=': 0, '>': 26, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2508114', 'n_tokens_mistral': 2946, 'n_tokens_neox': 2791, 'n_words': 1210}