Rcss - CSS Server-side Constants for Ruby/Rails

Information for version 0.3.0

Rcss implements CSS-SSC in Ruby.

Main features:

• Create rich CSS files using:
  • ERB templates
  • Server-side constants
  • Server-side classes (preliminary)
• Simply add Rcss files to any Rails application
• Process Rcss files off-line using command line executable

Introduction

Rcss addresses issue of CSS maintainability. Even a minor change in complex stylesheet usually requires using search-and-replace. A simple way to fix this flaw is to allow some kind of constant/variable substitution inside CSS. Using Rcss you can achieve that in three ways:

ERB templates

ERB templating is the most flexible solution. It uses standard ERB syntax (the same you can find in rhtml files). ERB allows you to inlude in the CSS values defined in controller. This gives access to database through ActiveRecord and allows database-driven CSS themes.

Strengths

• Access to application data (through ActiveRecord)
• Flexible Ruby syntax (allowing programmatic CSS)

Weaknesses

• Syntax unfamiliar to CSS designers
• A bit ugly and sometimes error-prone embedding
• Not portable

Example

  <% template_color = "#000"
     template_background = "#fff"
     template_highlight = "#fa3"
  %>
  body {
        color: <%= template_color %>;
        background-color: <%= template_background %>;
  }

  h1 {
        color: <%= template_background %>;
        background-color: <%= template_highlight %>;
  }

Server-side Constants

Server-side Constants were originaly developed by Shaun Inman in PHP. SSC extends CSS syntax in a simple way. SCC is cross-platform and easy to use.

Rcss differs from original implementation in two ways :

• Constants may have complex values (including spaces and commas)
• Includes are not implemented

Strengths

• Simple syntax
• SSC-CSS files can be used in both Rails and PHP applications

Weaknesses

• Only simple constant substitution

Example

  @server constants {
    template_color: #000;
    template_background: #fff;
    template_highlight: #fa3;

    // Rcss specific (note spaces and commas)
    template_font: "Trebuchet MS", "Bitstream Vera Sans", helvetica, sans-serif;
  }

  body {
        color: template_color;
        background-color: template_background;
        font-family: template_font;
  }

  h1 {
        color: template_background;
        background-color: template_highlight;
        font-family: template_font;
  }

Server-side Classes (preliminary)

Warning This functionality is subject to rapid change and future versions might not be compatible with current implementation.

Server-side Classes add multiple inheritence to CSS selectors. Now you can ‘virtual’, server-side selectors and use them to extend normal selectors. It is just a simple way of inheriting several attributes at once. Together with two technics described above they give a very powerfull tool to create maintainable CSS files.

Strengths

• Simple syntax
• Specify multiple related attributes at the same time

Weaknesses

• Syntax is subject to change
• No templating yet

Example

  @server &serif_font {
        font-family: "Trebuchet MS", "Bitstream Vera Sans", helvetica, sans-serif;
  }

  @server &highlighted {
    color: #000;
    background-color: #fa3;
  }

  h1 {
        extends: &highlighted;
        extends: &serif_font;
  }

  #menu {
        extends: &highlighted;
  }

Installation

Using RubyGems

Download and install Rcss with the following command:

   gem install --remote rcss

Manual

Download archive file from Rcss project page: rubyforge.org/projects/rcss and install it with following command

  # ruby install.rb

Usage

Command line

NAME

     rcss - process rich CSS files

SYNOPSIS

     rcss [RcssFile]

DESCRIPTION

     Reads and processes rich CSS files. Processed file is printed to standard
     output. If no file is given standard input is processed instead.

EXAMPLE

     rcss default.rcss >default.css

     Will read contents of default.rcss file, evaluate ERB templates, server
     side constants and classes. Output will be redirected to default.css file.

Rails

Follow this steps to use Rcss in Rails environment:

1. Modify your config/environment.rb file and add following line:

    require 'rcss'
   

2. Create controller that will be serving Rcss files. Create app/controllers/rcss_controller.rb file with following content:

    class RcssController < ApplicationController
      def render_rcss
        if params[:rcss] =~ /\.css$/
          template = $`
            else
              template = params[:rcss]
        end
        render :action => template, :type => 'rcss', :layout => false
      end
    end
   

3. For convenience add route entries that will handle Rcss files. Modify file config/routes.rb and add following lines before the default route:

     map.connect 'rcss/:rcss', :controller => 'rcss', :action => 'render_rcss'
     map.rcss 'rcss/:rcss', :controller => 'rcss', :action => 'render_rcss'
   

4. Create following test Rcss file app/views/rcss/test.rcss:

    <% test_color = "#000" %>
   
    @server constants {
      test_background: #fff;
    }
   
    @server &test_class {
      color: <%= test_color %>;
      background-color: test_background;
    }
   
    body {
      extends: &test_class;
    }
   

5. Start your Rails application

    $ ruby scripts/server
   

   Point your browser to location: localhost:3000/rcss/test.css You should see following content:

     body {
       color: #000;
       background-color: #fff;
     }
   

Rcss Syntax

Rcss file is processed in three stages:

1. The ERB template is applied
2. Server-side constants are gathered
3. Server-side constants are evaluated
4. Server-side classes are gathered
5. Server-side classes are evaluated

Server-side Constants Syntax

SSC block has following template:

  @server constants {
    constant_name: value;
  }

Also for compatibility older version is supported:

  @server variables {
    variable_name: value;
  }

There might be several constants/variables blocks in the same file. It does not matter where in CSS file they appear, their contents are still applied to whole file.

When a constant is redefined only later occurence is taken into account so:

  template_color: #fff;
  ...
  template_color: #000;

…will result in template_color having value 000 in all places.

To use constant’s value simply type it’s name anywhere in the code:

  body {
    color: constant_name;
  }

Note that since enything can be constant’s value it is also possible to use it to hold attribute or even selector:

  @server constants {
        body: #fff;
  }

  body {
        color: body;
  }

This will be evaluated to

  #fff {
    color: #fff;
  }

..which probably is not what one might expect. For that reason avoid using CSS selector and attribute names as constant names.

Server-side Classes Syntax

Server-side classes are defined using following template:

  @server &class_name {
        // normal CSS content
  }

The ampersand & before class name is mandatory.

To include server-side class in CSS selector use extends attribute:

  body {
    extends: &class_name;
  }

Server-side classes may also extend existing ones:

  @server &highlighted {
    background-color: #fec;
    color: #fff;
  }

  @server &header {
    extends: &highlighted;
    font-weight: bold;
  }

  h1 {
    extends: &header;
  }

  #menu {
    extends: &highlighted;
  }

In case of complex extending order in which server-side classes appear in the file is important. Class must be already declared before it is used - otherwise it will be evaluated to an empty string.

Credits

Shaun Inman

For the original PHP version of CSS-SSC

License

Rcss is available under an MIT-style license.

Copyright © 2005 Lukasz ‘Bragi Ragnarson’ Piestrzeniewicz

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.

Other stuff

Author:	Lukasz ‘Bragi Ragnason’ Piestrzeniewicz <bragi dot ragnarson at gmail dot com>
Requires:	Ruby 1.8.0 or later Rails 0.13.0 or later

Web pages

• Rcss Documentation: rcss.rubyforge.org
• Rcss Project Page: rubyforge.org/projects/rcss
• Developer’s Blog: ragnarson.blogspot.com

Warranty

This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.