sections_rails 0.0.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2011 Kevin Goslar
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,97 @@
+Ruby on Rails provides an amazing infrastructure and conventions for well structured server-side code. 
+It falls, however, short for the view layer. 
+
+_Partials_ provide a nice way to represent the HTML code of individual sections within complex web pages, 
+but no such facilities are available for the corresponding CSS and JavaScript. 
+This leaves the task of organizing the JS and CSS completely up to the user.
+
+_Sections_rails_ fills this gap by adding 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.
+
+
+# Example
+
+Let's assume a web page has amongst other things a navigation menu.
+This menu requires certain HTML, CSS, and JavaScript code that is specific to it.
+_Sections_rails_ allows to define this code as a _section_ inside the _/app_ folder:
+
+    /app/sections/menu/_menu.html.erb
+                       menu.css
+                       menu.js
+
+To display this menu, simply do this in your view:
+
+    <%= section :menu %>
+
+This inserts the partial as well as the JS and CSS files from _/app/sections/menu_ at this location.
+
+
+# Installation
+
+In your Gemfile:
+
+    gem 'sections_rails'
+
+Then set up the directory structure:
+
+    $ rails generate sections
+
+The generator does the following things:
+
+1.  It 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:
+
+        config.assets.paths << 'app/sections'
+
+3.  It optionally creates a demo section called _hello_world_.
+
+
+# Usage
+
+To use the "hello_world" section created by the sections generator, simply add it to the view:
+
+    <%= section :hello_world %>
+
+If your section renders itself completely in JavaScript, you can omit its partial file.
+In this case, the _sections_ command creates an empty div in the view.
+
+    <div class="hello_world"></div>
+
+
+## Asset precompilation
+
+_Sections_rails_ provides facilities to include the assets of sections in the global asset
+bundles for production mode.
+
+1.  Run __rake sections:prepare__
+    
+    This rake task creates helper files that tell the asset pipeline about the assets of the different sections.
+
+    * _/app/assets/javascripts/application_sections.js_ links to all JS files of all sections.
+    * _/app/assets/stylesheets/application_sections.js_ links to all CSS files of all sections.
+
+2.  Include the generated helper files into your _application.js_ and _application.css_ files.
+
+    In application.js:
+    
+        //= require application_sections
+
+    In application.css:
+    
+        /*= require application_sections */    
+
+3.  Run __rake assets:precompile__ as usual.
+
+
+# Missing features
+
+_Sections_rails_ is in early development and far from complete. Missing features are:
+
+* Support for multiple assets, and assets per section
+* support for assets in different formats like CoffeeScript, Haml, Sass etc.
+* Support for page-specific compiled asset files instead of one global one
+* Better integration into the asset precompilation workflow.
+* Include serverside controller logic for sections by integrating with https://github.com/apotonick/cells or something comparable

data/Rakefile

@@ -0,0 +1,39 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'SectionsRails'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+desc 'Default: run the specs and features.'
+task :default => 'spec:unit' do
+  system("bundle exec rake spec")
+end
+
+namespace :spec do
+
+  desc "Run unit specs"
+  RSpec::Core::RakeTask.new('unit') do |t|
+    t.pattern = 'spec/{*_spec.rb}'
+  end
+end
+
+desc "Run the unit tests"
+task :spec => ['spec:unit']

data/lib/generators/sections_generator.rb

@@ -0,0 +1,70 @@
+class SectionsGenerator < Rails::Generators::Base
+
+  def create_sections_folder
+    empty_directory "app/sections"
+    inject_into_file 'config/application.rb',
+                     "    config.assets.paths << 'app/sections'\n",
+                     :after => /config.assets.enabled\s*=.*\n/
+    say ''
+    say ' I have made some modifications to '
+    say 'config/application.rb', Thor::Shell::Color::BOLD
+    say ' Please review them before submitting these changes to your code repository.'
+    say ''
+  end
+  
+  def create_sample_section
+    
+    # Ask the user.
+    return unless ['', 'y', 'yes'].include? ask('Do you want to create a sample section? [Yn]').downcase
+
+    # Create the sample section directory.
+    empty_directory "app/sections/hello_world"
+
+    # Create the partial.
+    create_file "app/sections/hello_world/_hello_world.html.erb", <<-END_STR
+<!-- This file contains the HTML for the 'hello world' section. -->
+
+<div class="hello_world">
+  <h2>Hello World!</h2>
+  This is content inside the hello world section!
+</div>
+    END_STR
+
+    # Create the CSS file.
+    create_file "app/sections/hello_world/hello_world.css", <<-END_STR
+/* 
+ * This file contains the CSS for the 'hello world' section. 
+ *
+ * Please note that all CSS in here should be relative to the container of the section,
+ * in this case the ".hello" class.
+ */
+
+.hello_world { width: 300px; padding: 0 2ex 2ex; border: 2px dotted red; background-color: yellow; }
+.hello_world .h2 { font-size: 1em; margin: 0 0 1ex; padding: 0; }
+    END_STR
+    
+    # Create the JS file.
+    create_file "app/sections/hello_world/hello_world.js", <<-END_STR
+/*
+ * This file contains the JavaScript for the 'hello world' section.
+ *
+ * Anything in here should be restrained to within the container of the section,
+ * i.e. the <div> with the class 'hello_world'.
+ */
+
+$('.hello_world').click(function() {
+  alert('The Hello World section says hello to the world! :)');
+});
+    END_STR
+
+    say ''
+    say ' A sample section has been created in '
+    say 'app/sections/sample_section', Thor::Shell::Color::BOLD
+    say ' To use it, simply put '
+    say '<%= section :sample %>', Thor::Shell::Color::BOLD
+    say ' in your view file.'
+    say ''
+    say ' Happy coding! :)'
+    say ''
+  end
+end

data/lib/sections_rails.rb

@@ -0,0 +1,19 @@
+module SectionsRails
+
+  require "sections_rails/railtie" if defined?(Rails)
+  
+  def section name
+    out = []
+    out << javascript_include_tag("#{name}/#{name}") if File.exists? "#{Rails.root}/app/sections/#{name}/#{name}.js"
+    out << stylesheet_link_tag("#{name}/#{name}") if File.exists? "#{Rails.root}/app/sections/#{name}/#{name}.css"
+    if File.exists? "#{Rails.root}/app/sections/#{name}/_#{name}.html.erb" 
+      out << render(:partial => "/../sections/#{name}/#{name}")
+    else
+      out << "<div class=\"#{name}\"></div>"
+    end
+    out.join("\n").html_safe
+  end
+  
+end
+
+ActionView::Base.send :include, SectionsRails

data/lib/sections_rails/railtie.rb

@@ -0,0 +1,9 @@
+require "rails/railtie"
+module SectionsRails
+  class Railtie < Rails::Railtie
+
+    rake_tasks do
+      load "tasks/sections_rails_tasks.rake"
+    end
+  end
+end

data/lib/sections_rails/version.rb

@@ -0,0 +1,3 @@
+module SectionsRails
+  VERSION = "0.0.2"
+end

data/lib/tasks/sections_rails_tasks.rake

@@ -0,0 +1,102 @@
+namespace :sections do 
+
+  desc "Prepares the assets for precompilation in a setup with a single application.js file"
+  task :prepare do
+
+    # Find all views in this app.
+    views = find_all_views 'app/views'
+    
+    # Get all sections used in the views.
+    sections = views.map do |view|
+      find_sections_in_view IO.read "app/views/#{view}"
+    end.flatten
+    
+    # Create the require file for application.js.
+    File.open "app/assets/javascripts/application_sections.js", 'w' do |file|
+      file.write "// THIS FILE IS AUTOMATICALLY CREATED BY THE SECTIONS PLUGIN.\n"
+      file.write "// PLEASE DO NOT MODIFY MANUALLY.\n"
+      file.write "//\n"
+      sections.each do |section|
+        if File.exists? "app/sections/#{section}/#{section}.js"
+          file.write "//= require ../../sections/#{section}/#{section} \n"
+        end
+      end
+    end
+    
+    # Create the require file for application.css.
+    File.open "app/assets/stylesheets/application_sections.css", 'w' do |file|
+      file.write "/* \n"
+      file.write " * THIS FILE IS AUTOMATICALLY CREATED BY THE SECTIONS PLUGIN.\n"
+      file.write " * PLEASE DO NOT MODIFY MANUALLY.\n"
+      file.write " *\n"
+      sections.each do |section|
+        if File.exists? "app/sections/#{section}/#{section}.css"
+          file.write " *= require ../../sections/#{section}/#{section}\n" 
+        end
+      end
+      file.write "*/"
+    end
+    
+    # Make sure the require files are properly linked.
+    unless file_contains 'app/assets/javascripts/application.js', /application_sections/
+      puts "Please add the 'require' statement to 'application_sections.js' to 'application.js'."
+    end
+    unless file_contains 'app/assets/stylesheets/application.css', /application_sections/
+      puts "Please add the 'require' statement to 'application_sections.css' to 'application.css'."
+    end
+  end
+
+  desc "Prepares the assets for precompilation in a setup with multiple files per page."
+  task :prepare_pages do
+    root = 'app/views'
+
+    views = find_all_views root
+    sections_per_view = parse_views views
+    
+    # Create the require files.
+    sections_per_view.each do |view, sections|
+
+      # Don't do anything if there are no sections in this view.
+      next if sections.blank?
+      
+      # Don't do anything if the page has no page-specific JS file.
+      root_name = view[0..-10]
+      puts root_name
+      next unless File.exists? "app/pages/#{view}.js"
+    end
+  end  
+
+  # Returns an array with the file name of all views in the given directory.
+  # Views are all files that end in .html.erb
+  def find_all_views root
+    result = []
+    Dir.entries(root).each do |dir|
+      next if ['.', '..', 'layouts'].include? dir      
+      Dir.entries(File.join(root, dir)).each do |view_file|
+        next if ['.', '..'].include? view_file
+        result << File.join(dir, view_file)
+      end
+    end
+    result
+  end
+
+  def parse_views views
+    result = {}
+    views_to_parse.each do |view_to_parse|
+      view_text = IO.read(File.join root, view_to_parse)
+      result[view_to_parse] = find_sections_in_view view_text
+    end
+    result
+  end
+  
+  # Returns an array with the name of all sections in the given view source.
+  def find_sections_in_view view_text
+    view_text.scan(/<%= section\s+['"](.*?)['"]\s*%>/).flatten.sort.uniq
+  end
+  
+  # Returns whether the given file contains the given text somewhere in its content.
+  def file_contains file_name, text
+    IO.read(file_name) =~ text
+  end
+  
+end

data/spec/dummy/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks

data/spec/dummy/app/assets/javascripts/application.js

@@ -0,0 +1,9 @@
+// This is a manifest file that'll be compiled into including all the files listed below.
+// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
+// be included in the compiled file accessible from http://example.com/assets/application.js
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

data/spec/dummy/app/assets/stylesheets/application.css

@@ -0,0 +1,7 @@
+/*
+ * This is a manifest file that'll automatically include all the stylesheets available in this directory
+ * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
+ * the top of the compiled file, but it's generally better to create a new file per style scope.
+ *= require_self
+ *= require_tree . 
+*/

data/spec/dummy/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+end

data/spec/dummy/app/controllers/demos_controller.rb

@@ -0,0 +1,5 @@
+class DemosController < ApplicationController
+  def index
+  end
+
+end

data/spec/dummy/app/helpers/application_helper.rb

@@ -0,0 +1,2 @@
+module ApplicationHelper
+end

data/spec/dummy/app/sections/hello_world/_hello_world.html.erb

@@ -0,0 +1,6 @@
+<!-- This file contains the HTML for the 'hello world' section. -->
+
+<div class="hello_world">
+  <h2>Hello World!</h2>
+  This is content inside the hello world section!
+</div>

data/spec/dummy/app/sections/hello_world/hello_world.css

@@ -0,0 +1,9 @@
+/* 
+ * This file contains the CSS for the 'hello world' section. 
+ *
+ * Please note that all CSS in here should be relative to the container of the section,
+ * in this case the ".hello" class.
+ */
+
+.hello_world { width: 300px; padding: 0 2ex 2ex; border: 2px dotted red; background-color: yellow; }
+.hello_world .h2 { font-size: 1em; margin: 0 0 1ex; padding: 0; }

data/spec/dummy/app/sections/hello_world/hello_world.js

@@ -0,0 +1,10 @@
+/*
+ * This file contains the JavaScript for the 'hello world' section.
+ *
+ * Anything in here should be restrained to within the container of the section,
+ * i.e. the <div> with the class 'hello_world'.
+ */
+
+$('.hello_world').click(function() {
+  alert('The Hello World section says hello to the world! :)');
+});