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 ( >= 0.1.0 )
sinatra-outputbuffer ( >= 0.1.0 )
sinatra-basics ( >= 0.5.0 )

Optionals:

sinatra-settings (>= 0.1.1) # to view default settings in a browser display.
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:

`js() / javascript()`

This method serves two purposes:

a) Return a stylesheet <script src=""></script> tag with the path 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 <script> 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 <script> 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>

`js_custom() & js_custom_add()`

These two methods works together, like this:

First you add the js_custom() method to your layout(s) (../views/layout.erb):

<html>
  <head>
    <snip...>

    <%= js_custom %>

  </head>

Then in your views, you can use the js_custom_add() 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 <head> 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.

`js_custom_files() & js_custom_add_file()`

These two methods also works together in a similar fashion, like this:

First of, add the js_custom_files() method to your layout(s) (../views/layout.erb):

<html>
  <head>
    <snip...>

    <%= js_custom_files %>

  </head>

Then in your views, you can use the js_custom_add_file() 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 <head> 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>

`js_insert_file()`

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 :js_shared_source_files_dir configuration variable defined inside your application.

By default this is set to 'ENV['HOME']/.alt/js'.

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 public/js/ directory by adding the :local 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: 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.