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

adamh-html_namespacing 0.0.4 → 0.0.5

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

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