RubyGems - sinatra-js - Versions diffs - 0.1.5 - Mend

sinatra-js 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 +265 -0
data/Rakefile +91 -0
data/VERSION +1 -0
data/lib/sinatra/js.rb +564 -0
data/sinatra-js.gemspec +70 -0
data/spec/fixtures/app/views/js/app.rjs +1 -0
data/spec/fixtures/public/insert.js +1 -0
data/spec/fixtures/public/inserted-from-path.js +1 -0
data/spec/sinatra/js_spec.rb +315 -0
data/spec/spec_helper.rb +59 -0
metadata +156 -0

data/.document ADDED Viewed

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

data/.gitignore ADDED Viewed

@@ -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 Viewed

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

data/LICENSE ADDED Viewed

@@ -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 Viewed

@@ -0,0 +1,265 @@
+= Sinatra::JS
+A Sinatra Extension that makes working with JS easy.
+== Installation
+  #  Add RubyGems.org (former Gemcutter) to your RubyGems sources
+  $  gem sources -a http://rubygems.org
+  $  (sudo)? gem install sinatra-js
+== 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::JS, just require and register the extension in your App...
+  require 'sinatra/js'
+  class YourApp < Sinatra::Base
+    register(Sinatra::JS)
+    <snip...>
+  end
+You then get access to 6 useful helper methods:
+=== <tt>js() / javascript()</tt>
+This method serves two purposes:
+a) Return a stylesheet <tt><script src=""></script></tt> tag with the <tt>path</tt> given.
+  js('jquery') # =>
+    <script src="/jquery.js" type="text/javascript" charset="utf-8"></script>
+  js('/js/jquery-tools.js') # =>
+    <script src="/js/jquery-tools.js" type="text/javascript" charset="utf-8"></script>
+You can even pass an array of files to the method, which then outputs the <tt><script></tt>
+tags for each file.
+  js( ['/js/jquery.js', '/js/jquery.ui'] ) # =>
+    <script src="/js/jquery.js" type="text/javascript" charset="utf-8"></script>
+    <script src="/js/jquery.ui.js" type="text/javascript" charset="utf-8"></script>
+b) When passed a *block*, a <tt><script></tt> tag will be created with the yielded block
+as its contents.
+  js do
+    "document.write('hi');"
+  end
+  # =>
+    <script type="text/javascript" charset="utf-8">
+      document.write('hi');
+    </script>
+=== <tt>js_custom() & js_custom_add()</tt>
+These two methods works together, like this:
+First you add the <tt>js_custom()</tt> method to your layout(s) (../views/layout.erb):
+  <html>
+    <head>
+      <snip...>
+      <%= js_custom %>
+    </head>
+Then in your views, you can use the <tt>js_custom_add()</tt> method to add custom JS
+to the page, like this:
+  # in ../views/template.erb
+  <%= js_custom_add( "window.alert('this works');" )
+  # in ../views/shared/sidebar.erb
+  <%= js_custom_add( "document.write('this also works');" )
+Which outputs the following in the <tt><head></tt> element of your page.
+  <html>
+    <head>
+      <snip...>
+      <script type="text/javascript" charset="utf-8">
+        window.alert('this works');
+        document.write('this also works');
+      </script>
+This functionality makes it very easy to add special JS functionality to any page,
+even from within multiple views.
+=== <tt>js_custom_files() & js_custom_add_file()</tt>
+These two methods also works together in a similar fashion, like this:
+First of, add the <tt>js_custom_files()</tt> method to your layout(s) (../views/layout.erb):
+  <html>
+    <head>
+      <snip...>
+      <%= js_custom_files %>
+    </head>
+Then in your views, you can use the <tt>js_custom_add_file()</tt> method to add a custom JS
+file to the page, like this:
+  <%= js_custom_add_file('home')  #=>
+    <script src="/home.js" type="text/javascript" charset="utf-8"></script>
+You can also use the method to embed the content of a .js file into the <tt><head></tt>
+part of any page, like this:
+  # NB! path is starting from APP_ROOT/public/
+  js_custom_add_file('home.js',:insert_into_html) #=>
+    <html>
+      <head>
+        <snip...>
+        <script type="text/javascript" charset="utf-8">
+          // the contents of ../public/home.js
+        </script>
+You can even give a file system path to embed the content of a globaly shared .js file
+outside of your applications path. Providing an easy way to resuse common snippets of code.
+  # NB! make sure the path and .js file works together as a real path.
+  # the :path value should always be a directory without the trailing slash.
+  js_custom_add_file('win.open.js',:insert_into_html, '/path/2/some/directory')
+  <html>
+    <head>
+      <snip...>
+      <script type="text/javascript" charset="utf-8">
+        // the contents of /path/2/some/directory/win.open.js
+      </script>
+=== <tt>js_insert_file()</tt>
+This is a simple convenicence method that takes a path to a JS file
+and inserts its content straight into the current view, without any enclosing HTML tags.
+The method depends upon the settings of the <tt>:js_shared_source_files_dir</tt>
+configuration variable defined inside your application.
+By default this is set to <tt>'ENV['HOME']/.alt/js'</tt>.
+An example of how to use this functionality:
+  # in your app's routes configurations
+  get('/js/app.js') do
+    content_type 'text/javascript'
+    erb('js/app'.to_sym, :layout => false)
+  end
+  # in views/js/app.erb
+  <%= js_insert_file('jquery') %>
+    # => insert the contents of ENV['HOME']/.alt/js/jquery.js
+You can also load and insert local files, ie files in your app's <tt>public/js/</tt> directory
+by adding the <tt>:local</tt> flag to the call.
+  <%= js_insert_file('tweets', :local) %>
+  # => insert the contents of /path/2/your/app/public/js/tweets.js
+== 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-js/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 Viewed

@@ -0,0 +1,91 @@
+require 'rubygems'
+require 'rake'
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "sinatra-js"
+    gem.summary = %Q{A Sinatra Extension that makes working with JS easy.}
+    gem.description = %Q{A Sinatra Extension that makes working with JS easy.}
+    gem.email = "kematzy@gmail.com"
+    gem.homepage = "http://github.com/kematzy/sinatra-js"
+    gem.authors = ["kematzy"]
+    gem.add_dependency "sinatra", ">= 1.0"
+    gem.add_dependency "sinatra-tags"
+    gem.add_dependency "sinatra-assets"
+    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::JS #{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::JS 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 Viewed

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

data/lib/sinatra/js.rb ADDED Viewed

@@ -0,0 +1,564 @@
+require 'sinatra/base'
+require 'sinatra/tags'
+require 'sinatra/assets'
+module Tilt
+  ## RJS (RubyJS) support, piggy-backing onto the ERBTemplate
+  #   so that we can use <% %> tags with Ruby code inside the .rjs file
+  register 'rjs', ERBTemplate
+end #/module Tilt
+module Sinatra
+  module Templates
+    ## add support for .rjs
+    def rjs(template, options={}, locals={})
+      options[:outvar] = '@_out_buf'
+      options[:layout] = false
+      render :rjs, template, options, locals
+    end
+  end #/module Templates
+  # = Sinatra::JS
+  #
+  # A Sinatra Extension that makes working with JS easy.
+  #
+  #
+  #
+  # == Installation
+  #
+  #   #  Add RubyGems.org (former Gemcutter) to your RubyGems sources
+  #   $  gem sources -a http://rubygems.org
+  #
+  #   $  (sudo)? gem install sinatra-js
+  #
+  # == 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::JS, just require and register the extension in your App...
+  #
+  #   require 'sinatra/js'
+  #
+  #   class YourApp < Sinatra::Base
+  #     register(Sinatra::JS)
+  #
+  #     <snip...>
+  #
+  #   end
+  #
+  #
+  # You then get access to 6 useful helper methods:
+  #
+  #
+  # === <tt>js() / javascript()</tt>
+  #
+  # This method serves two purposes:
+  #
+  # a) Return a stylesheet <tt><script src=""></script></tt> tag with the <tt>path</tt> given.
+  #
+  #   js('jquery') # =>
+  #
+  #     <script src="/jquery.js" type="text/javascript" charset="utf-8"></script>
+  #
+  #   js('/js/jquery-tools.js') # =>
+  #
+  #     <script src="/js/jquery-tools.js" type="text/javascript" charset="utf-8"></script>
+  #
+  #
+  # You can even pass an array of files to the method, which then outputs the <tt><script></tt>
+  # tags for each file.
+  #
+  #   js( ['/js/jquery.js', '/js/jquery.ui'] ) # =>
+  #
+  #     <script src="/js/jquery.js" type="text/javascript" charset="utf-8"></script>
+  #     <script src="/js/jquery.ui.js" type="text/javascript" charset="utf-8"></script>
+  #
+  #
+  #
+  # b) When passed a *block*, a <tt><script></tt> tag will be created with the yielded block
+  # as its contents.
+  #
+  #   js do
+  #     "document.write('hi');"
+  #   end
+  #   # =>
+  #
+  #     <script type="text/javascript" charset="utf-8">
+  #       document.write('hi');
+  #     </script>
+  #
+  #
+  # === <tt>js_custom() & js_custom_add()</tt>
+  #
+  # These two methods works together, like this:
+  #
+  # First you add the <tt>js_custom()</tt> method to your layout(s) (../views/layout.erb):
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <%= js_custom %>
+  #
+  #     </head>
+  #
+  #
+  #
+  # Then in your views, you can use the <tt>js_custom_add()</tt> method to add custom JS
+  # to the page, like this:
+  #
+  #   # in ../views/template.erb
+  #   <%= js_custom_add( "window.alert('this works');" )
+  #
+  #   # in ../views/shared/sidebar.erb
+  #   <%= js_custom_add( "document.write('this also works');" )
+  #
+  #
+  # Which outputs the following in the <tt><head></tt> element of your page.
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <script type="text/javascript" charset="utf-8">
+  #         window.alert('this works');
+  #         document.write('this also works');
+  #       </script>
+  #
+  #
+  # This functionality makes it very easy to add special JS functionality to any page,
+  # even from within multiple views.
+  #
+  #
+  # === <tt>js_custom_files() & js_custom_add_file()</tt>
+  #
+  # These two methods also works together in a similar fashion, like this:
+  #
+  # First of, add the <tt>js_custom_files()</tt> method to your layout(s) (../views/layout.erb):
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <%= js_custom_files %>
+  #
+  #     </head>
+  #
+  #
+  # Then in your views, you can use the <tt>js_custom_add_file()</tt> method to add a custom JS
+  # file to the page, like this:
+  #
+  #   <%= js_custom_add_file('home')  #=>
+  #
+  #     <script src="/home.js" type="text/javascript" charset="utf-8"></script>
+  #
+  #
+  # You can also use the method to embed the content of a .js file into the <tt><head></tt>
+  # part of any page, like this:
+  #
+  #   # NB! path is starting from APP_ROOT/public/
+  #
+  #   js_custom_add_file('home.js',:insert_into_html) #=>
+  #
+  #     <html>
+  #       <head>
+  #         <snip...>
+  #
+  #         <script type="text/javascript" charset="utf-8">
+  #           // the contents of ../public/home.js
+  #         </script>
+  #
+  #
+  # You can even give a file system path to embed the content of a globaly shared .js file
+  # outside of your applications path. Providing an easy way to resuse common snippets of code.
+  #
+  #
+  #   # NB! make sure the path and .js file works together as a real path.
+  #
+  #   # the :path value should always be a directory without the trailing slash.
+  #
+  #   js_custom_add_file('win.open.js',:insert_into_html, '/path/2/some/directory')
+  #
+  #
+  #   <html>
+  #     <head>
+  #       <snip...>
+  #
+  #       <script type="text/javascript" charset="utf-8">
+  #         // the contents of /path/2/some/directory/win.open.js
+  #       </script>
+  #
+  #
+  #
+  # === <tt>js_insert_file()</tt>
+  #
+  # This is a simple convenicence method that takes a path to a JS file
+  # and inserts its content straight into the current view, without any enclosing HTML tags.
+  #
+  # The method depends upon the settings of the <tt>:js_shared_source_files_dir</tt>
+  # configuration variable defined inside your application.
+  # By default this is set to <tt>'ENV['HOME']/.alt/js'</tt>.
+  #
+  # An example of how to use this functionality:
+  #
+  #   # in your app's routes configurations
+  #
+  #   get('/js/app.js') do
+  #     content_type 'text/javascript'
+  #     erb('js/app'.to_sym, :layout => false)
+  #   end
+  #
+  #
+  #   # in views/js/app.erb
+  #
+  #   <%= js_insert_file('jquery') %>
+  #
+  #     # => insert the contents of ENV['HOME']/.alt/js/jquery.js
+  #
+  #
+  # You can also load and insert local files, ie files in your app's <tt>public/js/</tt> directory
+  # by adding the <tt>:local</tt> flag to the call.
+  #
+  #   <%= js_insert_file('tweets', :local) %>
+  #
+  #   # => insert the contents of /path/2/your/app/public/js/tweets.js
+  #
+  #
+  # == 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 JS
+    VERSION = '0.1.5' unless const_defined?(:VERSION)
+    def self.version; "Sinatra::JS v#{VERSION}"; end
+    module Helpers
+      attr_accessor :sinatra_js_custom_code, :sinatra_js_custom_files
+      ##
+      # Return script tag to _path_. When a _block_ is passed,
+      # a script tag will be created with the yielded value as
+      # its contents.
+      #
+      # ==== Examples
+      #
+      #   js do
+      #     "document.write('hi');"
+      #   end
+      #   # =>
+      #
+      #   js('jquery') # =>
+      #
+      #     <script src="/jquery.js" type="text/javascript" charset="utf-8"></script>
+      #
+      #   js('/js/jquery-tools.js') # =>
+      #
+      #     <script src="/js/jquery-tools.js" type="text/javascript" charset="utf-8"></script>
+      #
+      #
+      # You can even pass an array of files to the method, which then outputs the <tt><script></tt>
+      # tags for each file.
+      #
+      #   js( ['/js/jquery.js', '/js/jquery.ui'] ) # =>
+      #
+      #     <script src="/js/jquery.js" type="text/javascript" charset="utf-8"></script>
+      #     <script src="/js/jquery.ui.js" type="text/javascript" charset="utf-8"></script>
+      #
+      # @api public
+      def js(path = nil, attrs = {}, &block)
+        attrs = { :type => 'text/javascript', :charset => "utf-8" }.merge(attrs)
+        return tag(:script, yield, attrs) if block_given?
+        unless path.nil?
+          if path.is_a?(Array)
+            out = ''
+            path.each do |f|
+              fpath = url_for("#{f.sub(/\.js$/,'')}.js") unless remote_asset?(f)
+              attrs[:src] = fpath
+              out << tag(:script, { :newline => false }.merge(attrs) )
+            end
+            out
+          else
+            path = url_for("#{path.sub(/\.js$/,'')}.js") unless remote_asset?(path)
+            attrs[:src] = path
+            tag(:script, { :newline => false }.merge(attrs) )
+          end
+        end
+      end
+      alias_method :javascript, :js
+      ##
+      # Adds custom JS to the page load from within a view, helper method and so on
+      #
+      # ==== Examples
+      #
+      #   js_custom_add("window.alert('this works');") => void (output is handled through the :js_custom method)
+      #
+      # @api public
+      def js_custom_add(js)
+        @sinatra_js_custom_code ||= []
+        @sinatra_js_custom_code << js
+      end
+      ##
+      # Add a custom JS file to the page load from within a view, helper method and so on
+      #
+      # ==== Examples
+      #
+      #   js_custom_add_file(:filename || path to remote file)  => void (output handled through the :js_custom_files method)
+      #
+      # # You can also embed the code from a .js file into the head element of a page.
+      # NB! path is starting from APP_ROOT/public/
+      #
+      #   js_custom_add_file('home.js',:insert_into_html)
+      #     => <script type="text/javascript"..> JS content </script>
+      #
+      # You can even give a file system path to embed the styles of a .js file.
+      #
+      #   js_custom_add_file('home.js',:insert_into_html, '/path/2/some/directory')
+      #     => <script type="text/javascript"..> Some JS content </script>
+      #
+      # @api public
+      def js_custom_add_file(file, insert_into_html = nil, path = nil)
+        if insert_into_html.nil?
+          @sinatra_js_custom_files ||= []
+          if file.is_a?(Array)
+            file.each {|f| @sinatra_js_custom_files << f }
+          else
+            @sinatra_js_custom_files << file
+          end
+        else
+          # read the file into js_custom_add
+          path_js = path.nil? ? self.class.public : path
+          file_js = "#{path_js}/#{file.sub('.js','')}.js"
+          if test(?f, file_js)
+            js_custom_add(IO.read(file_js))
+          else
+            err_msg = "ERROR: js_custom_add_file(:insert_into_html) method could NOT find and embed this JS file=[ #{file_js} ]"
+            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 JS file
+      # and inserts its content into the current <tt>.js.erb</tt> file
+      #
+      # Depends upon the settings of the <tt>:js_source_files_dir</tt> configuration variable
+      # defined inside your application.  By default it is set to <tt>'/$HOME/.alt/css'</tt>
+      #
+      # ==== Examples
+      #
+      #   # in your app's routes configurations
+      #   get('/js/app.js') do
+      #     content_type 'application/javascript'
+      #     erb('js/app.js'.to_sym, :layout => false)
+      #   end
+      #
+      #
+      #
+      #   # in views/js/app.js.erb
+      #   js_insert_file('min/jquery') => path/2/js/files/min/jquery.js
+      #
+      # which inserts the JS code from that file into the output.
+      #
+      #
+      #
+      #
+      # @api public
+      def js_insert_file(path = '', local = nil )
+        file_path = local.nil? ? "#{self.class.js_shared_source_files_dir}/#{path}" : path
+        file_path = file_path.sub(/\.js$/,'') << ".js"
+        if test(?f, file_path)
+          content = IO.read(file_path)
+        else
+          content = "// ERROR: the JS file [#{file_path}] could NOT be found"
+        end
+        content
+      end
+      ##
+      # Outputs given custom JS if provided from within a view, helper method and so on
+      #
+      # ==== Examples
+      #
+      #   js_custom => <script...> var custom  = 'it works'; </script>
+      #
+      #
+      # You can also add the JQuery document.ready code to the output, by simply
+      # adding <tt>:jquery_block</tt> to the method.
+      #
+      #   <%= js_custom(:jquery_block) %>
+      #
+      #   <script type="text/javascript" charset="utf-8">
+      #     $(document).ready( function () {
+      #       // some custom JS code here
+      #     });
+      #   </script>
+      #
+      #
+      # @api public
+      def js_custom(js=nil, add_jquery_block = nil)
+        if js.is_a?(Symbol)
+          js = nil
+          add_jquery_block = :jquery
+        end
+        out = ''
+        out << js unless js.nil?
+        unless @sinatra_js_custom_code.nil?
+          @sinatra_js_custom_code.each { |i| out << "        #{i}\n" }
+        end
+        if add_jquery_block.nil?
+          code_js = out.strip
+        else
+          code_js = "$(document).ready( function () {\n   #{out.strip}\n  } );"
+        end
+        out = out.empty? ?
+          '' : %Q[<script type="text/javascript" charset="utf-8">\n#{code_js}\n</script>\n]
+      end
+      ##
+      # Outputs given custom JS files that have been included
+      #
+      # ==== Examples
+      #
+      #   <%= js_custom_files %> =>
+      #     <script src="/js/custom1.js" ...>
+      #     <script src="/js/custom2.js" ...>
+      #
+      # @api public
+      def js_custom_files
+        unless @sinatra_js_custom_files.nil?
+          out = "<!-- custom js files -->\n"
+          @sinatra_js_custom_files.each do |file|
+            # file = url_for("#{file.to_s.sub(/\.js$/,'')}.js") unless remote_asset?(file)
+            file = "#{file.to_s.sub(/\.js$/,'')}.js" unless remote_asset?(file)
+            out << js(file)
+            # out << %Q[    <script src="#{file}" type="text/javascript" charset="utf-8"></script>\n]
+          end
+          out << "    <!-- /custom js files -->\n"
+        else
+          '' # return empty string, it's better than nil in this case
+        end
+      end
+    end #/ Helpers
+    ##
+    # Handles all JS requests, and returns the RJS (RubyJS) 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/js directory in place.
+    #
+    # ie:
+    #   get_all_js_requests()  => expects a app/views/js dir with the .rjs files
+    #   get_all_js_requests('/javascripts')  => expects a app/views/js dir with the .rjs files
+    #
+    # ==== Examples
+    #
+    #   get_all_js_requests()                => catches 'site.com/js/app.js
+    #   get_all_js_requests('/javascripts')  => catches 'site.com/javascripts/app.js
+    #
+    # @api public
+    def get_all_js_requests(path='/js', options = {})
+      path, options = '/js', path if path.is_a?(Hash)
+      get("#{path}/*.js",  {} ) do
+        begin
+          options = { :cache => false, :layout => false }.merge(options)
+          content_type 'text/javascript', :charset => 'utf-8'
+          rjs("js/#{params[:splat].first}".to_sym, options ).gsub(/\n\r?$/,"")
+        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:
+    #
+    # * +:js_shared_source_files_dir+ => set the path to the Shared directory with compliled JS templates.
+    #   Default is: <tt>'ENV['HOME']/.alt/js'</tt>
+    #
+    # @api public
+    def self.registered(app)
+      app.register(Sinatra::Tags)
+      app.register(Sinatra::Assets)
+      app.helpers Sinatra::JS::Helpers
+      # set the path to the Shared directory with compliled JS templates
+      app.set :js_shared_source_files_dir, File.join(File.expand_path(ENV['HOME']) ,'.alt', 'js')
+      ## 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( js_shared_source_files_dir ).each do |m|
+          app.sinatra_settings_for_inspection << m
+        end
+      end
+    end #/ self.registered
+  end #/ JS
+  register(Sinatra::JS)
+end #/ Sinatra