RubyGems - adamh-html_namespacing - Versions diffs - 0.0.4 → 0.0.5 - Mend

adamh-html_namespacing 0.0.4 → 0.0.5

Files changed (9) hide show

data/Manifest +2 -0
data/README.rdoc +101 -27
data/Rakefile +1 -1
data/html_namespacing.gemspec +3 -3
data/lib/html_namespacing/plugin/rails.rb +2 -2
data/lib/html_namespacing/plugin/sass.rb +76 -0
data/lib/html_namespacing/plugin.rb +12 -0
data/lib/html_namespacing.rb +1 -2
metadata +4 -2

data/Manifest CHANGED Viewed

@@ -7,6 +7,8 @@ ext/html_namespacing/html_namespacing.h
 ext/html_namespacing/html_namespacing.c
 ext/html_namespacing/html_namespacing_ext.c
 lib/html_namespacing.rb
+lib/html_namespacing/plugin.rb
 lib/html_namespacing/plugin/rails.rb
+lib/html_namespacing/plugin/sass.rb
 Manifest
 html_namespacing.gemspec

data/README.rdoc CHANGED Viewed

@@ -3,6 +3,10 @@
 HTML Namespacing automatically adds HTML class attributes to partial HTML
 code.
+The intent is for HTML, CSS, and JavaScript files to be "namespaced" according
+to their location in the filesystem. That way, CSS and JavaScript can be scoped
+to individual HTML files--even automatically.
 == Installing
   gem install adamh-html_namespacing --source http://gems.github.com
@@ -21,21 +25,14 @@ HTML Namespacing can be used on its own for a snippet of code:
 == Details
-HTML namespacing expects valid, properly-nested HTML (not XML). It has no
-effect on doctype tags, XML declaration, comments, and the HTML tags which do
-not support the <tt>class</tt> attribute: <tt>html</tt>, <tt>head</tt>,
-<tt>base</tt>, <tt>meta</tt>, <tt>title</tt>, <tt>link</tt>, <tt>script</tt>,
-<tt>noscript</tt>, <tt>style</tt>.
-Only the root tags of the partial HTML will be namespaced. For instance, all
-<tt>p</tt> tags in this example will have a class added, but no other tags:
+Only root tags will be namespaced. For instance, all <tt>p</tt> tags in this
+example will have a class added, but no other tags:
   <p>This is a root tag. <b>This tag is nested.</b></p>
   <p>This is another root tag.</p>
-Remember, <tt>html</tt> (and other HTML tags which do not allow the
-<tt>class</tt> attribute) will be ignored. This HTML will pass through
-unchanged:
+Because XML, DOCTYPE, comments, and <tt>html</tt> tags do not allow the
+<tt>class</tt> attribute, the following HTML will pass through unchanged:
   <?xml version="1.0"?>
   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
@@ -50,13 +47,17 @@ unchanged:
     </body>
   </html>
+(The following elements do not support the <tt>class</tt> attribute:
+<tt>html</tt>, <tt>head</tt>, <tt>base</tt>, <tt>meta</tt>, <tt>title</tt>,
+<tt>link</tt>, <tt>script</tt>, <tt>noscript</tt>, <tt>style</tt>.)
 Though the actual namespacing functions are written in pure C with no
 dependencies, only Ruby bindings are available at this time.
-== Integrating in your Project
+== Integrating in a Rails project
-More likely, you want to integrate HTML namespacing into a framework. Here is
-a Rails example:
+HTML namespacing is meant to integrate into a framework. Here is a Rails
+example:
 In <tt>config/environment.rb</tt>:
@@ -74,9 +75,9 @@ Now, all templates will have HTML namespacing applied. For instance, with a
     <%=h @foo.name %>
   </p>
-  <%= render(:partial => 'details', :locals => { :foo => @foo }) %>
+  <%= render(:partial => @foo) %>
-  <%= link_to 'Edit', foo_edit_path(@foo) %> |
+  <%= link_to 'Edit', edit_foo_path(@foo) %> |
   <%= link_to 'Back', foos_path %>
 The following HTML might be generated (depending on the <tt>_details</tt>
@@ -87,7 +88,7 @@ partial and the data in the actual <tt>Foo</tt> object):
     Foo
   </p>
-  <p class="foos-_details foos-show">
+  <p class="foos-_foo foos-show">
     <b>Description:</b>
     Bar
   </p>
@@ -95,12 +96,59 @@ partial and the data in the actual <tt>Foo</tt> object):
   <a href="/foos/1/edit" class="hellos-show">Edit</a> |
   <a href="/foos" class="hellos-show">Back</a>
-Rails will integrate with all HTML templates, regardless of their
-implementation; feel free to use Haml.
+== Integrating with Haml and Sass in Rails
+With Haml:http://haml-lang.com/ and Sass:http://sass-lang.com/ namespacing can
+be automated even further.
+In your Rails project, implement the following:
+In <tt>config/environment.rb</tt>:
+  config.gem 'haml', :version => '2.2.0'
+  config.gem 'adamh-html_namespacing', :library => 'html_namespacing'
+In <tt>config/initializers/html_namespacing.rb</tt>:
+  HtmlNamespacing::Plugin::Rails.install
+  HtmlNamespacing::Plugin::Sass.install
+Then add <tt>stylesheet_link_tag(:all, :recursive => true)</tt> to your layout.
+Now, all templates will have HTML namespacing applied, and Sass files in
+<tt>SASS_DIR/views</tt> (where <tt>SASS_DIR</tt> is Sass's
+<tt>:template_location</tt>, default <tt>public/stylesheets/sass</tt>) will
+also be HTML-namespaced. For example:
+With a partial, <tt>app/views/foos/show.html.haml</tt> like this:
+  %p
+    %strong Name:
+    %span.name&= @foo.name
+  = render(:partial => @foo)
+  = link_to('Edit', edit_foo_path(@foo)
+  |
+  = link_to('Back', foos_path
+And a Sass file in <tt>public/stylesheets/sass/views/foos/show.sass</tt>:
+  strong
+    :font-size 1.3em
+  span.name
+    :font-style italic
+  a&
+    :font-weight bold
+The Sass rules will only apply to their corresponding partial.
+(Note: to target root-level elements in a Sass partial, use the "&" rule,
+which is standard Sass and will equate to ".NAMESPACE" in this context.)
 === Options
-Available options to <tt>install</tt> are:
+Available options to <tt>HtmlNamespacing::Plugin::Rails.install</tt> are:
 <tt>:template_to_namespace_callback</tt>: Ruby lambda function which accepts an
 <tt>ActionView::Template</tt> and returns an HTML namespacing string. The
@@ -119,6 +167,14 @@ an <tt>Exception</tt>, an <tt>ActionView::Template</tt>, and an
 If your <tt>:handle_exception_callback</tt> does not raise an exception,
 the template will be rendered as if HtmlNamespacing were not installed.
+Available options to <tt>HtmlNamespacing::Plugin::Sass.install</tt> are:
+<tt>:prefix</tt> (default <tt>views</tt>): subdirectory of Sass directory for
+which we want to namespace our Sass.
+<tt>:callback</tt>: See <tt>:template_to_namespace_callback</tt> above; this
+callback is similar, though it accepts a string path rather than an
+<tt>ActionView::Template</tt>.
 == Why?
 HTML namespacing gives huge benefits when writing CSS and JavaScript:
@@ -237,9 +293,9 @@ rename or move the partial.
 == Tips and Tricks
 You may find that HTML namespacing works best when each HTML partial is wrapped
-in its own <tt>div</tt> tag. Both CSS's child selectors and jQuery's <tt>find()</tt> function
-will ordinarily ignore the element with the namespace class, only selecting
-sub-elements. For instance, with this HTML:
+in its own <tt>div</tt> tag. Both CSS's child selectors and jQuery's
+<tt>find()</tt> function will ordinarily ignore the element with the namespace
+class, only selecting sub-elements. For instance, with this HTML:
   <div class="foos-show">
     <p>Hello</p>
@@ -249,6 +305,11 @@ If you wrote the following CSS:
   .foos-show div { font-weight: bold; }
+Or this Sass:
+  div
+    :font-weight bold
 Or the following JavaScript (following the <tt>$NS</tt> example above):
   var $div = $NS.find('div');
@@ -258,6 +319,11 @@ would need the following CSS:
   div.foos-show { font-weight: bold; }
+Or this sass:
+  div&
+    :font-weight bold
 Or the following JavaScript:
   var $div = $NS.filter('div');
@@ -266,10 +332,18 @@ Also, watch out for nesting: selectors with the <tt>foos-show</tt> namespace
 will match anything inside any partials rendered by
 <tt>foos/show.html.erb</tt>. As a rule of thumb to circumvent this problem: the
 wider the namespaces's scope, the less CSS and JavaScript you should write
-which depends on it. (Rule of thumb: use sub-partials very liberally.)
-These and similar strategies should be considered when building your automated
-HTML namespacing framework.
+which depends on it. (Use sub-partials very liberally.)
+HTML namespacing produces plenty of tiny CSS and/or JavaScript files. Best
+practice is to bundle all namespaced files together: by virtue of being
+namespaced, it is safe to concatenate them. (Advanced CSS users should
+be thoughtful about
+"cascading order and specificity":http://www.w3.org/TR/CSS2/cascade.html#cascading-order;
+and anybody bundling JavaScript files together should wrap each with
+<tt>(function() { ... })();</tt> to prevent variable leakage.)
+These and similar strategies should be considered when building an HTML
+namespacing framework.
 == License

data/Rakefile CHANGED Viewed

@@ -2,7 +2,7 @@ require 'rubygems'
 require 'rake'
 require 'echoe'
-Echoe.new('html_namespacing', '0.0.4') do |p|
+Echoe.new('html_namespacing', '0.0.5') do |p|
   p.author = 'Adam Hooper'
   p.email = 'adam@adamhooper.com'
   p.summary = 'Automatic HTML namespacing'

data/html_namespacing.gemspec CHANGED Viewed

@@ -2,16 +2,16 @@
 Gem::Specification.new do |s|
   s.name = %q{html_namespacing}
-  s.version = "0.0.4"
+  s.version = "0.0.5"
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Adam Hooper"]
-  s.date = %q{2009-07-07}
+  s.date = %q{2009-07-10}
   s.description = %q{Inserts "class=" attributes within snippets of HTML so CSS and JavaScript can use automatic scopes}
   s.email = %q{adam@adamhooper.com}
   s.extensions = ["ext/html_namespacing/extconf.rb"]
   s.extra_rdoc_files = ["README.rdoc"]
-  s.files = ["README.rdoc", "Rakefile", "test/c_extension_test.rb", "test/test_helper.rb", "ext/html_namespacing/extconf.rb", "ext/html_namespacing/html_namespacing.h", "ext/html_namespacing/html_namespacing.c", "ext/html_namespacing/html_namespacing_ext.c", "lib/html_namespacing.rb", "lib/html_namespacing/plugin/rails.rb", "Manifest", "html_namespacing.gemspec"]
+  s.files = ["README.rdoc", "Rakefile", "test/c_extension_test.rb", "test/test_helper.rb", "ext/html_namespacing/extconf.rb", "ext/html_namespacing/html_namespacing.h", "ext/html_namespacing/html_namespacing.c", "ext/html_namespacing/html_namespacing_ext.c", "lib/html_namespacing.rb", "lib/html_namespacing/plugin.rb", "lib/html_namespacing/plugin/rails.rb", "lib/html_namespacing/plugin/sass.rb", "Manifest", "html_namespacing.gemspec"]
   s.has_rdoc = true
   s.homepage = %q{http://github.com/adamh/html_namespacing}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Html_namespacing", "--main", "README.rdoc"]

data/lib/html_namespacing/plugin/rails.rb CHANGED Viewed

@@ -10,8 +10,8 @@ module HtmlNamespacing
       def self.path_to_namespace(template)
         if func = @options[:template_to_namespace_callback]
           func.call(template)
-        elsif template.path =~ /^([^\.]+)/
-          $1.gsub('/', '-')
+        else
+          HtmlNamespacing::Plugin.default_relative_path_to_namespace(template.path)
         end
       end

data/lib/html_namespacing/plugin/sass.rb ADDED Viewed

@@ -0,0 +1,76 @@
+module HtmlNamespacing
+  module Plugin
+    module Sass
+      def self.install(options = {})
+        options[:prefix] ||= 'views'
+        options[:callback] ||= lambda { |p| HtmlNamespacing::Plugin.default_relative_path_to_namespace(p) }
+        Sass_2_2.install(options)
+      end
+      module Sass_2_2
+        def self.install(options = {})
+          self.allow_updating_partials
+          self.add_super_rule_to_tree_node(options)
+          self.try_to_enable_memoization
+        end
+        private
+        def self.allow_updating_partials
+          ::Sass::Plugin.module_eval do
+            private
+            # Though a bit over-zealous, who *cares* if we render partial
+            # Sass files?
+            def forbid_update?(*args)
+              false
+            end
+          end
+        end
+        def self.add_super_rule_to_tree_node(namespacing_options)
+          ::Sass::Tree::RuleNode.class_eval do
+            def to_s_with_namespacing(tabs, super_rules = nil)
+              super_rules ||= namespacing_rules
+              to_s_without_namespacing(tabs, super_rules)
+            end
+            alias_method_chain(:to_s, :namespacing)
+            private
+            define_method(:namespacing_prefix) do
+              namespacing_options[:prefix]
+            end
+            define_method(:namespacing_callback) do
+              namespacing_options[:callback]
+            end
+            def namespacing_regex
+              /^#{Regexp.quote(options[:css_location])}\/#{Regexp.quote(namespacing_prefix)}\/(.*)\.css$/
+            end
+            def namespace
+              @namespace ||= if options[:css_filename] =~ namespacing_regex
+                namespacing_callback.call($1.split('.')[0])
+              end
+              @namespace
+            end
+            def namespacing_rules
+              namespace && [ ".#{namespace}" ]
+            end
+          end
+        end
+        def self.try_to_enable_memoization
+          ::Sass::Tree::RuleNode.class_eval do
+            extend ActiveSupport::Memoizable
+            memoize :namespacing_rules
+          end
+        rescue NameError
+          # ActiveSupport isn't loaded
+        end
+      end
+    end
+  end
+end

data/lib/html_namespacing/plugin.rb ADDED Viewed

@@ -0,0 +1,12 @@
+module HtmlNamespacing
+  module Plugin
+    autoload(:Rails, File.dirname(__FILE__) + '/plugin/rails')
+    autoload(:Sass, File.dirname(__FILE__) + '/plugin/sass')
+    def self.default_relative_path_to_namespace(path)
+      if path =~ /^([^\.]+)/
+        $1.gsub(/\//, '-')
+      end
+    end
+  end
+end

data/lib/html_namespacing.rb CHANGED Viewed

@@ -1,6 +1,5 @@
 require File.dirname(__FILE__) + '/../ext/html_namespacing/html_namespacing_ext'
-require 'html_namespacing/plugin/rails'
 module HtmlNamespacing
+  autoload(:Plugin, File.dirname(__FILE__) + '/html_namespacing/plugin')
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: adamh-html_namespacing
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Adam Hooper
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
-date: 2009-07-07 00:00:00 -07:00
+date: 2009-07-10 00:00:00 -07:00
 default_executable:
 dependencies: []
@@ -31,7 +31,9 @@ files:
 - ext/html_namespacing/html_namespacing.c
 - ext/html_namespacing/html_namespacing_ext.c
 - lib/html_namespacing.rb
+- lib/html_namespacing/plugin.rb
 - lib/html_namespacing/plugin/rails.rb
+- lib/html_namespacing/plugin/sass.rb
 - Manifest
 - html_namespacing.gemspec
 has_rdoc: true