Wordpress Sandbox and Blueprint

The files included at the bottom of this post are those that were used to implement the methods described in this article. They are not a wordpress theme and will not work if installed as such. If you are looking for a theme built using this method, see the page WSB Theme Download.

I have been very excited by the seamless integration of three of my favorite development tools: WordPress, Sandbox and Blueprint CSS. I know there’s a lot of interest these days in WordPress “frameworks” for child theme development and projects like Thematic and others are certainly exciting. For me though there is a definite cool factor in a rapid development and deployment stack like WSB.

Blueprint is the piece of this puzzle that is newest to me but that I’m almost most excited about. I have been using Sandbox and WordPress for theme development for a few years and have run up against all the common issues: lack of rapid complex layouts, lack of baseline typography, lack of baseline forms styling, and of course IE compatibility. What Blueprint provides is a baseline, common hooks, class generating plugins, and browser compatibility hacks to give you a consistent starting point for your design project. Getting it to integrate with WordPress and Sandbox is a must.

What we’ll set up here is a solid baseline for theme design: a complete, non-invasive integration of all three projects. Once set up, redeploying this stack for other projects and development environments on your server is very quick and easy. Blueprint provides nice tools for customizing your different installations from an organized central management script.

The Summary Workflow:

Install WordPress and Sandbox
Create a Sandbox Child Theme
Install Blueprint centrally and use compress.rb to generate stylesheets for the child theme
Import Blueprint screen.css into child theme style.css
Use functions.php to inject Blueprint stylesheet declarations into the header
Work with settings.yml to generate a layout and plugins for Blueprint stylesheets

The Detailed Workflow:

Either create a new domain or subdomain on your server or decide which wordpress installation you want to use for this project.
Install WordPress if it isn’t already, and make sure the Sandbox theme is installed as well. For this example, I’ll use
```
/var/www/wordpress/
```
Next we’ll create a new theme called WSB in
```
/var/www/wordpress/wp-content/themes/WSB
```
. Create the WSB folder and upload a style.css file with a header similar to the following:
```
/*
THEME NAME: WSB
THEME URI: http://domain.com
DESCRIPTION: Theme using WSB stack
VERSION: 0.0.1
AUTHOR: <a href="http://nedsferatu.com/">Nedsferatu</a>
AUTHOR URI:
TAGS: sandbox, blueprint
TEMPLATE: sandbox
*/
```
The important line here is TEMPLATE:sandbox. This basically makes your new theme a child theme of sandbox. What this means is wordpress will use the style and function files in our WSB theme first but will go to the sandbox theme for the template files. Be sure the check out the documentation for more info. This basically keeps the sandbox theme untouched and easily upgradable while we make all our customizations in this child theme.
In the Appearance menu, select our new WSB theme as your default theme. Your site shouldn’t look like much yet so keep going with the steps!
At this point we have have our wordpress and sandbox integration with our new child theme so let’s add blueprint into the mix. The best way to use blueprint for developing is to have a central installation of it that feeds style files to your projects. Upload the blueprint files to another directory on your server such as
```
/var/www/usr/blueprint-css
```
or
```
~/blueprint-css
```
. We will want to make a folder in our new theme to accept the files we generate:
```
/var/www/wordpress/wp-content/themes/WSB/bp
```
Let’s generate some basic Blueprint stylesheets for our new theme. In the shell, create a settings file for Blueprint:
```
/blueprint-css/lib/settings.yml
```
that contains the following:
```
WSB:
path: /var/www/wordpress/wp-content/themes/WSB/bp
semantic_classes:
"body": "container"
```
The key thing to know about this file is that indentation is meaningful. Be sure to only use a single space to differentiate sections of this settings.yml file. Be sure to read this guide for more, especially the Advanced Usage section. Also the comments in the blueprint files and the readme files throughout blueprint are a very good source of information about usage.
After you save the settings file, use the compress.rb script to generate the stylesheets and save them to our theme folder:
```
ruby compress.rb -p WSB
```
using the -h option will give you a help file on compress.rb usage.
Now if you look at your /WSB/bp directory you’ll see blueprint generate stylesheets. To make changes to these we will be updating our settings.yml file and rerunning the compress.rb script. (Incidentally to have blueprint generate stylesheets for another project, just add a new project name and path below the existing one in your settings.yml file. Hopefully you’ll begin to see the advantages of this approach although the real power comes with additional information we can put in the settings.yml file.)
Let’s integrate Blueprint into our new theme to run with sandbox and wordpress. First import the blueprint screen.css file into our new style.css:
```
/*
THEME NAME: WSB
THEME URI: http://domain.com
DESCRIPTION: Theme using WSB stack
VERSION: 0.0.1
AUTHOR: <a href="http://nedsferatu.com/">Nedsferatu</a>
AUTHOR URI:
TAGS: sandbox, blueprint
TEMPLATE: sandbox
*/
@import url('bp/screen.css');
```
At this point you could also import the default styles from sandbox but I prefer to keep the style separated to Blueprint and my own customizations.
Now we need to add Blueprint’s print.css and ie.css to the header of our template. To do this without touching the sandbox header.php file we will write a functions.php file in our theme directory:
```
/wp-content/themes/WSB/bp/print.css" type="text/css" media="print" /&gt;


<div id="designer-link"><span class="meta-sep">|</span>
<span id="designer-link"><a title="&lt;?php _e( 'Nedsferatu.com', 'sandbox' ) ?&gt;" rel="designer" href="http://nedsferatu.com/"></a></span></div>
add_action('wp_head', 'header_ie8');
add_action('wp_head', wp_enqueue_script('jquery')); // ADDS JQUERY TO THE HEADER
add_action('wp_head', 'header_blueprint');
add_action('wp_footer', 'footer_webmaster');
```
OK this script does a lot so let’s take a look at it. There are three functions: header_blueprint, header_ie8, and footer_webmaster. Header_blueprint takes the two stylesheet declarations and puts them into the header of all our pages using the add_action at the bottom. Header_ie8 calls the very helpful ie8.js (ie7.js) file that will help us maintain browser independent pages. Read more about it on their google code page. The last function can help you insert your own links or copyright information into the footer of the page. There is a fourth add_action at the bottom that adds the jquery call to your pages so that you can use jquery in your theme. Functions.php is a very powerful tool for child themes.
So now we have sandbox and blueprint integrated into our child theme so let’s go ahead and apply some basic layouts for the site using the settings.yml file. At this point I would recommend a few additions to the settings.yml file:
```
WSB:
path: /var/www/wordpress/wp-content/themes/WSB/bp
namespace: wsb-
semantic_classes:
"body": "container"
"div#wrapper": "column clearfix prepend-top append-bottom"
"div#header": "span-24 column clearfix"
"h1#blog-title": "span-18 column"
"div#blog-description": "span-6 prepend-top column last"
"div#access": "span-24 clear"
"div#container": "clearfix div.border column"
"div#content": "span-18"
"div#primary": "span-6 prepend-top column last"
"div#secondary": "span-6 column last"
"div#footer": "span-24 column"
```
The namespace will put a wsb- in front of all classes that blueprint generates. This will help alleviate any clashes with already existing classes in sandbox. Semantic classes basically take an existing class or id in your theme (#header for example) and assigns blueprint classes to it in the css (such as span-24 column and clearfix). This means that you can get the benefit of all the blueprint classes for layouts or other actions but you still only see your semantic classes in your markup provided by sandbox. Also, you can take advantage of the grid background to check your themes alignment at anytime by adding the showgrid class to div#wrapper. As always, whenever you make changes to settings.yml don’t forget to run:
```
ruby compress.rb -p WSB
```

Using the menu from sandbox and a couple other css tweaks at this point should leave us with a very respectable looking site:

/*
THEME NAME: WSB
THEME URI: http://domain.com
DESCRIPTION: Theme using WSB stack
VERSION: 0.0.1
AUTHOR: <a href="http://nedsferatu.com/">Nedsferatu</a>
AUTHOR URI:
TAGS: sandbox, blueprint
TEMPLATE: sandbox
*/
@import url('blueprint/screen.css');
div#wrapper {text-align:left;}
div.skip-link {display:none;}
div#secondary {float:right;}
/* Navigation (from Sandbox) */
div#menu {background:#EEE;height:1.5em;margin:1.5em 0;width:100%;}
div#menu ul,div#menu ul ul {line-height:1em;list-style:none;margin:0;padding:0;}
div#menu ul a {display:block;margin-right:1em;padding:0.2em 0.5em !important;text-decoration:none;}
div#menu ul ul ul a {font-style:italic;}
div#menu ul li ul {left:-999em;position:absolute;}
div#menu ul li:hover ul {left:auto;}
div#menu ul li,div.gallery dl,div.navigation div.nav-previous {float:left;}
form#searchform input.text {width:120px;} /*overrides blueprint's large input for sidebar*/
div#comments {clear: both;}

Adding custom css files to your blueprint generate stylesheets is an easy way to make changes to blueprint that you don’t want to make in your style.css file. All you have to do is save your custom css files in a folder such as:
```
/wp-content/themes/WSB/bp/custom
```
and then add them into your settings.yml file like so:
```
WSB:
path: /var/www/wordpress/wp-content/themes/WSB/bp
namespace: wsb-
custom_css:
screen.css:
- custom/custom-css-file.css
semantic_classes:
"body": "container"
"div#wrapper": "column clearfix prepend-top append-bottom"
"div#header": "span-24 column clearfix"
"h1#blog-title": "span-18 column"
"div#blog-description": "span-6 prepend-top column last"
"div#access": "span-24 clear"
"div#container": "clearfix div.border column"
"div#content": "span-18"
"div#primary": "span-6 prepend-top column last"
"div#secondary": "span-6 column last"
"div#footer": "span-24 column"
```
As you can see, you can save all of your customized css files with your project and manage them from your central settings.yml file for added convenience and organization. Specifying screen.css simply lets compress.rb know which blueprint css file to include the custom style in. You could also use print.css, etc. This will all come in handy below when working with plugins. As always, whenever you make changes to settings.yml don’t forget to run:
```
ruby compress.rb -p WSB
```

Here’s a quick screenshot example of what can be done using almost exactly this method without any additional styling:

I think this is quite nice and usable without any really design work yet.

Other Tips:

Plugins:

If you want to use the Fancy Type Plugin with Blueprint and Sandbox, you will have to write a custom css file and include it in your settings.yml file. This is because both Blueprint Fancy Type and Sandbox use the .alt class for different things and as of this writing the namespace is applied to classes generated before plugins are included by the compress.rb script. A solution to this is including a custom css file when you call the plugin. The css file:

/wp-content/themes/WSB/bp/custom/fancy-cust.css

would look like this

/* --------------------------------------------------------------
fancy-cust.css
* resets .alt generated by fancy-type and sets a class with a non
clashing name.
-------------------------------------------------------------- */
.alt {
font-style: inherit !important;
font-weight: normal;
color:#222 !important;
font-family:"Helvetica Neue", Arial, Helvetica, sans-serif !important;
}
.wsb-alt {
color: #666;
font-family: "Warnock Pro", "Goudy Old Style","Palatino","Book Antiqua", Georgia, serif;
font-style: italic;
font-weight: normal;
}

This will reset the offending class and set a new class with a non-clashing name. To add this to your settings.yml file:

WSB:
path: /var/www/wordpress/wp-content/themes/WSB/bp
namespace: wsb-
custom_css:
screen.css:
- custom/fancy-cust.css
semantic_classes:
"body": "container"
"div#wrapper": "column clearfix prepend-top append-bottom"
"div#header": "span-24 column clearfix"
"h1#blog-title": "span-18 column"
"div#blog-description": "span-6 prepend-top column last"
"div#access": "span-24 clear"
"div#container": "clearfix div.border column"
"div#content": "span-18"
"div#primary": "span-6 prepend-top column last"
"div#secondary": "span-6 column last"
"div#footer": "span-24 column"
plugins:
- fancy-type

This change calls the custom css file, adds it to the screen.css file and calls the fancy-type plugin. As always, whenever you make changes to settings.yml don’t forget to run:

ruby compress.rb -p WSB

If you want to use the Link Icon Plugin with Sandbox you’ll have to make a few modifications in a custom plugin file and include it in your settings.yml file. This is because the links plugin will be expecting relative links for internal links and Sandbox provides absolute links for all internal links. If you don’t modify it, you’ll see the external link image next to every link on the page. We take a similar approach to fixing this plugin to work with sandbox. The css file:

/wp-content/themes/WSB/bp/custom/links-cust.css

would look like this

/* --------------------------------------------------------------
links-cust.css
* Icons for links based on protocol or file type fixed for sandbox.
-------------------------------------------------------------- */
/* Uses this class if a link is internal */
body a[href^="http://sub.domain.com"] {
background:transparent none !important;
padding:0 !important;
margin:0 !important; }

This will apply no image to links that begin with http://sub.domain.com so you’ll want to change that to your domain. To add this to your settings.yml file:

WSB:
path: /var/www/wordpress/wp-content/themes/WSB/bp
namespace: wsb-
custom_css:
screen.css:
- custom/fancy-cust.css
- custom/links-cust.css
semantic_classes:
"body": "container"
"div#wrapper": "column clearfix prepend-top append-bottom"
"div#header": "span-24 column clearfix"
"h1#blog-title": "span-18 column"
"div#blog-description": "span-6 prepend-top column last"
"div#access": "span-24 clear"
"div#container": "clearfix div.border column"
"div#content": "span-18"
"div#primary": "span-6 prepend-top column last"
"div#secondary": "span-6 column last"
"div#footer": "span-24 column"
plugins:
- fancy-type
- link-icons

As always, whenever you make changes to settings.yml don’t forget to run:

ruby compress.rb -p WSB

Printing:

I would recommend a custom css file for printing as well with the following changes…the css file:

/wp-content/themes/WSB/bp/custom/print-cust.css

would look like this

/* --------------------------------------------------------------
print-cust.css
* Gives you some custom sensible styles for printing pages.
-------------------------------------------------------------- */
#header, #footer, #access, .navigation { display:none; }
/* If you're having trouble printing relative links, uncomment and customize this:
(note: This is valid CSS3, but it still won't go through the W3C CSS Validator) */
a[href^="/"]:after {
content: " (http://sub.domain.com" attr(href) ") ";
}

This hide some page element when printing a post or page from your blog. It also adds http://sub.domain.com to help when resolving internal links during printing. Be sure to test your printing styles by using the print preview function in your browser. To add this to your settings.yml file:

WSB:
path: /var/www/wordpress/wp-content/themes/WSB/bp
namespace: wsb-
custom_css:
screen.css:
- custom/fancy-cust.css
- custom/links-cust.css
print.css
- custom/print-cust.css
semantic_classes:
"body": "container"
"div#wrapper": "column clearfix prepend-top append-bottom"
"div#header": "span-24 column clearfix"
"h1#blog-title": "span-18 column"
"div#blog-description": "span-6 prepend-top column last"
"div#access": "span-24 clear"
"div#container": "clearfix div.border column"
"div#content": "span-18"
"div#primary": "span-6 prepend-top column last"
"div#secondary": "span-6 column last"
"div#footer": "span-24 column"
plugins:
- fancy-type
- link-icons

As always, whenever you make changes to settings.yml don’t forget to run:

ruby compress.rb -p WSB

Conclusions

This should give you a really solid start in developing and designing themes using WordPress, Sandbox, and Blueprint CSS. I feel there are many more areas for tight integration among the programs so maybe there will be followup articles as well. I will be looking into integrating visual elements like typography, and using Sandbox’ available filters for added flexibility. I would love to hear from others who are working on this and similar projects.

What most excites me about this set up as it stands here is how portable it is. This can be replicated in minutes allowing a designer to get into customizing faster with a more solid and proven foundation. Also, all of the customizations and tweaks we’ve made so far are completely non-invasive; this means that when WordPress, Sandbox, or Blueprint publish an update, we can upgrade quickly without anything breaking.

Download all the files mentioned in this article: WSB-stack-demo.zip
Please see the individual project sites to download the installation files and for more information: WordPress, Sandbox and Blueprint CSS