RubyGems - nestive-rails - Versions diffs - 1.0.1 → 1.0.2 - Mend

nestive-rails 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +13 -14
data/LICENSE +42 -21
data/README.md +311 -317
data/lib/nestive-rails.rb +9 -9
data/lib/nestive-rails/layout_helper.rb +260 -245
data/lib/nestive-rails/railtie.rb +13 -13
data/lib/nestive-rails/version.rb +5 -5
metadata +19 -6

data/lib/nestive-rails.rb CHANGED

@@ -1,9 +1,9 @@
-require 'nestive-rails/version'
-module NestiveRails
-    autoload :LayoutHelper, 'nestive-rails/layout_helper'
-    require 'nestive-rails/railtie'
-end
+# frozen_string_literal: true
+require 'nestive-rails/version'
+module NestiveRails
+  autoload :LayoutHelper, 'nestive-rails/layout_helper'
+  require 'nestive-rails/railtie'
+end

data/lib/nestive-rails/layout_helper.rb CHANGED

@@ -1,245 +1,260 @@
-module NestiveRails
-    # The Nestive 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 %>
-    module LayoutHelper
-        # Declares that the current layour (or view) is inheriting from and extending another layout.
-        #
-        # @param [String] layout
-        #   The base name of the file in `layouts/` that you wish to extend (eg `application` for `layouts/application.html.erb`)
-        #
-        # @example Extending the `application` layout to create an `admin` layout
-        #
-        #     # app/views/layouts/admin.html.erb
-        #     <%= extends :application do %>
-        #       ...
-        #     <% end %>
-        #
-        # @example 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 %>
-        def extends layout, &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).to_s
-            render file: layout
-        end
-        # 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
-        # allows for multiple levels of inheritance, a child layout can also declare an area for it's
-        # children to modify.
-        #
-        # @example Define an area without adding content to it:
-        #     <%= area :sidebar %>
-        #
-        # @example Define an area and add a String of content to it:
-        #     <%= area :sidebar, "Some content." %>
-        #
-        # @example Define an area and add content to it with a block:
-        #     <%= area :sidebar do %>
-        #       Some content.
-        #     <% end %>
-        #
-        # @example Define an area in a child layout:
-        #     <%= extends :global do %>
-        #       <%= area :sidebar do %>
-        #         Some content.
-        #       <% end %>
-        #     <% end %>
-        #
-        # @param [Symbol] name
-        #   A unique name to identify this area of content.
-        #
-        # @param [String] content
-        #   An optional String of content to add to the area as you declare it.
-        def area name, content=nil, &block
-            content = capture(&block) if block_given?
-            append name, content
-            render_area name
-        end
-        # 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.
-        #
-        # @example Appending content with a String
-        #     <% append :sidebar, "Some content." %>
-        #
-        # @example Appending content with a block:
-        #     <% append :sidebar do %>
-        #       Some content.
-        #     <% end %>
-        #
-        # @param [Symbol] name
-        #   A name to identify the area of content you wish to append to
-        #
-        # @param [String] content
-        #   Optionally provide a String of content, instead of a block. A block will take precedence.
-        def append name, content=nil, &block
-            content = capture(&block) if block_given?
-            add_instruction_to_area name, :push, content
-        end
-        # 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.
-        #
-        # @example Prepending content with a String
-        #     <% prepend :sidebar, "Some content." %>
-        #
-        # @example Prepending content with a block:
-        #     <% prepend :sidebar do %>
-        #       Some content.
-        #     <% end %>
-        #
-        # @param [Symbol] name
-        #   A name to identify the area of content you wish to prepend to
-        #
-        # @param [String] content
-        #   Optionally provide a String of content, instead of a block. A block will take precedence.
-        def prepend name, content=nil, &block
-            content = capture(&block) if block_given?
-            add_instruction_to_area name, :unshift, content
-        end
-        # 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.
-        #
-        # @example Replacing content with a String
-        #     <% replace :sidebar, "New content." %>
-        #
-        # @example Replacing content with a block:
-        #     <% replace :sidebar do %>
-        #       New content.
-        #     <% end %>
-        #
-        # @param [Symbol] name
-        #   A name to identify the area of content you wish to replace
-        #
-        # @param [String] content
-        #   Optionally provide a String of content, instead of a block. A block will take precedence.
-        def replace name, content=nil, &block
-            content = capture(&block) if block_given?
-            add_instruction_to_area name, :replace, [content]
-        end
-        # Purge the content of an area previously declared or modified in parent layout(s).
-        #
-        # @example Purge content
-        #     <% purge :sidebar %>
-        #
-        # @param names
-        #   A list of area names to purge
-        def purge *names
-            names.each{ |name| replace(name, nil) }
-        end
-        private
-        # We record the instructions (declaring, appending, prepending and replacing) for an area of
-        # content into an array that we can later retrieve and replay. Instructions are stored in an
-        # instance variable Hash `@_area_for`, with each key representing an area name, and each value
-        # an Array of instructions. Each instruction is a two element array containing a instruction
-        # method (eg `:push`, `:unshift`, `:replace`) and a value (content String).
-        #
-        #     @_area_for[:sidebar] # => [ [:push,"World"], [:unshift,"Hello"] ]
-        #
-        # Due to the way we extend layouts (render the parent layout after the child), the instructions
-        # are captured in reverse order. `render_area` reversed them and plays them back at rendering
-        # time.
-        #
-        # @example
-        #   add_instruction_to_area(:sidebar, :push, "More content.")
-        def add_instruction_to_area name, instruction, value
-            @_area_for ||= {}
-            @_area_for[name] ||= []
-            @_area_for[name] << [instruction, value]
-            nil
-        end
-        # Take the instructions we've gathered for the area and replay them one after the other on
-        # an empty array. These instructions will push, unshift or replace items into our output array,
-        # which we then join and mark as html_safe.
-        #
-        # These instructions are reversed and replayed when we render the block (rather than as they
-        # happen) due to the way they are gathered by the layout extension process (in reverse).
-        def render_area name
-            [].tap do |output|
-                @_area_for.fetch(name, []).reverse_each do |method_name, content|
-                    output.public_send method_name, content
-                end
-            end.join.html_safe
-        end
-    end
-end
+# frozen_string_literal: true
+module NestiveRails
+  # The Nestive 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 %>
+  module LayoutHelper
+    # Declares that the current layour (or view) is inheriting from and
+    # extending another layout.
+    #
+    # @param [String] layout
+    #   The base name of the file in `layouts/` that you wish to extend (eg
+    #   `application` for `layouts/application.html.erb`)
+    #
+    # @example Extending the `application` layout to create an `admin` layout
+    #
+    #     # app/views/layouts/admin.html.erb
+    #     <%= extends :application do %>
+    #       ...
+    #     <% end %>
+    #
+    # @example 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 %>
+    def extends(layout, &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).to_s
+      render file: layout
+    end
+    # 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 allows for multiple levels of inheritance, a child layout
+    # can also declare an area for it's children to modify.
+    #
+    # @example Define an area without adding content to it:
+    #     <%= area :sidebar %>
+    #
+    # @example Define an area and add a String of content to it:
+    #     <%= area :sidebar, "Some content." %>
+    #
+    # @example Define an area and add content to it with a block:
+    #     <%= area :sidebar do %>
+    #       Some content.
+    #     <% end %>
+    #
+    # @example Define an area in a child layout:
+    #     <%= extends :global do %>
+    #       <%= area :sidebar do %>
+    #         Some content.
+    #       <% end %>
+    #     <% end %>
+    #
+    # @param [Symbol] name
+    #   A unique name to identify this area of content.
+    #
+    # @param [String] content
+    #   An optional String of content to add to the area as you declare it.
+    def area(name, content = nil, &block)
+      content = capture(&block) if block_given?
+      append name, content
+      render_area name
+    end
+    # 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.
+    #
+    # @example Appending content with a String
+    #     <% append :sidebar, "Some content." %>
+    #
+    # @example Appending content with a block:
+    #     <% append :sidebar do %>
+    #       Some content.
+    #     <% end %>
+    #
+    # @param [Symbol] name
+    #   A name to identify the area of content you wish to append to
+    #
+    # @param [String] content
+    #   Optionally provide a String of content, instead of a block. A block will
+    #   take precedence.
+    def append(name, content = nil, &block)
+      content = capture(&block) if block_given?
+      add_instruction_to_area name, :push, content
+    end
+    # 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.
+    #
+    # @example Prepending content with a String
+    #     <% prepend :sidebar, "Some content." %>
+    #
+    # @example Prepending content with a block:
+    #     <% prepend :sidebar do %>
+    #       Some content.
+    #     <% end %>
+    #
+    # @param [Symbol] name
+    #   A name to identify the area of content you wish to prepend to
+    #
+    # @param [String] content
+    #   Optionally provide a String of content, instead of a block. A block will
+    #   take precedence.
+    def prepend(name, content = nil, &block)
+      content = capture(&block) if block_given?
+      add_instruction_to_area name, :unshift, content
+    end
+    # 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.
+    #
+    # @example Replacing content with a String
+    #     <% replace :sidebar, "New content." %>
+    #
+    # @example Replacing content with a block:
+    #     <% replace :sidebar do %>
+    #       New content.
+    #     <% end %>
+    #
+    # @param [Symbol] name
+    #   A name to identify the area of content you wish to replace
+    #
+    # @param [String] content
+    #   Optionally provide a String of content, instead of a block. A block will
+    #   take precedence.
+    def replace(name, content = nil, &block)
+      content = capture(&block) if block_given?
+      add_instruction_to_area name, :replace, [content]
+    end
+    # Purge the content of an area previously declared or modified in parent
+    # layout(s).
+    #
+    # @example Purge content
+    #     <% purge :sidebar %>
+    #
+    # @param names
+    #   A list of area names to purge
+    def purge(*names)
+      names.each { |name| replace(name, nil) }
+    end
+    private
+    # We record the instructions (declaring, appending, prepending and
+    # replacing) for an area of content into an array that we can later retrieve
+    # and replay. Instructions are stored in an instance variable Hash
+    # `@_area_for`, with each key representing an area name, and each value an
+    # Array of instructions. Each instruction is a two element array containing
+    # a instruction method (eg `:push`, `:unshift`, `:replace`) and a value
+    # (content String).
+    #
+    #     @_area_for[:sidebar] # => [ [:push,"World"], [:unshift,"Hello"] ]
+    #
+    # Due to the way we extend layouts (render the parent layout after the
+    # child), the instructions are captured in reverse order. `render_area`
+    # reversed them and plays them back at rendering time.
+    #
+    # @example
+    #   add_instruction_to_area(:sidebar, :push, "More content.")
+    def add_instruction_to_area(name, instruction, value)
+      @_area_for ||= {}
+      @_area_for[name] ||= []
+      @_area_for[name] << [instruction, value]
+      nil
+    end
+    # Take the instructions we've gathered for the area and replay them one
+    # after the other on an empty array. These instructions will push, unshift
+    # or replace items into our output array, which we then join and mark as
+    # html_safe.
+    #
+    # These instructions are reversed and replayed when we render the block
+    # (rather than as they happen) due to the way they are gathered by the
+    # layout extension process (in reverse).
+    def render_area(name)
+      [].tap do |output|
+        @_area_for.fetch(name, []).reverse_each do |method_name, content|
+          output.public_send method_name, content
+        end
+      end.join.html_safe
+    end
+  end
+end