Permalink
Browse files

Merge branch 'release-2.0.1'

  • Loading branch information...
2 parents 3c6039d + 28dd433 commit 96be02c5805eeb19d6f298f31875a22b86085a04 Anthony Short committed Feb 3, 2010
Showing with 327 additions and 2 deletions.
  1. +17 −2 HISTORY.txt
  2. +310 −0 README.md
View
@@ -1,5 +1,20 @@
Scaffold Release Notes
Version 2.0.0
- * Comments can now be left within the CSS after parsing
- * Folder structure changed
+ * Constants use the PHP variable style now - $constant - This means it can parse the constants in the CSS super fast.
+ * PHP now sets the Expires header, rather than using the .htaccess, and a lot of other caching headers. It should pass YSlow with an A every time.
+ * You can pass multiple files to Scaffold at once like so: http://localhost/scaffold/?f=/css/master.css,/css/type.css,/css/other.css
+ * It's now completely modular. Other applications/frameworks should be able to integrate Scaffold fairly easily. You can use the Scaffold::parse function to just return the result of a parsed CSS file rather than displaying it to the browser.
+ * Logs - Scaffold can now log errors and other messages to the logs directory. You can set level of message it logs or will throw as an error (error, warning, info or debugging message).
+ * Scaffold now retains CSS-style comments
+ * Much better caching. Scaffold now caches the completely parsed request for a single group of files for a set amount of time. You can set this in the config. By default, it will check every hour if it needs to recache (only while in production).
+ * There's a new extensions folder. In here you can drop single PHP functions to create new properties and CSS functions. Take a look at what I've already made, it's really easy to do. Just have the function return whatever you want the original string replaced with.
+ * As well as enabling easy extensions, I've added LOT of functions and a couple of properties. Things like cmyk(), embed(), rand().
+ * There's a new config folder, which is where all the config files for each module are stored.
+ * New module: Absolute Urls - rewrites all URL's to be absolute so they will never break. Previously, if you called Scaffold manually (scaffold/index.php?blah) the browser would be looking for the CSS images in the scaffold directory. This just makes everything easier.
+ * New module: Firelog - Uses FirePHP to log a lot of information to Firebug. It also enables FirePHP for other modules to use.
+ * New module: Flags - You can have chunks of your CSS only show for certain flags. Eg. @flag(morning) { background:blue; } This will only show if the morning flag is set. Flags are set by modules.
+ * New module: Gradient - You can create simple gradients using the property background-gradient: direction, size, start colour, end colour. Direction can get vertical or horizontal. You need to set a size too, if it's a vertical gradient, the size will be use for the height, and vica versa for horizontal. Eventually I'll add the ability to do more complex gradients.
+ * New module: Time - Lets you set flags based on time. Take a look at the Time config file for an example.
+ * New module: Formatter - This is the combined Pretty and Minify module. You can set various options for this in it's config file.
+ * Various bug fixes
View
@@ -0,0 +1,310 @@
+# Scaffold CSS Framework
+
+Scaffold is a CSS framework and pre-processor that lets you extend the CSS language easily. You just pass your CSS files through Scaffold and you have access to all of the new functionality.
+
+## Requirements
+
+PHP5+
+
+## Setup
+
+Put the scaffold folder somewhere on your web server. Then link to your CSS files in your HTML like so:
+
+ <link rel="stylesheet" href="scaffold/index.php?f=/stylesheets/master.css" />
+
+You can pass through multiple files at once by separating the file names with a comma.
+
+ <link rel="stylesheet" href="scaffold/index.php?f=/stylesheets/master.css,/stylesheets/another.css" />
+
+And you can define a base path
+
+ <link rel="stylesheet" href="scaffold/index.php?d=/stylesheets/&f=master.css,another.css,type.css" />
+
+### Automatically parse your CSS using .htaccess
+
+You can use a .htaccess file to automatically pass any requests to CSS files to Scaffold. You might use something like this:
+
+ <IfModule mod_rewrite.c>
+ RewriteEngine on
+ RewriteCond %{REQUEST_FILENAME} -f
+ RewriteCond %{REQUEST_URI} \.css$
+ RewriteRule ^(.+)$ scaffold/index.php?f=%{REQUEST_URI}&%{QUERY_STRING}
+ </IfModule>
+
+You would place this in the CSS directory (which also contains the scaffold directory), and any CSS files requested from this directory or deeper are passed through Scaffold first. Explaining this .htaccess file, or getting it to work with your exact setup is out of the scope of this documentation, as it will vary in each environment depending on how you are using Scaffold.
+
+### Configuration
+
+The config for Scaffold itself, is called config.php and is inside the scaffold folder. The configuration for each module is stored within the config folder inside the scaffold folder.
+
+To get Scaffold to work correctly, you may need to modify some of the settings inside config.php.
+
+## Usage
+
+Once you've setup Scaffold, and you can see your CSS files being parsed by it, you'll want to know what you can do. The bulk of Scaffold's functionality is contained within **modules** and **extensions**.
+
+### What are Modules and Extensions?
+
+#### Modules
+
+Modules are classes which use hooks within Scaffold to do various things to the CSS. In 2.0, however, they can hook into the core functionality of Scaffold to do just about anything they want. You might want to do custom caching or modify the files before processing.
+
+#### Extensions
+
+The extensions are simple PHP functions that Scaffold uses to create custom properties and CSS-style functions (like url()).
+
+### Included Modules
+
+It wouldn't be much of a framework if it didn't include a lot of useful modules. Scaffold includes:
+
+- **Absolute URL**: Convert url paths in your CSS into absolute path relative to the document root.
+- **Constants**: Set and use constants within your CSS. You can even use an xml file to load constants from an outside source.
+- **Extensions**: Enables the use of extensions allowing you to create custom properties and CSS functions without needing an entire module
+- **Firelog**: Outputs various information to Firebug if you have the FirePHP extension installed.
+- **Flags**: Have different caches depending on certain conditions. For example, you can set certain CSS to only appear in the morning, or only show to particular browser.
+- **Formatter**: Minify your CSS before it's cached to save on size, or format your CSS in a way that it's easily readable.
+- **Gradient**: Create gradient background images right within your CSS that are created on the fly. It makes creating buttons a snap.
+- **Import**: Lets you include other CSS files to be compiled as one file. This means it's sent to the browser as one file instead of many. It's way better than the standard @import
+- **Iteration**: Use PHP-style for loops to generate CSS
+- **Layout**: Generate grid CSS classes and mixins on the fly. It creates Blueprint-style grid classes based on a custom grid.
+- **Mixins**: Extend selectors using base sets of properties that can take parameters.
+- **Nested Selectors**: Nest selectors as complex as you'd like.
+- **Time**: Create custom time periods where certain CSS will be displayed - like Christmas or Halloween.
+- **Typography**: Generate a specimen sheet of all the HTML elements and the styles your CSS applies to them.
+- **Validate**: Use the W3C CSS validator to validate your CSS.
+
+### Included Functions
+
+- **rand(from,to)**: Lets you generate a random number between two other numbers
+- **baseline(n)**: Using the layout module, this multiplies the baseline by n
+- **baseline_round(n)**: Similar to the above, but you can put in any number, and it will round to the nearest baseline unit.
+- **calc(expression)**: Evaluate math expressions.
+- **cmyk(c,m,y,k)**: Input CMYK values, and the output is a simple hex value.
+- **cmyka(c,m,y,k,alpha)**: Similar to the above, but you can define an alpha value.
+- **embed(path)**: Embed an image in the CSS. Used as a replacement for url()
+- **enumerate(string,from,to,seperator)**: Generate a string from one value to another.
+- **hsl(hue,saturation,brightness)**: Returns a simple hex value
+- **hsla(hue,saturation,brightness,alpha)**: Well, you get the point.
+
+### Included Properties
+
+- **background-gradient: (vertical|horizontal), size, from, to**: Create a gradient background image.
+- **image-replace:url()**: Replaces text with an image.
+
+## Constants
+
+Constants are set like so:
+
+ @constants
+ {
+ name:value;
+ }
+
+And then used like a PHP variable:
+
+ #id
+ {
+ height:$name;
+ }
+
+Which will output
+
+ #id
+ {
+ height:value;
+ }
+
+You can define a path to an XML file to set constants automatically from there as well.
+
+## Flags and Time
+
+Using flags, we can display parts of our CSS only if certain conditions are met:
+
+ @flag(morning)
+ {
+ background:$light_blue;
+ }
+
+ @flag(night)
+ {
+ background:$dark_blue;
+ }
+
+To create flags, you need to create a module to set flags during the initialisation hook. This may be changed in a future release. You can create your own time-based flags inside the time config file located at scaffold/config/Time.php
+
+## Import
+
+Using import is easy.
+
+ @include 'myfile.css';
+
+It will use the path of the current CSS file as the base, but you can do absolute paths too:
+
+ @include '/stylesheets/components/myfile.css';
+
+## Iteration
+
+This lets you use PHP-style for loops
+
+ @for $n from 1 to 10
+ {
+ .columns-$n
+ {
+ width: calc($n + 100)px;
+ }
+ }
+
+## Layout
+
+The layout module creates CSS classes and Scaffold mixins to make creating layouts easy.
+
+ @grid
+ {
+ grid-width:940;
+ right-gutter-width:10;
+ left-gutter-width:10;
+ column-count:16;
+ baseline:18;
+ }
+
+Then we can do this:
+
+ #id
+ {
+ +columns(4);
+ }
+
+Which might output this:
+
+ #id
+ {
+ width:300px;
+ }
+
+*columns* is a mixin that the Layout module creates. To see the rest, take a look inside /scaffold/modules/Layout/templates/
+
+## Nested Selectors
+
+You can do simple nesting:
+
+ #id
+ {
+ a
+ {
+ color:blue;
+ }
+ }
+
+Or do more complex nesting
+
+ .tweet
+ {
+ +third-unit;
+
+ &:nth-child(odd)
+ {
+ top:-10px;
+ }
+
+ @for $i from 1 to 3
+ {
+ &:nth-child($i)
+ {
+ blockquote
+ {
+ -webkit-transform:rotate(rand(-3,3)deg) scale( calc( rand(1,20) * 0.01 + 1 ) );
+ }
+ }
+ }
+ }
+
+The & symbol represents the parent element of the current selector. This way you can keep all the selectors for single id or class in one group.
+
+## Creating custom functions
+
+To create a custom function, you need to place a PHP file with the name of your function inside /scaffold/extensions/functions/ inside one of the 3 phase folders.
+
+The phase folders allow you to determine the order the functions are parsed.
+
+Here's a simple example that creates the embed function
+
+ function Scaffold_embed($file)
+ {
+ $path = Scaffold::find_file( Scaffold_Utils::unquote($file) );
+
+ # Couldn't find it
+ if($path === false)
+ return false;
+
+ $data = 'data:image/'.pathinfo($path, PATHINFO_EXTENSION).';base64,'.base64_encode(file_get_contents($path));
+
+ return "url(" . $data . ")";
+ }
+
+You need to call the PHP function the same as the name of the file (which is the name of the CSS function) and prefix it with Scaffold_ to avoid conflicts.
+
+You return the string that will replace the function string. So in this case, url($data) will replace the embed() string.
+
+Above your functions, you can set a variable called $unique.
+
+ $unique = true;
+
+ function Scaffold_rand($from,$to)
+ {
+ return rand($from, $to);
+ }
+
+This means every found function will be parsed separately. By default, this is false, and functions that Scaffold finds that are exactly the same, will be combined and replaced at the same time.
+
+## Creating custom properties
+
+The properties work the same way as the functions. You place a file named whatever you want your property to be called, inside /scaffold/extensions/properties.
+
+ function Scaffold_image_replace($url)
+ {
+ $url = preg_replace('/\s+/','',$url);
+ $url = preg_replace('/url\\([\'\"]?|[\'\"]?\)$/', '', $url);
+
+ $path = Scaffold::find_file($url);
+
+ if($path === false)
+ return false;
+
+ // Get the size of the image file
+ $size = GetImageSize($path);
+ $width = $size[0];
+ $height = $size[1];
+
+ // Make sure theres a value so it doesn't break the css
+ if(!$width && !$height)
+ {
+ $width = $height = 0;
+ }
+
+ // Build the selector
+ $properties = "background:url(".Scaffold::url_path($path).") no-repeat 0 0;
+ height:{$height}px;
+ width:{$width}px;
+ display:block;
+ text-indent:-9999px;
+ overflow:hidden;";
+
+ return $properties;
+ }
+
+For properties, you want to return a string of properties that will replace this custom one.
+
+##Having trouble?
+
+Make sure you read the documentation. Twice. Then Google it. If you're still having trouble, feel free to contact me at csscaffold@me.com.
+
+If you find a bug, put it in the issues section on Github.
+
+##License
+
+Copyright (c) 2009, Anthony Short <csscaffold@me.com>
+http://github.com/anthonyshort/csscaffold
+All rights reserved.
+
+This software is released under the terms of the New BSD License.
+http://www.opensource.org/licenses/bsd-license.php

0 comments on commit 96be02c

Please sign in to comment.