sections_rails 0.3.0 → 0.5.0

data/README.md

@@ -1,6 +1,8 @@
-_Sections_rails_ adds a component-oriented infrastructure to the view layer of Ruby on Rails.
-This allows to define and use the HTML, CSS, and JavaScript code of dedicated 
-sections of web pages together in one place.
+_SectionsRails_ adds a component-oriented infrastructure to the view layer of Ruby on 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.
 
 
 # Example
@@ -10,24 +12,39 @@ 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.
 
+Traditionally, these files are defined in this directory structure:
+
+```
+/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
+```
+
 _Sections_rails_ allows to define these assets together, as a _section_ inside the _/app_ folder:
 
-    /app/sections/menu/_menu.html.erb
-                       menu.css
-                       menu.js
+    /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.
 
-To display this menu, simply do this in your view:
+To embed this menu and all its assets into a page, simply do this in your view:
 
 ```erb
 <%= section :menu %>
 ```
 
-The _section_ helper inserts the partial as well as the JS and CSS files from _/app/sections/menu_ at this location.
-It does the right thing in all circumstances: In development mode, it inserts the individual assets. 
-In production mode, it inserts the assets to the main _application.js_ bundle.
+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.
 
 The gem source comes with a bundled example Rails app in the _demo/_ directory. 
-It provides a working example of a section in action in _views/demos/index.html.erb_.
+It provides several working examples of sections in action in _views/demos/index.html.erb_.
 
 
 # Installation
@@ -77,13 +94,45 @@ In this case, the _sections_ helper creates an empty div in the view.
 <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 by the options __:partial__, __:css__, and __:js__ the `section` command.
+Providing `false` disables the respective functionality, while a filename makes the section use the given file instead of the default one.
+
+The command ```erb <%= section :hello_world, css: false, js: 'foobar.js' %>``` renders the _hello_world_ section without styling and using
+_foobar.js_ instead of _hello_world.js_.
+
+
+## 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:
+
+```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
+
+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_.
+
 
 # Missing features
 
 _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 assets in different formats like CoffeeScript, Haml, Sass etc.
 * Support for serverside controller logic for sections, for example by integrating with https://github.com/apotonick/cells.
 * More natural integration into the asset pipeline.
 

data/lib/sections_rails/version.rb

@@ -1,3 +1,3 @@
 module SectionsRails
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/sections_rails.rb

@@ -2,7 +2,7 @@ module SectionsRails
 
   require "sections_rails/railtie" if defined?(Rails)
   
-  def section combined_name
+  def section combined_name, options = {}
     out = []
 
     # Split the parameter into file name and directory name.
@@ -15,18 +15,50 @@ module SectionsRails
     # Add assets of section when in dev mode.
     file_path = "#{directory_path}/#{filename}"                              # Base path of filename in section: /app/sections/admin/logo/logo
     if Rails.env != 'production'
-      out << javascript_include_tag("#{directory}#{filename}/#{filename}") if File.exists?("#{file_path}.js") || File.exists?("#{file_path}.js.coffee") || File.exists?("#{file_path}.coffee")
-      out << stylesheet_link_tag("#{directory}#{filename}/#{filename}") if File.exists?("#{file_path}.css") || File.exists?("#{file_path}.css.scss") || File.exists?("#{file_path}.css.sass") || File.exists?("#{file_path}.scss") || File.exists?("#{file_path}.sass") 
+
+      # Include JS assets.
+      if options.has_key? :js
+        if options[:js]
+          out << javascript_include_tag("#{directory}#{filename}/#{options[:js]}")
+        end
+      else
+        if File.exists?("#{file_path}.js") || File.exists?("#{file_path}.js.coffee") || File.exists?("#{file_path}.coffee")
+          out << javascript_include_tag("#{directory}#{filename}/#{filename}")
+        end
+      end
+
+      # Include CSS assets.
+      if options.has_key? :css
+        if options[:css]
+          out << stylesheet_link_tag("#{directory}#{filename}/#{options[:css]}")
+        end
+      else
+        if File.exists?("#{file_path}.css") || File.exists?("#{file_path}.css.scss") || File.exists?("#{file_path}.css.sass") || File.exists?("#{file_path}.scss") || File.exists?("#{file_path}.sass") 
+          out << stylesheet_link_tag("#{directory}#{filename}/#{filename}")
+        end
+      end
     end
 
     # Render the section partial into the view.
     partial_path = "#{directory_path}/_#{filename}.html"
-    if File.exists?("#{partial_path}.erb") || File.exists?("#{partial_path}.haml")
-      out << render(:partial => "/../sections/#{directory}#{filename}/#{filename}")
+    if options.has_key? :partial
+      if options[:partial] == :tag
+        # :partial => :tag given --> render the tag.
+        out << content_tag(:div, '', :class => filename)
+      elsif options[:partial]
+        # some value for :partial given --> render the given partial.
+        out << render(:partial => "/../sections/#{directory}#{filename}/#{filename}")
+      else
+        # :partial => false given --> render nothing
+      end
     else
-      out << content_tag(:div, '', :class => filename)
+      # No :partial option given --> render the file or tag per convention.
+      if File.exists?("#{partial_path}.erb") || File.exists?("#{partial_path}.haml")
+        out << render(:partial => "/../sections/#{directory}#{filename}/#{filename}")
+      else
+        out << content_tag(:div, '', :class => filename)
+      end
     end
-
     out.join("\n").html_safe
   end
   

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sections_rails
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-29 00:00:00.000000000 Z
+date: 2012-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
-  requirement: &70259643113940 !ruby/object:Gem::Requirement
+  requirement: &70129622938640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70259643113940
+  version_requirements: *70129622938640
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70259643113080 !ruby/object:Gem::Requirement
+  requirement: &70129622938060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70259643113080
+  version_requirements: *70129622938060
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &70259643112020 !ruby/object:Gem::Requirement
+  requirement: &70129622937560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +43,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70259643112020
+  version_requirements: *70129622937560
 description: Sections_rails adds infrastructure to the view layer of Ruby on Rails.
   It allows to define and use the HTML, CSS, and JavaScript code of dedicated sections
   of pages together in one place.