RubyGems - sinatra-css - Versions diffs - 0.1.5 - Mend

sinatra-css 0.1.5

Files changed (15) hide show

data/.document +5 -0
data/.gitignore +23 -0
data/CHANGES +4 -0
data/LICENSE +20 -0
data/README.rdoc +256 -0
data/Rakefile +92 -0
data/VERSION +1 -0
data/lib/sinatra/css.rb +522 -0
data/sinatra-css.gemspec +67 -0
data/spec/fixtures/app/views/css/screen.rcss +4 -0
data/spec/fixtures/public/insert.css +1 -0
data/spec/fixtures/public/inserted-from-path.css +1 -0
data/spec/sinatra/css_spec.rb +314 -0
data/spec/spec_helper.rb +60 -0
metadata +144 -0

data/.document ADDED

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore ADDED

@@ -0,0 +1,23 @@
+## MAC OS
+.DS_Store
+## TEXTMATE
+*.tmproj
+tmtags
+## EMACS
+*~
+\#*
+.\#*
+## VIM
+*.swp
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+doc
+## PROJECT::SPECIFIC
+spec/fixtures/public/system

data/CHANGES ADDED

@@ -0,0 +1,4 @@
+rel 0.1.0 (2010-03-03)
+* initial release

data/LICENSE ADDED

@@ -0,0 +1,20 @@
+Copyright (c) 2009 kematzy
+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.rdoc ADDED

@@ -0,0 +1,256 @@
+= Sinatra::CSS
+A Sinatra Extension that makes working with CSS easy.
+== Installation
+  #  Add RubyGems.org (former Gemcutter) to your RubyGems sources
+  $  gem sources -a http://rubygems.org
+  $  (sudo)? gem install sinatra-css
+== Dependencies
+This Gem depends upon the following:
+=== Runtime:
+* sinatra ( >= 1.0.a )
+* sinatra-tags[http://github.com/kematzy/sinatra-tags] ( >= 0.1.0 )
+* sinatra-outputbuffer[http://github.com/kematzy/sinatra-outputbuffer] ( >= 0.1.0 )
+* sinatra-basics[http://github.com/kematzy/sinatra-basics] ( >= 0.5.0 )
+Optionals:
+* sinatra-settings[http://github.com/kematzy/sinatra-settings] (>= 0.1.1) # to view default settings in a browser display.
+* sinatra-logger[http://github.com/kematzy/sinatra-logger] (>= 0.1.0) # to capture error messages in the log file.
+=== Development & Tests:
+* sinatra-tests (>= 0.1.6)
+* rspec (>= 1.3.0 )
+* rack-test (>= 0.5.3)
+* rspec_hpricot_matchers (>= 0.1.0)
+== Getting Started
+To start using Sinatra::CSS, just require and register the extension in your App...
+  require 'sinatra/css'
+  class YourApp < Sinatra::Base
+    register(Sinatra::CSS)
+    <snip...>
+  end
+You then get access to 6 useful helper methods:
+=== <tt>css()</tt>
+This method serves two purposes:
+a) Return a stylesheet <tt><link></tt> tag with the <tt>path</tt> given.
+  css('/css/style.css') # =>
+    <link rel="stylesheet" href="/css/style.css" media="screen" type="text/css" charset="utf-8">
+  css('style.css', :media => :print) # =>
+    <link rel="stylesheet" href="/style.css" media="print" type="text/css" charset="utf-8">
+b) When passed a *block*, a <tt><style></tt> tag will be created with the yielded block as its contents.
+  css do
+    "body {
+      color: blue;
+      }"
+  end
+  # =>
+    <style type="text/css" media="screen">
+      body { color: blue; }
+    </style>
+=== <tt>css_custom() & css_custom_add()</tt>
+These two methods works together, like this:
+First you add the <tt>css_custom()</tt> method to your layout(s) (../views/layout.erb):
+  <html>
+    <head>
+      <snip...>
+      <%= css_custom %>
+    </head>
+Then in your views, you can use the <tt>css_custom_add()</tt> method to add custom CSS
+to the page, like this:
+  # in ../views/template.erb
+  <%= css_custom_add( "body{color: red;}" ) =>
+  # in ../views/shared/sidebar.erb
+  <%= css_custom_add( "#sidebar { background-color: black; }" ) =>
+Which outputs the following in the <tt><head></tt> element of your page.
+  <html>
+    <head>
+      <snip...>
+      <style type="text/css" media="screen">
+        body { color: red; }
+        #sidebar { background-color: black; }
+        /* ...and more custom CSS */
+      </style>
+This functionality makes it very easy to add CSS overides or page specific CSS to any page,
+even from within multiple views.
+=== <tt>css_custom_files() & css_custom_add_file()</tt>
+These two methods also works together in a similar fashion, like this:
+First of, add the <tt>css_custom_files()</tt> method to your layout(s) (../views/layout.erb):
+  <html>
+    <head>
+      <snip...>
+      <%= css_custom_files %>
+    </head>
+Then in your views, you can use the <tt>css_custom_add_file()</tt> method to add a custom CSS
+file to the page, like this:
+  <%= css_custom_add_file('home')  #=>
+    <link href="/home.css" rel="stylesheet" media="screen" type="text/css" charset="utf-8" />
+The method even accepts an Array consisting of <tt>[ filename, media ]</tt> like this:
+  <%= css_custom_add_file( ['/css/print', :print] )  #=>
+    <link href="/css/print.css" rel="stylesheet" media="print" type="text/css" charset="utf-8" />
+You can also use the method to embed the styles of a .css file into any part of a page, like this:
+  # NB! path is starting from APP_ROOT/public/
+  css_custom_add_file('home.css',:insert_into_html) #=>
+    <style type="text/css" media="screen">
+      /* the contents of ../public/home.css */
+    </style>
+You can even give a file system path to embed the styles of a globaly shared .css file
+outside of your applications path. Providing an easy way to resuse common snippets of code.
+  # NB! make sure the path and .css file works together as a real path.
+  # the :path value should always be a directory without the trailing slash.
+  css_custom_add_file('home.css',:insert_into_html, '/path/2/some/directory')
+    <style type="text/css" media="screen">
+      /* the contents of /path/2/some/directory/home.css */
+    </style>
+=== <tt>css_insert_file()</tt>
+This is a simple convenicence method that takes a path to a CSS file
+and inserts its content straight into the current view, without any enclosing HTML tags.
+The method depends upon the settings of the <tt>:css_shared_source_files_dir</tt>
+configuration variable defined inside your application.
+By default this is set to <tt>'ENV['HOME']/.alt/css'</tt>.
+An example of how to use this functionality:
+  # in your app's routes configurations
+  get('/css/screen.css') do
+    content_type 'text/css'
+    erb('css/screen'.to_sym, :layout => false)
+  end
+  # in views/css/screen.erb
+  <%= css_insert_file('blueprint/grid') %>
+    # => insert the contents of ENV['HOME']/.alt/css/blueprint/grid.css
+You can also load and insert local files, ie files in your app's <tt>public/css/</tt> directory
+by adding the <tt>:local</tt> flag to the call.
+  <%= css_insert_file('colors', :local) %>
+  # => insert the contents of /path/2/your/app/public/css/colors.css
+== RTFM
+If the above is not clear enough, please check the Specs for a better understanding.
+== Errors / Bugs
+If something is not behaving intuitively, it is a bug, and should be reported.
+Report it here: http://github.com/kematzy/sinatra-css/issues
+== TODOs
+* Keep it up to date with any changes in Sinatra.
+* Add bundle functionality from Sinatra::Bundles gem.
+* Improve the specs a bit and add missing tests.
+* Any other improvements I or You can think of.
+== Note on Patches/Pull Requests
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  * (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+== Copyright
+Copyright (c) 2010 kematzy. See LICENSE for details.

data/Rakefile ADDED

@@ -0,0 +1,92 @@
+require 'rubygems'
+require 'rake'
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sinatra-css"
+    gem.summary = %Q{A Sinatra Extension that makes working with CSS easy.}
+    gem.description = %Q{A Sinatra Extension that makes working with CSS easy.}
+    gem.email = "kematzy@gmail.com"
+    gem.homepage = "http://github.com/kematzy/sinatra-css"
+    gem.authors = ["kematzy"]
+    gem.add_dependency "sinatra", ">= 1.0"
+    gem.add_dependency "sinatra-tags", ">= 0.1.0"
+    gem.add_development_dependency "sinatra-tests", ">= 0.1.6"
+    gem.add_development_dependency "rspec", ">= 1.3.0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"]
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"]
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+namespace :spec do
+  desc "Run all specifications quietly"
+  Spec::Rake::SpecTask.new(:quiet) do |t|
+    t.libs << "lib"
+    t.spec_opts = ["--color", "--require", "spec/spec_helper.rb"]
+  end
+  desc "Run specific spec verbosely (SPEC=/path/2/file)"
+  Spec::Rake::SpecTask.new(:select) do |t|
+    t.libs << "lib"
+    t.spec_files = [ENV["SPEC"]]
+    t.spec_opts = ["--color", "--format", "specdoc", "--require", "spec/spec_helper.rb"]
+  end
+end
+task :spec => :check_dependencies
+task :default => :spec
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "Sinatra::CSS #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+desc 'Build the rdoc HTML Files'
+task :docs do
+  version = File.exist?('VERSION') ? IO.read('VERSION').chomp : "[Unknown]"
+  sh "sdoc -N --title 'Sinatra::CSS v#{version}' lib/ README.rdoc"
+end
+namespace :docs do
+  desc 'Remove rdoc products'
+  task :remove => [:clobber_rdoc]
+  desc 'Force a rebuild of the RDOC files'
+  task :rebuild => [:rerdoc]
+  desc 'Build docs, and open in browser for viewing (specify BROWSER)'
+  task :open => [:docs] do
+    browser = ENV["BROWSER"] || "safari"
+    sh "open -a #{browser} doc/index.html"
+  end
+end

data/VERSION ADDED

	@@ -0,0 +1 @@
1	+ 0.1.5

data/lib/sinatra/css.rb ADDED

@@ -0,0 +1,522 @@
+require 'sinatra/base'
+require 'sinatra/tags'
+require 'sinatra/assets'
+module Tilt
+  ## RCSS (RubyCSS) support, piggy-backing onto the ERBTemplate
+  #   so that we can use <% %> tags with Ruby code inside the .rcss file
+  register 'rcss', ERBTemplate
+end #/module Tilt
+module Sinatra
+  module Templates
+    ## add support for .rcss
+    def rcss(template, options={}, locals={})
+      options[:outvar] = '@_out_buf'
+      options[:layout] = false
+      render :rcss, template, options, locals
+    end
+  end #/module Templates
+  ##
+  # = Sinatra::CSS
+  #
+  # A Sinatra Extension that makes working with CSS easy.
+  #
+  #
+  #
+  # == Installation
+  #
+  #   #  Add RubyGems.org (former Gemcutter) to your RubyGems sources
+  #   $  gem sources -a http://rubygems.org
+  #
+  #   $  (sudo)? gem install sinatra-css
+  #
+  # == Dependencies
+  #
+  # This Gem depends upon the following:
+  #
+  # === Runtime:
+  #
+  # * sinatra ( >= 1.0.a )
+  # * sinatra-tags[http://github.com/kematzy/sinatra-tags] ( >= 0.1.0 )
+  # * sinatra-outputbuffer[http://github.com/kematzy/sinatra-outputbuffer] ( >= 0.1.0 )
+  # * sinatra-basics[http://github.com/kematzy/sinatra-basics] ( >= 0.5.0 )
+  #
+  # Optionals:
+  #
+  # * sinatra-settings[http://github.com/kematzy/sinatra-settings] (>= 0.1.1) # to view default settings in a browser display.
+  # * sinatra-logger[http://github.com/kematzy/sinatra-logger] (>= 0.1.0) # to capture error messages in the log file.
+  #
+  #
+  # === Development & Tests:
+  #
+  # * sinatra-tests (>= 0.1.6)
+  # * rspec (>= 1.3.0 )
+  # * rack-test (>= 0.5.3)
+  # * rspec_hpricot_matchers (>= 0.1.0)
+  #
+  #
+  # == Getting Started
+  #
+  # To start using Sinatra::CSS, just require and register the extension in your App...
+  #
+  #   require 'sinatra/css'
+  #
+  #   class YourApp < Sinatra::Base
+  #     register(Sinatra::CSS)
+  #
+  #     <snip...>
+  #
+  #   end
+  #
+  #
+  # You then get access to 6 useful helper methods:
+  #
+  #
+  # === <tt>css()</tt>
+  #
+  # This method serves two purposes:
+  #
+  # a) Return a stylesheet <tt><link></tt> tag with the <tt>path</tt> given.
+  #
+  #   css('/css/style.css') # =>
+  #
+  #     <link rel="stylesheet" href="/css/style.css" media="screen" type="text/css" charset="utf-8">
+  #
+  #   css('style.css', :media => :print) # =>
+  #
+  #     <link rel="stylesheet" href="/style.css" media="print" type="text/css" charset="utf-8">
+  #
+  #
+  #
+  # b) When passed a *block*, a <tt><style></tt> tag will be created with the yielded block as its contents.
+  #
+  #   css do
+  #     "body {
+  #       color: blue;
+  #       }"
+  #   end
+  #   # =>
+  #
+  #     <style type="text/css" media="screen">
+  #       body { color: blue; }
+  #     </style>
+  #
+  #
+  # === <tt>css_custom() & css_custom_add()</tt>
+  #
+  # These two methods works together, like this:
+  #
+  # First you add the <tt>css_custom()</tt> method to your layout(s) (../views/layout.erb):
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <%= css_custom %>
+  #
+  #     </head>
+  #
+  #
+  #
+  # Then in your views, you can use the <tt>css_custom_add()</tt> method to add custom CSS
+  # to the page, like this:
+  #
+  #   # in ../views/template.erb
+  #   <%= css_custom_add( "body{color: red;}" ) =>
+  #
+  #   # in ../views/shared/sidebar.erb
+  #   <%= css_custom_add( "#sidebar { background-color: black; }" ) =>
+  #
+  #
+  # Which outputs the following in the <tt><head></tt> element of your page.
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <style type="text/css" media="screen">
+  #         body { color: red; }
+  #         #sidebar { background-color: black; }
+  #         /* ...and more custom CSS */
+  #       </style>
+  #
+  #
+  # This functionality makes it very easy to add CSS overides or page specific CSS to any page,
+  # even from within multiple views.
+  #
+  #
+  # === <tt>css_custom_files() & css_custom_add_file()</tt>
+  #
+  # These two methods also works together in a similar fashion, like this:
+  #
+  # First of, add the <tt>css_custom_files()</tt> method to your layout(s) (../views/layout.erb):
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <%= css_custom_files %>
+  #
+  #     </head>
+  #
+  #
+  # Then in your views, you can use the <tt>css_custom_add_file()</tt> method to add a custom CSS
+  # file to the page, like this:
+  #
+  #   <%= css_custom_add_file('home')  #=>
+  #
+  #     <link href="/home.css" rel="stylesheet" media="screen" type="text/css" charset="utf-8" />
+  #
+  #
+  # The method even accepts an Array consisting of <tt>[ filename, media ]</tt> like this:
+  #
+  #   <%= css_custom_add_file( ['/css/print', :print] )  #=>
+  #
+  #     <link href="/css/print.css" rel="stylesheet" media="print" type="text/css" charset="utf-8" />
+  #
+  #
+  # You can also use the method to embed the styles of a .css file into any part of a page, like this:
+  #
+  #   # NB! path is starting from APP_ROOT/public/
+  #
+  #   css_custom_add_file('home.css',:insert_into_html) #=>
+  #
+  #     <style type="text/css" media="screen">
+  #       /* the contents of ../public/home.css */
+  #     </style>
+  #
+  #
+  # You can even give a file system path to embed the styles of a globaly shared .css file
+  # outside of your applications path. Providing an easy way to resuse common snippets of code.
+  #
+  #
+  #   # NB! make sure the path and .css file works together as a real path.
+  #
+  #   # the :path value should always be a directory without the trailing slash.
+  #
+  #   css_custom_add_file('home.css',:insert_into_html, '/path/2/some/directory')
+  #
+  #
+  #     <style type="text/css" media="screen">
+  #       /* the contents of /path/2/some/directory/home.css */
+  #     </style>
+  #
+  #
+  #
+  # === <tt>css_insert_file()</tt>
+  #
+  # This is a simple convenicence method that takes a path to a CSS file
+  # and inserts its content straight into the current view, without any enclosing HTML tags.
+  #
+  # The method depends upon the settings of the <tt>:css_shared_source_files_dir</tt>
+  # configuration variable defined inside your application.
+  # By default this is set to <tt>'ENV['HOME']/.alt/css'</tt>.
+  #
+  # An example of how to use this functionality:
+  #
+  #   # in your app's routes configurations
+  #
+  #   get('/css/screen.css') do
+  #     content_type 'text/css'
+  #     erb('css/screen'.to_sym, :layout => false)
+  #   end
+  #
+  #
+  #   # in views/css/screen.erb
+  #
+  #   <%= css_insert_file('blueprint/grid') %>
+  #
+  #     # => insert the contents of ENV['HOME']/.alt/css/blueprint/grid.css
+  #
+  #
+  # You can also load and insert local files, ie files in your app's <tt>public/css/</tt> directory
+  # by adding the <tt>:local</tt> flag to the call.
+  #
+  #   <%= css_insert_file('colors', :local) %>
+  #
+  #   # => insert the contents of /path/2/your/app/public/css/colors.css
+  #
+  #
+  # == TODOs
+  #
+  # * Keep it up to date with any changes in Sinatra.
+  #
+  # * Add bundle functionality from Sinatra::Bundles gem.
+  #
+  # * Improve the specs a bit and add missing tests.
+  #
+  # * Any other improvements I or You can think of.
+  #
+  #
+  # == Copyright
+  #
+  # Copyright (c) 2010 kematzy. See LICENSE for details.
+  #
+  module CSS
+    VERSION = '0.1.5' unless const_defined?(:VERSION)
+    def self.version; "Sinatra::CSS v#{VERSION}"; end
+    module Helpers
+      attr_accessor :sinatra_css_custom_code, :sinatra_css_custom_files
+      ##
+      # Return stylesheet link tag to _path_. When a _block_
+      # is passed, a style tag will be created with the yielded
+      # value as its contents.
+      #
+      # ==== Examples
+      #
+      #   css do
+      #     "body {
+      #       color: blue;
+      #     }"
+      #   end
+      #   # => <style>body { ... }</style>
+      #
+      #
+      #   css('/css/style.css', :media => :print) # =>
+      #
+      #     <link rel="stylesheet" href="/css/style.css" media="print" type="text/css" charset="utf-8">
+      #
+      # @api public
+      def css(path = nil, attrs = {}, &block)
+        attrs = { :type => 'text/css', :media => "screen" }.merge(attrs)
+        return tag(:style, yield, attrs) if block_given?
+        path = url_for("#{path.sub('.css','')}.css") unless remote_asset?(path)
+        tag(:link, { :rel => 'stylesheet', :charset => "utf-8", :href => path, :newline => true }.merge(attrs))
+      end
+      alias_method :stylesheet, :css
+      ##
+      # Adds custom CSS to the page load from within a view, helper method and so on
+      #
+      # ==== Examples
+      #
+      #   css_custom_add("body{color: green;}")
+      #     => output within <style>.. tag in the <head> of document
+      #
+      # @api public
+      def css_custom_add(css)
+        @sinatra_css_custom_code ||= []
+        @sinatra_css_custom_code << css
+      end
+      ##
+      # Add a custom CSS file to the page load from within a view, helper method and so on
+      #
+      # ==== Examples
+      #
+      #   css_custom_add_file [filename, media]
+      #     => output within <link href..>.. tag in the <head> of document
+      #
+      # You can also embed the styles of a .css file into the head element of a page.
+      # NB! path is starting from APP_ROOT/public/
+      #
+      #   css_custom_add_file('home.css',:insert_into_html)
+      #     => <style type="text/css" media="screen"> CSS content </style>
+      #
+      # You can even give a file system path to embed the styles of a .css file.
+      # NB! make sure the path and .css file works together as a real path.
+      # :path should always be a directory without the trailing slash.
+      #
+      #   css_custom_add_file('home.css',:insert_into_html, '/path/2/some/directory')
+      #     => <style type="text/css" media="screen"> Some Style CSS content </style>
+      #
+      # @api public
+      def css_custom_add_file(file, insert_into_html = nil, path = nil)
+        if insert_into_html.nil?
+          @sinatra_css_custom_files ||= []
+          file = [file,:screen] unless file.is_a?(Array)
+          @sinatra_css_custom_files << file
+        else
+          # read the file into css_custom_add
+          path_css = path.nil? ? self.class.public : path
+          file_css = "#{path_css}/#{file.sub('.css','')}.css"
+          if test(?f, file_css)
+            css_custom_add(IO.read(file_css))
+          else
+            err_msg = "ERROR: css_custom_add_file(:insert_into_html) method could NOT find and embed this CSS file=[ #{file_css} ]"
+            if self.respond_to?(:logger)
+              logger.warn(err_msg)
+            else
+              warn(err_msg)
+            end
+          end
+        end
+      end
+      ##
+      # Simple convenicence method that takes a path to a CSS file
+      # and inserts its content into the current <tt>.erb</tt> file
+      #
+      # Depends upon the settings of the <tt>:css_compiled_files_dir</tt> configuration variable
+      # defined inside your application.  By default it is set to <tt>'//Users/kematzy/.alt/css'</tt>
+      #
+      # ==== Examples
+      #
+      #   # in your app's routes configurations
+      #   get '/css/screen.css' { }
+      #   get('/css/screen.css') do
+      #     content_type 'text/css'
+      #     erb('css/screen.css'.to_sym, :layout => false)
+      #   end
+      #
+      #
+      #   # in views/css/screen.css
+      #   css_insert_file('blueprint/grid')
+      #
+      # which inserts the CSS code from that file into the output.
+      #
+      #
+      #
+      #
+      # @api public
+      def css_insert_file(path = '', local = nil )
+        file_path = local.nil? ? "#{self.class.css_shared_source_files_dir}/#{path}" : path
+        file_path = file_path.sub(/\.css$/,'') << ".css"
+        if test(?f, file_path)
+          content = IO.read(file_path)
+        else
+          content = "/* ERROR:  the CSS file [#{file_path}] could NOT be found */"
+        end
+        content
+      end
+      ##
+      # Outputs any custom CSS if provided from within a view, helper method and so on
+      #
+      # ==== Examples
+      #
+      #   custom_css() => <style...> custom css </style>
+      #
+      # @api public
+      def css_custom(css=nil)
+        out = ''
+        out << css unless css.nil?
+        @sinatra_css_custom_code.each { |i| out << "        #{i}\n" } unless @sinatra_css_custom_code.nil?
+        out = out.empty? ? '' : %Q[<style type="text/css" media="screen">\n#{out.strip}\n      </style>\n]
+      end
+      ##
+      # Outputs any custom CSS files that have been included
+      #
+      # ==== Examples
+      #
+      #   css_custom_files =>
+      #     <!-- custom css files -->
+      #     <link href="/css/custom1.css"...>
+      #     <link href="/css/custom2.css"...>
+      #     <!-- /custom css files -->
+      #
+      # @api public
+      def css_custom_files
+        unless @sinatra_css_custom_files.nil?
+          out = "<!-- custom css files -->\n"
+          @sinatra_css_custom_files.each do |file| # returns an array
+            out << css(file[0], :media => file[1])
+          end
+          out << "<!-- /custom css files -->\n"
+        else
+          '' # return empty string, it's better than nil in this case
+        end
+      end
+    end #/ Helpers
+    ##
+    # Handles all CSS requests, and returns the RCSS (RubyCSS) file version of it,
+    # or else passes the request on to the file system.
+    #
+    # NB! the path value given is NOT used as the name of the source directory in app/views,
+    # so ensure that there is always an app/views/css directory in place.
+    #
+    # ie:
+    #   get_all_css_requests()  => expects a app/views/css dir with the .rcss files
+    #   get_all_css_requests('/stylesheets')  => expects a app/views/css dir with the .rcss files
+    #
+    # ==== Examples
+    #
+    #   get_all_css_requests()                => catches 'site.com/css/screen.css
+    #   get_all_css_requests('/stylesheets')  => catches 'site.com/stylesheets/screen.css
+    #
+    # @api public
+    def get_all_css_requests(path='/css', options = {})
+      path, options = '/css', path if path.is_a?(Hash)
+      get("#{path}/*.css", {}) do
+        begin
+          options = { :cache => false, :layout => false }.merge(options)
+          content_type 'text/css', :charset => 'utf-8'
+          if self.settings.environment == :production
+            rcss("css/#{params[:splat].first}".to_sym, options ).gsub(/\n\r?$/,"")
+          else
+            rcss("css/#{params[:splat].first}".to_sym, options )
+          end
+        rescue Errno::ENOENT
+          content_type 'text/html'  # reset the content_type
+          pass
+        end
+      end
+    end
+    ##
+    # Registers these Extensions:
+    #
+    # * Sinatra::Tags
+    # * Sinatra::Basics::Assets
+    #
+    # Default Settings:
+    #
+    # * +:css_shared_source_files_dir+ => set the path to the Shared directory with compliled CSS templates.
+    #   Default is: <tt>'ENV['HOME']/.alt/css'</tt>
+    #
+    # @api public
+    def self.registered(app)
+      app.register(Sinatra::Tags)
+      app.register(Sinatra::Assets)
+      app.helpers Sinatra::CSS::Helpers
+      # set the path to the Shared directory with compliled CSS templates
+      app.set :css_shared_source_files_dir, File.join(File.expand_path(ENV['HOME']) ,'.alt', 'css')
+      ## add the extension specific options to those inspectable by :settings_inspect method
+      #  provided by the Sinatra::Settings extension
+      if app.respond_to?(:sinatra_settings_for_inspection)
+        %w( css_shared_source_files_dir ).each do |m|
+          app.sinatra_settings_for_inspection << m
+        end
+      end
+    end #/ self.registered
+  end #/ CSS
+  register(Sinatra::CSS)
+end #/ Sinatra