Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Changed some README stuff

  • Loading branch information...
commit 2bfea6f878dd08dc46a0cb086b001e004b408dd2 1 parent 5f2a698
@rwz authored
Showing with 77 additions and 85 deletions.
  1. +72 −80 README.md
  2. +5 −5 nestive.gemspec
View
152 README.md
@@ -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)
@@ -16,7 +14,7 @@ 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" %>
@@ -24,41 +22,16 @@ Unlike `yield`, `area` will allow your parent layouts to add content to the area
<%= 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 %>
@@ -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>
@@ -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.
@@ -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
View
10 nestive.gemspec
@@ -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'
Please sign in to comment.
Something went wrong with that request. Please try again.