Default content goes here.
<% end %>
This gem is a continuation for Rails 5 of the [nestive](https://github.com/rwz/nestive) gem originally created by Justin French and Pavel Pravosud.
nestive-rails adds powerful layout and view helpers to your Rails app. It's similar to the nested layout technique [already documented in the Rails guides](http://guides.rubyonrails.org/layouts_and_rendering.html#using-nested-layouts) and found in many other nested layout plugins (a technique using `content_for` and rendering the parent layout at the end of the child layout). There's a bunch of problems with this technique, including:
* you can only *append* content to the content buffer with `content_for` (you can't prepend to content, you can't replace it)
* when combined with this nested layout technique, `content_for` actually *prepends* new content to the buffer, because each parent layout is rendered *after* it's child
nestive-rails is *better* because it addresses these problems.
---
## Table of Contents
* [Installation](#installation)
* [Usage](#usage)
* [Caching](#caching)
* [To Do](#to-do)
* [Contributing](#contributing)
* [Contributors](#contributors)
* [License](#license)
---
## Installation
`nestive-rails` works with Rails 5.0 onwards. You can add it to your `Gemfile` with:
```ruby
gem 'nestive-rails'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install nestive-rails
If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
```ruby
gem 'nestive-rails', github: 'jonhue/nestive-rails'
```
## Usage
### Declaring an area of content with `area`:
The `area` helper is a lot like Rails' own `<%= yield :foo %>`, and is used in layouts to define and render a chunk of content in your layout:
```erb
<%= area :sidebar %>
```
Unlike `yield`, `area` will allow your parent layouts to add content to the area at the same time using either a String or a block:
```erb
<%= area :sidebar, "Some Content Here" %>
<%= area :sidebar do %>
Some Content Here
<% end %>
```
It's important to note that this isn't *default* content, it *is* the content (unless a child changes it).
### Appending content to an area with `append`:
The implementation details are quite different, but the `append` helper works much like Rails' built-in `content_for`. It will work with either a String or block, adding the new content onto the end of any content previously provided by parent layouts:
```erb
<%= extends :application do %>
<% append :sidebar, "More content." %>
<% append :sidebar do %>
More content.
<% end %>
<% end %>
```
### Prepending content to an area with `prepend`:
Exactly what you think it is. The reverse of `append` (duh), adding the new content at the start of any content previously provided by parent layouts:
``` erb
<%= extends :application do %>
<%= prepend :sidebar, "Content." %>
<%= prepend :sidebar do %>
Content.
<% end %>
<% end %>
```
### Replacing content with `replace`
You can also replace any content provided by parent layouts:
``` erb
<%= extends :application do %>
<%= replace :sidebar, "New content." %>
<%= replace :sidebar do %>
New content.
<% end %>
<% end %>
```
### Removing content with `purge`
You can remove the content in the single or in multiple areas
``` erb
<% purge :sidebar %>
<% purge :sidebar, :banner %>
```
... which is equal to:
``` erb
<% replace :sidebar, nil %>
```
### Extending a layout in a child layout (or view) with `extends`
Any layout (or view) can declare that it wants to inherit from and extend a parent layout, in this case we're extending `app/views/layouts/application.html.erb`:
``` erb
<%= extends :application do %>
...
<% end %>
```
You can nest many levels deep:
`app/views/layouts/application.html.erb`:
``` erb
<%= area :head do %>
Default content goes here.
<% end %>