Creating Extensions

Extensions are simple classes which hook into different parts of the system. They’re located in /scaffold/extensions/. If an extension was called ‘MyExtension’, it would look like this:

extensions/
   MyExtension/
      MyExtension.php

Scaffold Hooks

Hooks are functions In extensions that are called during a certain point in the processing of the CSS string. There are 2 types of hooks: system hooks and custom hooks. 

The system hooks available allow a certain amount of knowledge about the present state of the CSS string. 

initialize(Scaffold_Source $source, Scaffold $scaffold)

This is fired off right at the start, before any processing has occurred. It’s used for loading in extra libraries, manipulating settings etc. 

pre_format(Scaffold_Source $source, Scaffold $scaffold)

This hook is for formatting the CSS before any processing has occurred. It might include removing of whitespace to improve performance, or un-nesting selectors. 

pre_process(Scaffold_Source $source, Scaffold $scaffold)

Used for importing files and generally getting the CSS ready for processing. 

process(Scaffold_Source $source, Scaffold $scaffold)

The main work-horse. This is where most of the extensions will take place. It could include replacing selectors, replacing custom properties etc. 

post_process(Scaffold_Source $source, Scaffold $scaffold)

Cleaning up anything that wouldn’t be considered valid CSS. 

post_format(Scaffold_Source $source, Scaffold $scaffold)

Formatting the string before it’s returned.

The Scaffold hook methods all give a $source object and a $scaffold object.

Working with the $scaffold object

From here you have access to Scaffolds public methods, such as notify for creating custom hooks, and the cache, loader and response objects which are stored as variables. With access to the Scaffold object, you can access just about any part of the system and it’s objects. You could:

• create your own cache files (along with expiration and time checking)
• load in files from the filesystem
• create your own hooks
• parse chunks of CSS through the parser itself in a loop
• change the output of scaffold
• change the way the original file is stored

It’s really limitless what you could do with it. 

Working with the $source object

$source is an instance of Scaffold_Source that is passed through to the hooks from the main system. A source can be a file, a string, a URL etc. It contains the contents of the CSS string currently being parsed, as well as information about the original file, such as when it was last modified.

No matter which type of source it is, it will always be an extension of Scaffold_Source and contain the following methods and class variables for working with the contents:

• $contents – Returns the CSS string (the contents of the source)
• $id – A unique identifier for this source. ie. It’s used by the cache to create cache files.
• $last_modified – Returns when the source was last modified. In the case of a string, the modified time will be when the source object was created
• find() – Finds files relative to the source. This is useful when trying to resolve paths within url() or @imports. 

Refer to the class, located in lib/Scaffold/Source.php for more things you can do with this object.

Helper classes

There are two classes that make working with CSS string and files much easier. They are the Scaffold_Helper_CSS class and the Scaffold_Helper_String class. They are essentially classes full of helper functions. They include:

• finding properties and values within the CSS
• locating and replacing at-rules
• finding CSS style functions

This can be accessed from any extension via $this->helper['helper_name']. The three helpers available are:

• css – Scaffold_Helper_CSS
• string – Scaffold_Helper_String
• load – Scaffold_Helper_Loader

See the classes in lib/Scaffold/Helper for more detailed documentation. 

Creating configuration options

Extensions can have their own options which are set in the config with the rest of Scaffold’s options:

$config['AbsoluteUrls']['require_files'] = false;

To access these within the extension:

$this->config['require_files']

Every extension inherits the $_defaults variable. This is where you need to set the default settings for your extension if no settings given:

public $_defaults = array(
	'require_files' => false
);

Extensions should be able to function without any user configuration. If the require configuration, the extensions shouldn’t throw any errors or warnings and just let Scaffold continue on as normal. 

How to use the hooks

Hooks are called by simply having the correctly named method in your class. Every system hook has a single parameter $source which is the CSS object being parsed.  

public function process($source,$scaffold) {} 

Custom Hooks

Extensions can create their own hooks as well. For instance, the Constant extension has hooks for before and after the constant replacement. Hooks are created via the $scaffold object:

$this->scaffold->notify('hook name', array(parameters))

Now other extensions can hook into our extension. You can start to see how powerful extensions can become when they can use each other, but in a decoupled way.