CSScaffold v1.5.0b6

These docs are a work-in-progress. All the information you should need is here, but there's still a lot of work to be done.

Overview

Scaffold is a new type of CSS framework, built with PHP, that allows speed up your development time by doing the hard work for you. It is different to other CSS frameworks, like Blueprint and 960.gs, but it's power lies in it's ability to extend the CSS language. You can even generate the CSS found in other CSS frameworks dynamically, like grid classes to quickly build layouts.

It will change the way you write and manage your CSS.

How it works

Scaffold sits in your CSS directory, and uses .htaccess files to automatically pass any CSS file through Scaffold first for processing and caching - it all happens in the background. Just drop the files onto your server and you're ready to go with the CSS you've already written.

Features

Written exactly like CSS, so you don't have to learn a new syntax
Use constants within your CSS
Use mixins like in SASS and Compass
Nest selectors to tidy up your code
Optimize, compress and gzip
Generate test suites for typography, layouts and form styles
Plugin architecture that lets you extend the language the way you want
and much more!

Requirements

The only requirements are a webserver running PHP 5+. You need to be able to use .htaccess files if you want automatic parsing of your CSS files (An apache-like server).

Download

You can download the latest version directly from Github in the downloads section. You can also download the latest source (note: It might have a couple of untamed bugs).

Upgrade Notes

Upgrading Scaffold shouldn't break you're CSS, unless it's a jump from a point verion (1.5 to 1.6), where you might be at risk as some syntax may change.

However, the syntax is locked in for good now, so you shouldn't have any issue simply replacing the Scaffold folder on your server with the latest version, but just keep this in mind.

Release notes

Support

If you're having any issues installing or using Scaffold, have any suggestions, bugs or critique, you can send an email to csscaffold@me.com.

Please note that under Scaffold's license, I hold not accountablity for breaking your site, costing you money or otherwise harming you commercially or financially. This is an MIT-licensed project simply out there for those that care to use it at their own risk.

License

This software is released under the terms of the New BSD License.

User guide

Installation

Download the latest release of Scaffold.
Rename the downloaded file to scaffold
Place all the files inside your css directory on your webserver. e.g /themes/css/scaffold/
Move css.htaccess into your css directory (one level up) and rename to .htaccess
Rename example-config.php to just config.php
Change any configuration options in scaffold/config.php
If all is well, when you view your CSS file in a browser, it will be parsed.

Install with Git

cd path/to/css/directory
git clone git://github.com/anthonyshort/csscaffold.git scaffold
git mv scaffold/css.htaccess .htaccess

The Basics

Now that you've installed Scaffold, you can see your parsed CSS file in one of 2 ways; If you're using the .htaccess file, you can call your CSS files as normal and if you're not, you can manually pass the CSS through Scaffold.

Method One

http://localhost/css/screen.css

Method Two

http://localhost/css/scaffold/index.php?request=/css/screen.css

Forcing a recache

If you've got always_recache turned off, but have only modified included files (Scaffold won't know the main CSS has changed) you can use recache as a URL parameter to force it to recache.

http://localhost/css/screen.css?recache

The best method is to turn always_recache on while developing so you don't ever need to force a recache, and when you send the CSS live, change IN_PRODUCTION and cache_lock to true.

Constants

You declare constants using a syntax similar to normal css:

@constants 
{
	normal_color:#eee;
	other_constant:10px;
}

We've defined two constants - 'normal_color' and 'other_constant'- to use those constants, we do this:

body
{
	color:!normal_color;
}

It doesn't matter where you define your constants, they can't be set again like variables. Once they are set, they are saved for good. You can also define constants inside config.php if there are any you can't set with CSS alone.

Expressions

You can parse parts of your CSS as PHP:

#id 
{
	padding:#[10 * !constant]px;
}

Anything you place inside the square brackets will be parsed as PHP.

Includes

One of the great things about Scaffold is that it combines all of your CSS into one file. Scaffold imports the files server-side before it's cached and sent to the browser. This means you'll only send 1 file, not 4 or 5.

@include '/css/sections/layout.css';

There are a couple of other things you can do also - You don't need the extension of CSS files and you can use the ~ to reference the css directory. For example, this will also work:

@include '~/sections/layout';

Iteration

You can loop through to build selectors, just like a for loop in PHP. This is how the grid mixin uses it to generate the grid classes:

@for !i from 1 to 12
{
	.columns-!i { +span(!i); }
}

Mixins

Mixins are like functions for CSS, and they are by far the most powerful element of Scaffold. They let you define property groups that can be reused or extended upon. They can have parameters and they can nested within each other. Mixins were ported over from SASS.

This is the basic mixin syntax:

=mixin-name(!param, !param2 = 10)
{
	color:!param;
	border:!param2 solid !param;
}

Then you assign it to a selector:

#id 
{
	+mixin-name(#eee);
	padding:10px;
}

You can use mixins to intelligently extend other property groups:

=box(!color)
{
	padding:10px;
	border:1px solid !color;
	color:!color;
}

=error
{
	+box(red);
	background:red;
}

=alert
{
	+error;
	background:yellow;
}

Now when you change the 'box' style, you change it everywhere. The organisational benefits of using mixins are huge. You can keep all of your styles for a particular element in one spot, and simply extend properties where needed. This makes your CSS file much more manageable.

Mixins don't need parameters either, as shown above.

Built-in Mixins

Scaffold comes with many mixins already made for you to abstract the more tedious elements of CSS. For example, clearing a container is usually done like this:

.clearfix
{
	zoom:1;
	display:block;
}

.clearfix:after 
{
	content:'\\0020';
	display:block;
	height:0;
	clear:both;
	visibility:hidden;
	overflow:hidden;
	font-size:0;
}

You might add every selector to this as you go, making the selector very long, not to mention you need to remember it everytime. Scaffold makes it easy.

#id { +clearfix; }

That's it. Just add the clearfix mixin to any selector you want to add it to. Scaffold will do the rest of the work of adding the properties so you don't need to remember it in every project.

It also adds more meaning to your CSS - people who read your stylesheets will know exactly what's going on. Using the first method, it's messy and there's no real meaning behind all of the those properties, people might not know what they're doing.

Using mixins, you get the benefit of adding semantics to your CSS and making it much cleaner at the same time.

Some of the included mixins:

+border-radius
+box-shadow
+clearfix
+has-layout
+container
+opacity
+move
+reset

Full list of included mixins ›

All of the included mixins are stored in scaffold/framework/mixins. Have a look through those files to see all of the mixins you have in your toolkit, or read through the complete list here in the documentation.

Nested Selectors

By nesting selectors, you save yourself from writing the same code over and over and it ultimately makes your CSS much easier to read and navigate. It's pretty simple:

#id
{
	color:#000;
	padding:10px;
	
	a 
	{ 
		color:#ff0;
		
		&:hover { text-decoration:underline; } 
	}
	
	h1,h2,h3,h4,h5,h6
	{
		border-bottom:1px solid #eee;
		padding-bottom:10px;
		
		&:first-child { margin-top:0; }
	}
	
}

This will render this CSS:

#id { color:#000; padding:10px;}
#id a { color:#ff0; }
#id a:hover { text-decoration:underline; }
#id h1, #id h2, #id h3 { border-bottom:1px solid #eee; padding-bottom:10px; }
#id h1:first-child, #id h2:first-child ... { margin-top:0; }

It's fairly obvious which is easier to read and update.

Using the parent element - `&`

One thing you'll notice above is that you can use the & to reference the parent element. So in the case of &:hover above, it's really saying a:hover.

Custom Output

Custom output allows modules and plugins to output something other than the CSS file. It could be a layout test page, test markup, validation etc.

Custom output will not work when in production mode.

Typography test suite - Example

The typography test suite creates a page with nearly every html element which is attached to the processed CSS. This allows you to easily see what you're styles look like, without writing a single line of html.

http://localhost/css/screen.css/typography/

Validate - Example

The validate module allows you to validate your CSS using the W3C validator before sending it to the browser. To use it, simply add validate to your URL. Instead of displaying your CSS, it will display any validate errors. Eg:

http://localhost/css/screen.css/validate/

Grid - Example

If you're using the Layout module, you can view your grid as output, so you can test it out and adjust it to your liking.

http://localhost/css/screen.css/grid/

Plugins

Scaffold can use plugins to extend it's capabilities even further. Plugins are extremely easy to create and have all of the same functionality as the built-in modules.

Enabling a plugin

To enable a plugin, place the folder in the scaffold/plugins/ directory and add the plugin name to your config.php file in the plugins array. These two plugins are included for you.

Image Replace

The image replace plugin creates a new property called image-replace. You simply give it a url, like a normal image in CSS, and it will image replace that element for you. Here's an example:

#id 
{
	image-replace:url(/path/to/image.png);
}

Which might render this:

#id
{
	text-indent:-9999px;
	height:20px;
	width:240px;
	background:url(/path/to/image.png) no-repeat 0 0;
	display:block;
	overflow:hidden;
}

It finds the image and does all of the hard work for you.

XML Constants

This plugin allows you to set constants using an XML file. You simply edit the config in scaffold/plugins/xml_constants/config.php with the path to an xml file that looks like this:

<?xml version="1.0" ?>
<constants>

	<constant>
		<name>Foo</name>
		<value>Bar</value>
	</constant>

</constants>

You can then use the constant !Foo in your CSS. This becomes useful when you use a CMS, like ExpressionEngine or Wordpress, to set constants for categories or tags, then you can use them in your CSS to style your pages.

Advanced Usage

Folder structure and files

Getting to know the Scaffold folder structure will make it easier to understand and will make the learning curve a little bit smaller.

Inside the scaffold directory you have:

cache

This stores the parsed CSS files and any other files created by Scaffold

example-config.php

Rename this to config.php. The global configuration for Scaffold. You can activate plugins in here and turn a lot of functionality on and off. Be sure to have a good look through here before anything else to customize Scaffold.

css.htaccess

This .htaccess file should be placed in your CSS directory and renamed to just .htaccess. The lines pointing to the scaffold folder will need to be adjusted manually if you don't keep Scaffold in your CSS directory.

framework

This stores all of the templates, mixins, behaviours and grids used by Scaffold. The system may open up the functionality, but the framework folder is what gives you a jump-start when building your CSS. Take a look through this folder and take note of the Mixins you can use in your projects.

Any CSS file placed in the mixins directory is automatically included (you can turn this off), but not all mixins have to reside in here.

index.php

The front controller for Scaffold. CSS is passed to this file via the request POST variable. You can set paths to Scaffold folders in here if you need to.

plugins

You can create plugins for Scaffold and drop them in here. There are a few plugins in there already to give you an idea of what you can do.

system

Scaffold core functionality resides in here. You shouldn't need to change anything in here.

Configuration Options

Scaffold's configuration is stored in scaffold/config.php and it's paths and constants are stored in scaffold/index.php.

INSTALL: Setting this to true will cause Scaffold to run the path checking script rather than outputting the file. This will check all of your paths and make sure Scaffold can find them all.
IN_PRODUCTION: Setting this to true will cause no errors to be thrown and the CSS will never be recached. This overrides the cache_lock.
cache_lock boolean: Scaffold recaches the CSS file if the CSS has been changed, however, you can lock the cache so it is never recached. You usually do this when you send your site to production.
always_recache boolean: If you want Scaffold to always recache the files, set this to true. Scaffold doesn't know if included files have been changed, so if you're working on an included file, and refresh the main CSS file, it won't recache. To counter this, turn this option on. It's useful to have this on during development. However, you can use the recache url parameter instead.
show_header boolean: Scaffold outputs some information at the top of the CSS file, you can turn this on or off.
auto_include_mixins boolean: Scaffold automatically includes all the CSS files inside scaffold/framework/mixins so that you don't have to include them one-by-one yourself. Turning this off can speed up Scaffold.
override_import boolean: The syntax for including files is @include, however, if you'd rather just use the standard @import, turn this on.
absolute_urls boolean: If your calling Scaffold using the second method, that is, manually passing the CSS files through the index.php, the browser will assume all image paths are relative to the index.php file. You can either move the index.php file and change the paths, or set this to true. All image paths will be renamed to absolute URL's. This is not 100% effective.
use_css_constants boolean: Scaffold uses the SASS syntax for constants !constantname, however, if you'd like to use a syntax which is closer to that of the proposed CSS constants, use can turn this on. Constants are then used const(constantname)
minify_css boolean: You can use the minify library to compress your CSS. Minify strips all unnecessary whitespace, empty and redundant selectors etc. By setting this to false, instead of minifying your CSS, it will prettify it, making it easier to read instead of worrying about compressing down the size.
constants array: An array of values for creating CSS constants. This is useful for constants that you can't set in the CSS, for example, PHP version or SERVER info.
debug: Turn on FirePHP log and errors messages. These message will output to Firebug.
language: Set the language. Scaffold comes with English only at the moment.
plugins: Plugins are activated by adding them to this array and setting their value to true.

Custom Paths

You can change the paths for Scaffold so you can customize the folder structure to work with your server setup. The paths you can change in index.php are:

All of these paths are relative to index.php. If you move index.php, you'll need to change these paths accordingly.

document_root: Set the document root of your server using the full server path. You should only need to set this if your server doesn't support $_SERVER['DOCUMENT_ROOT']
css: The path to the CSS directory. This can be relative to the index.php file, or from the document root.
scaffold: The path to the scaffold directory. This is either relative to the index.php file, or from the document root.
system: The path to the system directory inside the scaffold folder. Can be relative to the index.php or from the document root.
cache: The path to the cache directory inside the scaffold folder. Can be relative to the index.php or from the document root.
plugins: The path to the plugins directory inside the scaffold folder. Can be relative to the index.php or from the document root.

Layout Module

The layout module allows you to create layouts with pure CSS very quickly. It generates grid structures similar to Blueprint and 960.gs. The difference is that you can make the grid just about anything you want.

If you’ve used either of these CSS frameworks before, you’ll already know how you can create layouts by using classes, like so:

<div class="columns-12 last"></div>

Creating layouts this way is very easy, but it’s not entirely semantic - we want to try and remove as much of this style from the markup as possible. The layout module, along with mixins, solves this problem.

Using the layout module

To use the layout module, all you have to do is setup your grid inside your CSS:

@grid
{
    column-width:60;
    column-count:12;
    left-gutter-width:10;
    right-gutter-width:10;
    baseline:18;
}

This particular @grid creates the 960.gs style of grid. Each column (which is usually a div), has a left and right margin of 10px and a single column is 60px wide.

Test out your grid

To see your new grid, locate your CSS file in the browser, and add /grid/ to the end of the url like so:

http://scaffold/stylesheets/master.css/grid/

You should see a page will red columns cascading down the page. Each of these columns has been created dynamically. Change the @grid settings and refresh this page to see the changes.

Background Grid Image

By adding the grid settings, you also have access to a class which is automatically added to your CSS called .showgrid. Adding this class to an element which display the grid behind it for reference.

Grid Classes

Like I mentioned earlier, if you’ve used 960.gs or Blueprint, you’ll know how these frameworks use pre-built grid classes to build layouts. Scaffold creates these for you as well. You have:

.columns-#: Makes the div sddan a ddarticular number of columns across
.push-# and .pull-#: Moves the column across the grid x number of columns
.append-# and .prepend-#: Adds x number of columns to the total width of the column
.baseline-#: Makes the column x baseline heights high.
.baseline-up-# and .baseline-down-#: Moves the column udd and down the baseline
.container: Creates a container for grid columns which sits in the middle of the page and spans the total width of the grid.
.first and .last: Removes left or right margin respectively.

Grid Mixins

Scaffold creates mixins which mirror all of the classes above. In fact, the mixins actually create those classes. You can see this in action in scaffold/framework/mixins/layout/grid.css.

These allow you to do exactly the same thing as the classes above, but you don’t have to litter your markup. You do this instead:

#id
{
    +columns(4);
}

This div will span exactly 4 columns across and have all the properties needed to function as a column.

For full reference as to what all the mixins do, become familiar with scaffold/framework/mixins/layout/grid.css.

CSScaffold v1.5.0b6

Overview

How it works

Features

Requirements

Download

Upgrade Notes

Release notes

Support

License

User guide

Installation

Install with Git

The Basics

Method One

Method Two

Forcing a recache

Constants

Expressions

Includes

Iteration

Mixins

Built-in Mixins

Full list of included mixins ›

Nested Selectors

Using the parent element - &

Custom Output

Typography test suite - Example

Validate - Example

Grid - Example

Plugins

Enabling a plugin

Image Replace

XML Constants

Advanced Usage

Folder structure and files

Configuration Options

Custom Paths

Layout Module

Using the layout module

Test out your grid

Background Grid Image

Grid Classes

Grid Mixins

Using the parent element - `&`