Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Better Nested Inheritable Layouts Plugin for Rails
Ruby
Tree: 57fb205ae5

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
app/helpers/nestive
lib
spec
.gitignore
.travis.yml
.yardopts
Gemfile
MIT-LICENSE
README.md
Rakefile
config.ru
nestive.gemspec

README.md

Nestive Build Status Code Climate

A Nested Inheritable Layouts Helpers for Rails

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 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 is better because it addresses these problems.

Just six methods (so far)

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:

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

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:

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

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

<%= extends :application do %>
  <%= replace :sidebar, "New content." %>
  <%= replace :sidebar do %>
    New content.
  <% end %>
<% end %>

Removing content with purge

You can remove the content of the area:

<% purge :sidebar %>

... which is equal to:

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

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

app/views/layouts/application.html.erb:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <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>
<body>
  <div id="wrapper">
    <div id="content">
      <%= area :content do %>
        <p>Default content goes here.</p>
      <% end %>
    </div>
    <div id="sidebar">
      <%= area :sidebar do %>
        <h2>About Me</h2>
        <p>...</p>
      <% 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 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:

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

<% append :sidebar do %>
  <h2>Blog Roll</h2>
  <%= render @links %>
<% end %>

We also need to instruct the PostsController to use this blog layout:

app/controllers/posts_controller.rb:

class PostsController < ApplicationController
  layout 'blog'
end

Installation

  • add gem 'nestive', '~> 0.2' to your Gemfile
  • run bundle

Compatibility

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.

You can help with...

  • feedback
  • reporting issues
  • fixing issues with pull requests
  • performance testing

Twitter

Something went wrong with that request. Please try again.