About

CSSPP is a PHP based cascading stylesheet preprocessor intended to extend the capabilities of CSS beyond specification, reduce typing and ease production of more modular/logical standards compliant css files.

Used and tested on a few production sites, it has allowed highly effective, clean, and quick output of complex layouts. Now free to the public; available as zip file or at framwurk.org subversion repository. Accepting patches, bug reports, ideas and better example/documentation content.

1. Features

• Constants - change values throughout one or multiple stylsheets with less keystrokes
• Rule inheritance - make libraries of easily modifiable css
• Includes - recursive inclusion of multiple css files
• Formats and compresses whitespace, stripping single and multi-line comments
• Smart caching engine handles rerendering when masters have changed

2. Installation

Download http://framwurk.org/data/csspp-0.9.1.zip and extract the directory csspp into your host's document root. Alternatively, you may export the code from the framwurk.org subversion repository into a directory named 'csspp':

            
svn export https://svn.framwurk.org/~/csspp/trunk csspp

Here is an example of a document root tree with the css preprocessor in place

Create an .htaccess file in the document root with the following contents:

 # Turn on Rewriting
 RewriteEngine   On
 RewriteBase   /
 # CSS Preprocessor
 RewriteCond   %{REQUEST_URI} \.CSS$
 RewriteCond   %{REQUEST_FILENAME} !-d
 RewriteRule   ^(.+)$ /csspp/process.php?css=%{REQUEST_FILENAME} [L]

This will effectively redirect all requests to filenames with a .CSS extension to the css preprocessor (leaving your *.css files alone).

The system you are on should support case-sensitive file names (linux, osx, unix, etc), otherwise you must modify the rewrite above (and process.php) to use another expression and conditions.

Change the permissions of /csspp/cache/ directory to 771, so that the cached files dont leak out for any reason.

You should now be able to request http://example.com/stylesheet-to-process.CSS (or the path/name of your style sheet) to output the stylesheet preprocessed into valid css.

3. Usage

You may insert a style sheet with the extension .CSS (capitalized; instead of .css) anywhere in the document root and it will be automatically preprocessed.

Your style sheet should be valid and clean with semi-colons in the right places... no error recovery implemented yet.

<link rel="styleshet" type="text/css" href="/styles/parse/me.CSS" />

You may change the sequence options before the call to parse() in process.php like so (the default options shown):

$csspp->sequence_options = csspp::COMMENTS|csspp::CONSTANTS|csspp::BASES|csspp::NESTED|csspp::FORMAT|csspp::TIMESTAMP|csspp::INCLUDES;

Contact

4. Syntax

4.1 Includes

Include a file on the server side. Paths are relative to the current file.

@include (../path/relative/to/the/current/file.CSS);

Contents

4.2 Constants

Constants can be defined in singular or plural forms:

@constant name:value;

@constants {
name:value;
...
}

An example of using a constant to set the body's background-color:

@constant background_color:red;

body {
background: background_color;
}

generates:

body {
background: red;
}

4.3 Variables

As of version 0.8, this is disabled by default. Variables can be passed via the query string. Any variables defined are replaced with the $_GET array from php. They can be enabled via options.

It is against recommendation to use variables in production enviroments as they can cause the stylesheet to recompiled on every request; leaving a hole for a potential denial of service.

@variable $background_color:white;

body {
background:$background_color;
}

when accessed with http://example.com/styles/test.css?background_color=red, will generate:

body {
background:red;
}

Above, $background_color's default is set to white.

Contents

4.4 Single Inheritance

rules can be nested

body {
..blue {
background:blue;
}

..red {

background:red;
}

.box {
background:green;
}

h1 {
font-size:1.6em;
}

h2 {
font-size:1.4em;
}
}

produces:

body.blue {
background:blue;
}

body.red {

background:red;
}

body .box {
background:green;
}

body h1 {
font-size:1.6em;
}


body h2 {
font-size:1.4em;
}

Contents

4.5 Multiple Inheritance

One can also pull in properties from multiple "abstract class"-type rules.

@abstract base_class {
padding:1em;
}

body {
extends:base_class;
background:blue;
}

generates

body {
padding:1em;
background:blue;
}

Contents

4.6 Comments

Comments can be inserted for multiples lines like:

/*
Multiple line comments
...
*/

and for single lines like:

// single line comment

4.7 Prevent processing

to prevent processing of the file, even if it is named *.CSS, prepend @nopp inside of it.

• TODO: prevent stripping of comments

@nopp

5. TODO

• DONE: configurable styles directory (0.9)
• DONE: change @base to @abstract (permitting @base for backwards compatibility) (0.9)
• DONE: simplify installation, usage, configuration (0.9)
• DONE: better security (chroot-like). currently, only allows access to files with .CSS extension (0.9)
• Nested base/abstract classes (1.0)
• expression evaluation (1.0)
• real error recovery... handle at least some form of dirty css, mark with a comment as /* dirty */ (projected 1.0)
• IDEA: Convert this into an installable apache module that parses server side (?)

6. Related Work

• Shaun Inman's Cacheer
• XCS
• Early design idea mention: Chris Heilmann
• The DtTvB's CSS Preprocessor

This work is licensed under a Creative Commons Attribution-No Derivative Works 3.0 Unported License.