Skip to content

Commit

Permalink
Changed some README stuff
Browse files Browse the repository at this point in the history
  • Loading branch information
@rwz
rwz committed Nov 10, 2012
1 parent 5f2a698 commit 2bfea6f
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 85 deletions.
152 changes: 72 additions & 80 deletions README.md
View file
@@ -1,7 +1,5 @@
# Nestive, A Nested Inheritable Layouts Plugin for Rails

**Note: This is ridiculously alpha proof-of-concept seeking feedback. Things will change.**

Nestive 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)
Expand All @@ -16,49 +14,24 @@ Nestive is *better* because it addresses these problems.
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:

<%= 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:

<%= 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).

### Extending a layout in a child layout (or view):

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`:

<%= extends :application do %>
...
<% end %>

You can nest many levels deep:

# app/views/posts/index.html.erb
<%= extends :blog do %>
...
<% end %>

# app/views/layouts/blog.html.erb
<%= extends :public do %>
...
<% end %>

# app/views/layouts/public.html.erb
<%= extends :application do %>
...
<% 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:

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:

<%= extends :application do %>
<%= append :sidebar, "More content." %>
<%= append :sidebar do %>
<% append :sidebar, "More content." %>
<% append :sidebar do %>
More content.
<% end %>
<% end %>
Expand All @@ -85,17 +58,63 @@ You can also replace any content provided by parent layouts:
<% end %>
<% end %>

### Extending a layout in a child layout (or view):

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`:

<%= extends :application do %>
...
<% end %>

You can nest many levels deep:

# app/views/layouts/application.html.erb
<!DOCTYPE html>
<html>
<head>
<%= area :head do %>
<title><%= area :title, 'Nestive' %></title>
<% end %>
</head>
<body>
<%= yield %>
</body>
</html>

# app/views/layouts/with_sidebar.html.erb
<%= extends :application do %>
<div class="sidebar"><%= area(:sidebar) do %>
here goes sidebar
<% end %></div>
<%= yield -%>
<% end %>

# app/views/layouts/blog_posts.html.erb
<%= extends :with_sidebar do %>
<% append :sidebar do %>
Blog archive:
<%= render_blog_archive %>
<% end %>

<% append :head do %>
<%= javascript_include_tag 'fancy_blog_archive_tag_cloud' %>
<% end %>

<%= yield %>
<% end %>



## The token blog example

Set-up a global layout defining some content areas. Note that there is no `<% yield %>` here.
Set-up a global layout defining some content areas.

# app/views/layouts/application.html.erb
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title><%= area :title %> JustinFrench.com</title>
<title><%= area :title, "JustinFrench.com" %></title>
<meta name="description" content="<%= area :description, "This is my website." %>">
<meta name="keywords" content="<%= area :keywords, "justin, french, ruby, design" %>">
</head>
Expand All @@ -113,76 +132,49 @@ Set-up a global layout defining some content areas. Note that there is no `<% yi
<% end %>
</div>
</div>
<%= yield %>
</body>
</html>

Next, we set-up a `blog` layout that extends `application`, replacing, appending & prepending content to the areas we defined earlier.

# app/views/layouts/blog.html.erb
<%= extends :application do %>
<% replace :title, "My Blog – " %>
<% replace :description, "Justin French blogs here on Ruby, Rails, Design, Formtastic, etc" %>
<% prepend :keywords, "blog, weblog, design links, ruby links, formtastic release notes, " %>
<%= yield %>
<% end %>

Now our blog index view can extend `blog` and fill in the areas with content specific to the index action.
Now in our blog index view we can use `blog` layout and fill in the areas with content specific to the index action.

# app/views/posts/index.html.erb
<%= extends :blog do %>
<% replace :content do %>
<h1>My Blog</h1>
<% render @articles %>
<% end %>

<% append :content do %>
<h2>Blog Roll</h2>
<% render @links %>
<% end %>
<% replace :content do %>
<h1>My Blog</h1>
<%= render @articles %>
<% end %>

We also need to instruct the `PostsController` not to wrap the view in a layout of it's own (default Rails behavior), which can be done on an individual action:

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
def index
render :layout => false
end
end
<% append :sidebar do %>
<h2>Blog Roll</h2>
<%= render @links %>
<% end %>

Or for an entire controller:
We also need to instruct the `PostsController` to use this `blog` layout:

# app/controllers/posts_controller.rb
class PostsController < ApplicationController
layout false
end

Or for every controller:

# app/controllers/application_controller.rb
class ApplicationController < ActionController::Base
layout false
layout 'blog'
end

We'll find a way to make this easier or a bit more obvious in a future version.


## Installation

* add `gem 'nestive', '~> 0.1'` to your gemfile
* add `gem 'nestive', '~> 0.2'` to your gemfile
* run `bundle`
* add `layout nil` to ApplicationController or the specific controllers you want to use Nestive on (see above)


## TODO

* Figure out how to test it
* Actually use it in an app
* You know, everything!


## Compatibility

Only testing it with Rails 3.1 RCs right now, but it should work with Rails 2 & 3. The dependency is set to ~> 3.0 right now, will change to 2.x when someone can test it works.
Nestive should work properly with any Rails 3.*. It should probably work with 2.* too, but we don't have test coverage for this.

*Nestive doesn't monkey patch or fiddle with any default behaviors in Rails.* Use it when you want to, don't when you don't.

Expand All @@ -195,5 +187,5 @@ Only testing it with Rails 3.1 RCs right now, but it should work with Rails 2 &

## Twitter

* [@nestivegem](http://twitter.com/nestivegem)
* [@justinfrench](http://twitter.com/justinfrench)
* [@rwz](https://twitter.com/rwz) — current maintainer
* [@justinfrench](http://twitter.com/justinfrench) — author
10 changes: 5 additions & 5 deletions nestive.gemspec
View file
Expand Up @@ -6,11 +6,11 @@ Gem::Specification.new do |s|
s.name = "nestive"
s.version = Nestive::VERSION
s.platform = Gem::Platform::RUBY
s.authors = ['Justin French']
s.email = ['justin@indent.com.au']
s.homepage = ''
s.summary = %{A Rails plugin/gem for awesome nested templates and layouts}
s.description = %{A Rails plugin/gem for awesome nested templates and layouts}
s.authors = ['Justin French', 'Pavel Pravosud']
s.email = ['justin@indent.com.au', 'pavel@pravosud.com']
s.homepage = 'https://github.com/rwz/nestive'
s.summary = 'A Rails plugin/gem for awesome nested templates and layouts'
s.description = 'A Rails plugin/gem for awesome nested templates and layouts'

s.rubyforge_project = 'nestive'

Expand Down

0 comments on commit 2bfea6f

Please sign in to comment.