sections_rails 0.7.1 → 0.7.2

data/README.md

@@ -1,38 +1,33 @@
-_SectionsRails_ adds a component-oriented infrastructure to the view layer of Ruby on Rails.
+# Sections for Rails [![Build Status](https://travis-ci.org/kevgo/sections_rails.png?branch=master)](https://travis-ci.org/kevgo/sections_rails) [![Code Climate](https://codeclimate.com/github/kevgo/sections_rails.png)](https://codeclimate.com/github/kevgo/sections_rails) [![Coverage Status](https://coveralls.io/repos/kevgo/sections_rails/badge.png?branch=master)](https://coveralls.io/r/kevgo/sections_rails)
 
-In short, the DOM, styling, behavior, tests, and other data for dedicated pieces of a web page are defined together, in one directory,
-rather than spread across _app/views_, _app/assets/javascripts_, _app/assets/stylesheets_, and _spec/javascripts_.
-This makes it easier to work on those pieces, makes them more reusable, and large code bases more managable.
+_A component-oriented infrastructure for the view layer of Ruby on Rails applications._
 
+A _section_ organizes all assets (DOM, styling, behavior, tests etc) for a particular component of a web site (a menu, a navbar, a slideshow etc)
+together. This makes development easier, components more reusable, and large code bases more managable.
 
-# Example
 
-Let's take the navigation menu within a web site as an example section.
-It consists of certain HTML, CSS, and JavaScript code as well as image resources.
-These assets must be loaded on every page that this navigation menu is visible on,
-and should be removed when the navigation menu is removed from the site.
+## Example
 
-Traditionally, these files are defined in this directory structure:
+A navigation menu (as an example for a component) within a web site consists of HTML, CSS, and JavaScript code, image resources, as well as unit tests.
+Traditionally, these files are defined in a directory like this:
 
-```
-/app/assets/javascripts/menu.js
-                       /templates/entry.jst.ejs
-           /stylesheets/menu.css
-    /views/shared/_menu.html.erb
-/doc/menu.md
-/spec/javascripts/menu_spec.js
-```
+    /app/assets/images/background.gif                   # Background image.
+               /javascripts/menu.js                     # Logic for the menu.
+                           /templates/entry.jst.ejs     # Client-side template for menu entries.
+               /stylesheets/menu.css                    # Styling.
+        /views/shared/_menu.html.erb                    # Server-side template.
+    /spec/javascripts/menu_spec.js                      # Unit tests.
 
-_Sections_rails_ allows to define these assets together, as a _section_ inside the _/app_ folder:
+_Sections_rails_ allows to define these assets together, as a _section_, inside the _/app_ folder:
 
-    /app/sections/menu/_menu.html.erb     # Server side template.
-                       menu.css           # Styling for the menu.
-                       menu.js            # Logic for the menu.
-                       readme.md          # Documentation.
-                       entry.jst.ejs      # Client-side template.
-                       menu_spec.coffee   # Unit test for logic of this template.
+    /app/sections/menu/_menu.html.erb
+                       background.gif
+                       entry.jst.ejs
+                       menu.css
+                       menu.js
+                       menu_spec.coffee
 
-To embed this menu and all its assets into a page, simply do this in your view:
+To embed this menu into a page, simply do this in your view:
 
 ```erb
 <%= section :menu %>
@@ -40,144 +35,139 @@ To embed this menu and all its assets into a page, simply do this in your view:
 
 This command inserts the partial as well as the JS and CSS files from _/app/sections/menu_ into the page.
 
-It does the right thing in all circumstances: In development mode it inserts the individual assets,
-in production mode the assets are included into the precompilation targets.
+It does the right thing in all circumstances: In development mode it inserts the individual files into the page,
+in production mode they are included into the compiled output.
+And when the menu folder is deleted or moved to another page,
+all assets of the menu are cleanly deleted or moved with it!
 
-The gem source comes with a bundled example Rails app in the _demo/_ directory.
-It provides several working examples of sections in action in _views/demos/index.html.erb_.
 
+## Example applications
 
-# Installation
+The gem source comes with a bundled example Rails app in the [demo](https://github.com/kevgo/sections_rails/tree/master/demo) directory.
+Start it up and [check it out](http://localhost:3000)!
+The source code for the sections is [here](https://github.com/kevgo/sections_rails/tree/master/demo/app/sections).
 
-In your Gemfile:
 
-```ruby
-gem 'sections_rails'
-```
+## Installation
 
-Then set up the directory structure:
+In your Gemfile: `gem 'sections_rails'`, then set up the directory structure:
 
 ```bash
 $ rails generate sections
 ```
 
-The generator does the following things:
+The generator
 
-1.  It creates a new folder __/app/sections__,
-    in which you put the source code for the different sections.
+*  creates a new folder __/app/sections__, in which you put the source code for the different sections.
 
-2.  It adds the folder _/app/sections_ to the asset pipeline by inserting this line into your _application.rb_ file:
+*  adds the folder _/app/sections_ to the asset pipeline by inserting this line into your _application.rb_ file:
 
         config.assets.paths << 'app/sections'
 
-3.  It optionally creates a demo section called _hello_world_ that you can try out as described below.
+*  optionally creates a demo section called _hello_world_ that you can try out as described below.
 
 
-In it's current prototypical implementation, _Sections_rails_ also creates empty asset container files:
-__application_sections.js__ and __application_sections.css__.
+The current implementation requires two empty asset container files: __application_sections.js__ and __application_sections.css__.
 Make sure you require them from your main _application.js_ and _application.css_ files.
-They are used only when running _rake assets:precompile_ during deployment, and should be checked in and stay the way they are.
+They are used only when running _rake assets:precompile_ during deployment, should be checked into your code repository, and stay the way they are.
 
 
-# Usage
+## Usage
 
-To use the "hello_world" section created by the sections generator, simply add it to the view:
+To show the "hello_world" section created by the sections generator on a page:
 
 ```erb
 <%= section :hello_world %>
 ```
 
 If your section renders itself completely in JavaScript, you can omit its partial file.
-In this case, the _sections_ helper creates an empty div in the view.
+In this case, the _sections_ helper creates an empty div with the section name as its class.
 
 ```html
 <div class="hello_world"></div>
 ```
 
-## Options
-
 By default, a section automatically includes partials, css, and js files with the section name if they exist.
-This convention can be overridden. The following example renders the _hello_world_ section with a different partial, with no stylesheet,
-and it uses the custom _foobar.js_ instead of _hello_world.js_.
+This convention can be overridden.
+
+
+### Customizing the filename of the section's partial.
 
 ```erb
-<%= section :hello_world, partial: 'hello_new', css: false, js: 'foobar.js' %>
+<%= section :hello_world, partial: 'another_partial' %>
 ```
 
-It is also possible to provide parameters to the rendered partial.
+
+### Customizing the filename of the assets
+
+To tell the section to use `foobar.js` instead of `hello_world.js`:
 
 ```erb
-<%= section :hello_world, locals: { message: 'Greetings!' } %>
+<%= section :hello_world, js: 'foobar.js' %>
 ```
 
-You can also provide a block to the section, which can be included into the partial by saying
 
+### Omitting assets
 
-## Inline blocks for sections.
+Sections can be told not not include their css or js file when rendered.
 
-You can provide a block to the section, like so:
+```erb
+<%= section :hello_world, css: false %>
+```
+
+### Providing parameters to the partial
 
 ```erb
-<%= section :section_with_block do %>
-  <h1>  Elaborate </h1>
-  <div> Block     </div>
-  <p>   content   </p>
-<% end %>
+<%= section :hello_world, locals: { message: 'Greetings!' } %>
 ```
 
-This block can be included into the partial:
+### Inline blocks for sections.
+
+You can provide a block to the section:
+
 ```erb
-Partial content...
-<%= yield %>
-Partial content...
+<%= section :info_window do %>
+  <h1>  inline  </h1>
+  <div> block   </div>
+  <p>   content </p>
+<% end %>
 ```
 
-This allows to define the content of parts of the section dynamically in the calling view, using view helper methods.
+This block can be included into the serverside partial of the section using `yield`.
 
 
-## Creating new sections.
+### Creating new sections.
 
-To create a new section, simply create a new folder under _/app/sections_ and add the partials, css, js, jst, and test files for this section.
-Alternatively, run the provided generator:
+To create a new section, simply create a new folder under _/app/sections_.
+There is also a generator for your convenience, which creates a whole scaffolded section.
 
 ```bash
 $ rails generate section admin/chart
 ```
 
-This creates a folder _/app/sections/admin/chart_ with a scaffold for a new section.
-
 
-# Unit tests for sections
+### Unit tests for sections
 
 Sections should also contain unit test files for the section.
 
-## Unit testing using Konacha
-
-_This feature is still under development._
-
-To test them for example using [Konacha](https://github.com/jfirebaugh/konacha), create a symlink to _app/sections_ in _spec/javascript_.
-
+To run your section tests using [Konacha](https://github.com/jfirebaugh/konacha), create a symlink to _app/sections_ in _spec/javascript_.
 
-# Development
 
-## Unit tests
+## How to contribute
 
-```bash
-$ rake
-```
+Feel free to send unit-tested pull requests! The unit tests of this project are run using `rake`.
 
-To automatically run unit tests when files change, run
 
-```bash
-$ bundle exec guard -c
-```
+### Missing features
 
-# Missing features
+_Sections_rails_ is far from complete. Some missing things are:
 
-_Sections_rails_ is in prototypical development and far from complete. Missing features are:
-
-* Better support for unit testing.
 * Support for multiple application assets, for example page-specific compiled asset files instead of one global one.
 * Support for serverside controller logic for sections, for example by integrating with https://github.com/apotonick/cells.
 * More natural integration into the asset pipeline.
 
+
+### Authors
+
+* [Kevin Goslar](https://github.com/kevgo)
+* [Serge Zinin](https://github.com/zininserge)

data/lib/sections_rails/section.rb

@@ -1,8 +1,14 @@
 module SectionsRails
   require "sections_rails/config"
   require 'sections_rails/partial_parser'
+  require 'sections_rails/section_asset_rendering'
+  require 'sections_rails/section_partial_rendering'
 
+
+  # Provides intelligent support for dealing with sections.
   class Section
+    include SectionAssetRenderering
+    include SectionPartialRendering
 
     def initialize section_name, view = nil, options = {}
       @section_name = section_name.to_s
@@ -24,122 +30,12 @@ module SectionsRails
       @filename ||= File.basename @section_name, '.*'
     end
 
-    # Path to the folder for asset includes.
-    # Example: 'folder/section'
-    def folder_includepath
-      @folder_includepath ||= File.join directory_name, filename
-    end
-
     # Path of the folder on the file system.
     # Example: 'app/sections/folder/section'
     def folder_filepath
       @folder_filepath ||= File.join SectionsRails.config.path, directory_name, filename
     end
 
-    # Path to access assets on the file system.
-    # Includes only the base name of assets, without extensions.
-    # Example: 'app/sections/folder/section/section'
-    def asset_filepath
-      @asset_filepath ||= File.join SectionsRails.config.path, asset_includepath
-    end
-
-    # Path for including assets into the web page.
-    #
-    def asset_includepath
-      @asset_includepath ||= File.join(directory_name, filename, filename).gsub(/^\//, '')
-    end
-
-    # The path for accessing the partial on the filesystem.
-    # Example: '
-    def partial_renderpath partial_filename = nil
-      File.join(directory_name, filename, partial_filename || filename).gsub(/^\//, '')
-    end
-
-    # The path for accessing the partial on the filesystem.
-    # Example: '
-    def partial_filepath partial_filename = nil
-      File.join(SectionsRails.config.path, directory_name,filename, "_#{partial_filename or filename}").gsub(/^\//, '')
-    end
-
-    # For including the partial into views.
-    def partial_includepath
-      @partial_includepath ||= File.join(directory_name, filename, "#{filename}").gsub(/^\//, '')
-    end
-
-    # Returns the content of this sections partial.
-    def partial_content
-      return @partial_content if @has_partial_content
-      @has_partial_content = true
-      if (partial_path = find_partial_filepath)
-        @partial_content = IO.read partial_path
-      end
-    end
-
-    # Returns the asset path of asset with the given extensions.
-    # Helper method.
-    def find_asset_includepath asset_option, extensions
-      return nil if asset_option == false
-      return asset_option if asset_option
-      extensions.each do |ext|
-        file_path = "#{asset_filepath}.#{ext}"
-        return asset_includepath if File.exists? file_path
-      end
-      nil
-    end
-
-    # Returns the path to the JS asset of this section, or nil if the section doesn't have one.
-    def find_css_includepath
-      @find_css_includepath ||= find_asset_includepath @options[:css], SectionsRails.config.css_extensions
-    end
-
-    # Returns the path to the JS asset of this section, or nil if the section doesn't have one.
-    def find_js_includepath
-      @find_js_includepath ||= find_asset_includepath @options[:js], SectionsRails.config.js_extensions
-    end
-
-    # Returns the filename of the partial of this section, or nil if this section has no partial.
-    # Uses the given custom partial name, or the default partial name if none is given.
-    def find_partial_filepath partial_filename = nil
-      SectionsRails.config.partial_extensions.each do |ext|
-        path = "#{partial_filepath(filename)}.#{ext}"
-        return path if File.exists? path
-      end
-      nil
-    end
-
-    # Returns the path of the partial of this section for rendering, or nil if this section has no partial.
-    # Uses the given custom partial name, or the default partial name if none is given.
-    def find_partial_renderpath partial_filename = nil
-      SectionsRails.config.partial_extensions.each do |ext|
-        return partial_renderpath(partial_filename) if File.exists? "#{partial_filepath(filename)}.#{ext}"
-      end
-      nil
-    end
-
-    # TODO: replace this with find_asset.
-    def has_asset? *extensions
-      extensions.flatten.each do |ext|
-        return true if File.exists?("#{asset_filepath}.#{ext}")
-      end
-      false
-    end
-
-    # TODO: replace this with find_asset.
-    def has_default_js_asset?
-      has_asset? SectionsRails.config.js_extensions
-    end
-
-    # TODO: replace this with find_asset.
-    def has_default_style_asset?
-      has_asset? SectionsRails.config.css_extensions
-    end
-
-    # Returns whether this section has a template.
-    # Deprecated.
-    def has_partial?
-      @view.lookup_context.template_exists? partial_includepath
-    end
-
     # Returns the sections that this section references.
     # If 'recursive = true' is given, searches recursively for sections referenced by the referenced sections.
     # Otherwise, simply returns the sections that are referenced by this section.
@@ -158,73 +54,14 @@ module SectionsRails
       result.sort!
     end
 
-    def render &block
-      result = []
 
-      # Check if section exists.
+    # Renders this section, i.e. returns the HTML for this section.
+    def render &block
       raise "Section #{folder_filepath} doesn't exist." unless Dir.exists? folder_filepath
 
-      # Include assets only for development mode.
-      if Rails.env != 'production'
-
-        # Include JS assets.
-        if @options.has_key? :js
-          if @options[:js]
-            result << @view.javascript_include_tag(File.join(folder_includepath, @options[:js]))
-          else
-            # :js => (false|nil) given --> don't include any JS.
-          end
-        else
-          # No :js configuration option given --> include the default script.
-          js_includepath = find_js_includepath
-          result << @view.javascript_include_tag(js_includepath) if js_includepath
-        end
-
-        # Include CSS assets.
-        if @options.has_key? :css
-          if @options[:css]
-            # Custom filename for :css given --> include the given CSS file.
-            result << @view.stylesheet_link_tag(File.join(folder_includepath, @options[:css]))
-          else
-            # ":css => false" given --> don't include any CSS.
-          end
-        else
-          # No option for :css given --> include the default stylesheet.
-          css_includepath = find_css_includepath
-          result << @view.stylesheet_link_tag(css_includepath) if css_includepath
-        end
-      end
-
-      # Render the section partial into the view.
-      if @options.has_key? :partial
-        if @options[:partial] == :tag
-          # :partial => :tag given --> render the empty tag even if there is a partial present.
-          result << @view.content_tag(:div, '', :class => filename)
-        elsif @options[:partial]
-          # Custom partial name given --> render that partial.
-          if block_given?
-            result << @view.render({:layout => find_partial_renderpath(@options[:partial])}, @options[:locals], &block)
-          else
-            result << @view.render(find_partial_renderpath(@options[:partial]), @options[:locals])
-          end
-        else
-          # :partial => (false|nil) given --> render nothing.
-        end
-      else
-        # No :partial option given --> render the default partial.
-        partial_filepath = find_partial_filepath
-        if partial_filepath
-
-          if block_given?
-            result << @view.render(:layout => partial_includepath, :locals => @options[:locals], &block)
-          else
-            result << @view.render(:partial => partial_includepath, :locals => @options[:locals])
-          end
-        else
-          result << @view.content_tag(:div, '', :class => filename)
-        end
-      end
-
+      result = []
+      render_assets result if Rails.env != 'production'
+      render_partial result, &block
       result.join("\n").html_safe
     end
   end

data/lib/sections_rails/section_asset_rendering.rb

@@ -0,0 +1,92 @@
+module SectionsRails
+
+  # Helps with rendering the assets of a section.
+  module SectionAssetRenderering
+    extend ActiveSupport::Concern
+
+    included do
+
+      # Path to access assets on the file system.
+      # Includes only the base name of assets, without extensions.
+      # Example: 'app/sections/folder/section/section'
+      def asset_filepath
+        @asset_filepath ||= File.join SectionsRails.config.path, asset_includepath
+      end
+
+      # Path for including assets into the web page.
+      #
+      def asset_includepath
+        @asset_includepath ||= File.join(directory_name, filename, filename).gsub(/^\//, '')
+      end
+
+
+      # Returns the path to the JS asset of this section, or nil if the section doesn't have one.
+      def find_js_includepath
+        @find_js_includepath ||= find_asset_includepath @options[:js], SectionsRails.config.js_extensions
+      end
+
+
+      # Returns the asset path of asset with the given extensions.
+      # Helper method.
+      def find_asset_includepath asset_option, extensions
+        return nil if asset_option == false
+        return asset_option if asset_option
+        extensions.each do |ext|
+          file_path = "#{asset_filepath}.#{ext}"
+          return asset_includepath if File.exists? file_path
+        end
+        nil
+      end
+
+      # Returns the path to the JS asset of this section, or nil if the section doesn't have one.
+      def find_css_includepath
+        @find_css_includepath ||= find_asset_includepath @options[:css], SectionsRails.config.css_extensions
+      end
+
+
+      # Path to the folder for asset includes.
+      # Example: 'folder/section'
+      def folder_includepath
+        @folder_includepath ||= File.join directory_name, filename
+      end
+
+
+      # Renders the assets of this section into the given result.
+      def render_assets result
+        render_js_assets result
+        render_css_assets result
+      end
+
+      # Renders the CSS for this section.
+      def render_css_assets result
+        if @options.has_key? :css
+          if @options[:css]
+            # Custom filename for :css given --> include the given CSS file.
+            result << @view.stylesheet_link_tag(File.join(folder_includepath, @options[:css]))
+          else
+            # ":css => false" given --> don't include any CSS.
+          end
+        else
+          # No option for :css given --> include the default stylesheet.
+          css_includepath = find_css_includepath
+          result << @view.stylesheet_link_tag(css_includepath) if css_includepath
+        end
+      end
+
+      # Renders the JS for this section.
+      def render_js_assets result
+        if @options.has_key? :js
+          if @options[:js]
+            result << @view.javascript_include_tag(File.join(folder_includepath, @options[:js]))
+          else
+            # :js => (false|nil) given --> don't include any JS.
+          end
+        else
+          # No :js configuration option given --> include the default script.
+          js_includepath = find_js_includepath
+          result << @view.javascript_include_tag(js_includepath) if js_includepath
+        end
+      end
+    end
+  end
+end

data/lib/sections_rails/section_partial_rendering.rb

@@ -0,0 +1,100 @@
+module SectionsRails
+
+  # Helps with rendering partials of sections.
+  module SectionPartialRendering
+    extend ActiveSupport::Concern
+
+    included do
+
+      # The path for accessing the partial on the filesystem.
+      # Example: '
+      def partial_renderpath partial_filename = nil
+        File.join(directory_name, filename, partial_filename || filename).gsub(/^\//, '')
+      end
+
+      # The path for accessing the partial on the filesystem.
+      # Example: '
+      def partial_filepath partial_filename = nil
+        File.join(SectionsRails.config.path, directory_name, filename, "_#{partial_filename or filename}").gsub(/^\//, '')
+      end
+
+      # For including the partial into views.
+      def partial_includepath
+        @partial_includepath ||= File.join(directory_name, filename, "#{filename}").gsub(/^\//, '')
+      end
+
+      # Returns the content of this sections partial.
+      def partial_content
+        return @partial_content if @has_partial_content
+        @has_partial_content = true
+        if (partial_path = find_partial_filepath)
+          @partial_content = IO.read partial_path
+        end
+      end
+
+      # Returns the filename of the partial of this section, or nil if this section has no partial.
+      # Uses the given custom partial name, or the default partial name if none is given.
+      def find_partial_filepath partial_filename = nil
+        SectionsRails.config.partial_extensions.each do |ext|
+          path = "#{partial_filepath(filename)}.#{ext}"
+          return path if File.exists? path
+        end
+        nil
+      end
+
+      # Returns the path of the partial of this section for rendering, or nil if this section has no partial.
+      # Uses the given custom partial name, or the default partial name if none is given.
+      def find_partial_renderpath partial_filename = nil
+        SectionsRails.config.partial_extensions.each do |ext|
+          return partial_renderpath(partial_filename) if File.exists? "#{partial_filepath(filename)}.#{ext}"
+        end
+        nil
+      end
+
+
+      # Renders the section partial into the view.
+      def render_partial result, &block
+        if @options.has_key? :partial
+          if @options[:partial] == :tag
+            # :partial => :tag given
+            render_empty_tag result
+          elsif @options[:partial]
+            # Custom partial name given
+            render_custom_partial  result, &block
+          else
+            # :partial => (false|nil) given --> render nothing.
+          end
+        else
+          # No :partial option given
+          render_default_partial result, &block
+        end
+      end
+
+      def render_custom_partial result, &block
+        if block_given?
+          result << @view.render({:layout => find_partial_renderpath(@options[:partial])}, @options[:locals], &block)
+        else
+          result << @view.render(find_partial_renderpath(@options[:partial]), @options[:locals])
+        end
+      end
+
+      def render_default_partial result, &block
+        partial_filepath = find_partial_filepath
+        if partial_filepath
+
+          if block_given?
+            result << @view.render(:layout => partial_includepath, :locals => @options[:locals], &block)
+          else
+            result << @view.render(:partial => partial_includepath, :locals => @options[:locals])
+          end
+        else
+          result << @view.content_tag(:div, '', :class => filename)
+        end
+      end
+
+      def render_empty_tag result
+        result << @view.content_tag(:div, '', :class => filename)
+      end
+    end
+  end
+end

data/lib/sections_rails/version.rb

@@ -1,3 +1,3 @@
 module SectionsRails
-  VERSION = "0.7.1"
+  VERSION = "0.7.2"
 end