Module: NestiveRendering::LayoutHelper

Defined in:
lib/nestive_rendering/layout_helper.rb

Overview

The Nestive Rendering LayoutHelper provides a handful of helper methods for use in your layouts and views.

See the documentation for each individual method for detailed information, but at a high level, your parent layouts define ‘area`s of content. You can define an area and optionally add content to it at the same time using either a String, or a block:

# app/views/layouts/global.html.erb
<html>
  <head>
    <title><%= area :title, "MySite.com" %></title>
  </head>
  <body>
    <div id="content">
      <%= area :content %>
    </div>
    <div id="sidebar">
      <%= area :sidebar do %>
        <h2>About MySite.com</h2>
        <p>...</p>
      <% end %>
    </div>
  </body>
</html>

Your child layouts (or views) inherit and modify the parent by wrapping in an ‘extends` block helper. You can then either `append`, `prepend` or `replace` the content that has previously been assigned to each area by parent layouts.

The ‘append`, `prepend` or `replace` helpers are similar to Rails’ own ‘content_for`, which accepts content for the named area with either a String or with a block). They’re different to ‘content_for` because they’re only used modify the content assigned to the area, not retrieve it:

# app/views/layouts/admin.html.erb
<%= extends :global do %>
  <% prepend :title, "Admin :: " %>
  <% replace :sidebar do %>
    <h2>Quick Links</h2>
    <ul>
      <li>...</li>
    </ul>
  <% end %>
<% end %>

# app/views/admin/posts/index.html.erb
<%= extends :admin do %>
  <% prepend :title, "Posts ::" %>
  <% replace :content do %>
    Normal view stuff goes here.
  <% end %>
<% end %>

Instance Method Summary collapse

Instance Method Details

#append(name, content = nil, &block) ⇒ Object

Appends content to an area previously defined or modified in parent layout(s). You can provide the content using either a String, or a block.

Examples:

Appending content with a String

<% append :sidebar, "Some content." %>

Appending content with a block:

<% append :sidebar do %>
  Some content.
<% end %>

Parameters:

  • name (Symbol) —

    A name to identify the area of content you wish to append to

  • content (String) (defaults to: nil) —

    Optionally provide a String of content, instead of a block. A block will take precedence.



166
167
168
169
 
# File 'lib/nestive_rendering/layout_helper.rb', line 166

def append(name, content=nil, &block)
  content = capture(&block) if block_given?
  add_instruction_to_area name, :push, content
end

#area(name, content = nil, &block) ⇒ Object

Defines an area of content in your layout that can be modified or replaced by child layouts that extend it. You can optionally add content to an area using either a String, or a block.

Areas are declared in a parent layout and modified by a child layout, but since Nestive Rendering allows for multiple levels of inheritance, a child layout can also declare an area for it’s children to modify.

Examples:

Define an area without adding content to it:

<%= area :sidebar %>

Define an area and add a String of content to it:

<%= area :sidebar, "Some content." %>

Define an area and add content to it with a block:

<%= area :sidebar do %>
  Some content.
<% end %>

Define an area in a child layout:

<%= extends :global do %>
  <%= area :sidebar do %>
    Some content.
  <% end %>
<% end %>

Parameters:

  • name (Symbol) —

    A unique name to identify this area of content.

  • content (String) (defaults to: nil) —

    An optional String of content to add to the area as you declare it.



144
145
146
147
148
 
# File 'lib/nestive_rendering/layout_helper.rb', line 144

def area(name, content=nil, &block)
  content = capture(&block) if block_given?
  append name, content
  render_area name
end

#extends(layout, options = {}, &block) ⇒ Object

Declares that the current layour (or view) is inheriting from and extending another layout.

Examples:

Extending the ‘application` layout to create an `admin` layout


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

Extending the ‘admin` layout in a view (you’ll need to render the view with ‘layout: nil`)


# app/controllers/admin/posts_controller.rb
class Admin::PostsController < ApplicationController
  # You can disable Rails' layout rendering for all actions
  layout nil

  # Or disable Rails' layout rendering per-controller
  def index
    render layout: nil
  end
end

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

Parameters:

  • layout (String) —

    The base name of the file in ‘layouts/` that you wish to extend (eg `application` for `layouts/application.html.erb`)

  • options (Hash) (defaults to: {}) —

    Any options such as locals that you want to pass through to the layout rendering



86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/nestive_rendering/layout_helper.rb', line 86

def extends(layout, options = {}, &block)
  # Make sure it's a string
  layout = layout.to_s

  # If there's no directory component, presume a plain layout name
  layout = "layouts/#{layout}" unless layout.include?('/')

  # Capture the content to be placed inside the extended layout
  @view_flow.get(:layout).replace capture(&block)

  render options.merge(file: layout)
end

#extends_partial(partial, options = {}, &block) ⇒ Object

Works exactly the same as extends but is targeted at extending partials not layouts.

Parameters:

  • partial (String) —

    The base name of the partial that you wish to extend (eg ‘header` for `application/_header.html.erb`)

  • options (Hash) (defaults to: {}) —

    Any options such as the object or locals that you want to pass through to the parital rendering



107
108
109
110
111
112
 
# File 'lib/nestive_rendering/layout_helper.rb', line 107

def extends_partial(partial, options = {}, &block)
  # Make sure it's a string
  partial = partial.to_s
  block.call if block_given?
  render options.merge(partial: partial)
end

#prepend(name, content = nil, &block) ⇒ Object

Prepends content to an area previously declared or modified in parent layout(s). You can provide the content using either a String, or a block.

Examples:

Prepending content with a String

<% prepend :sidebar, "Some content." %>

Prepending content with a block:

<% prepend :sidebar do %>
  Some content.
<% end %>

Parameters:

  • name (Symbol) —

    A name to identify the area of content you wish to prepend to

  • content (String) (defaults to: nil) —

    Optionally provide a String of content, instead of a block. A block will take precedence.



187
188
189
190
 
# File 'lib/nestive_rendering/layout_helper.rb', line 187

def prepend(name, content=nil, &block)
  content = capture(&block) if block_given?
  add_instruction_to_area name, :unshift, content
end

#purge(*names) ⇒ Object

Purge the content of an area previously declared or modified in parent layout(s).

Examples:

Purge content

<% purge :sidebar %>

Parameters:

  • names —

    A list of area names to purge



220
221
222
 
# File 'lib/nestive_rendering/layout_helper.rb', line 220

def purge(*names)
  names.each{ |name| replace(name, nil)}
end

#replace(name, content = nil, &block) ⇒ Object

Replaces the content of an area previously declared or modified in parent layout(s). You can provide the content using either a String, or a block.

Examples:

Replacing content with a String

<% replace :sidebar, "New content." %>

Replacing content with a block:

<% replace :sidebar do %>
  New content.
<% end %>

Parameters:

  • name (Symbol) —

    A name to identify the area of content you wish to replace

  • content (String) (defaults to: nil) —

    Optionally provide a String of content, instead of a block. A block will take precedence.



208
209
210
211
 
# File 'lib/nestive_rendering/layout_helper.rb', line 208

def replace(name, content=nil, &block)
  content = capture(&block) if block_given?
  add_instruction_to_area name, :replace, [content]
end