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 ( >= 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::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:

`css()`

This method serves two purposes:

a) Return a stylesheet <link> tag with the path 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 <style> 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>

`css_custom() & css_custom_add()`

These two methods works together, like this:

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

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

    <%= css_custom %>

  </head>

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

`css_custom_files() & css_custom_add_file()`

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

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

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

    <%= css_custom_files %>

  </head>

Then in your views, you can use the css_custom_add_file() 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 [ filename, media ] 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>

`css_insert_file()`

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

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

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