Blueprint’s compress.rb: A Walkthrough

Joshua Clayton

This is Not Just a Compression Script

One of the purposes of the revamping of the Blueprint scripts was to eliminate the need for a lot of the other websites out there that help you build custom grids, semantic namespaces, etc. Too many different versions of a very young CSS framework can wreak havoc on helping developers debug their code, especially since there’s no way to determine who’s running what version. These scripts will do darn near everything any of the websites out there do now. Point being, this is not just a compression script; it compresses the CSS, yes, but it also handles 95% of what the other websites out there provide in terms of flexibility.

What Can It Do?

Note that all these features are really only useful if you have one Blueprint folder on your computer and use it to export CSS to multiple projects. Everything listed below is project-specific as well, meaning that per project, you can define any (or all) of these settings explicitly.

Use a settings.yml file within the Blueprint folder to store project-specific CSS information for export
Export CSS files to remote locations (e.g. a user-defined path to a project)
Bundle user-written CSS with the Blueprint output CSS, compressing it at the same time (CSS specific, so Blueprint will bundle custom (print|screen|ie).css files as needed)
Define Blueprint-specific namespaces (all Blueprint classes would come prepended with a defined namespace)
Assemble sites with custom grid layouts, allowing users to have total control over the column count, column width, and gutter width, without having to use another website or application to change the grids
Simple user-defined semantic classes (setting #header and #footer to act as an element classed with “span-24 last”)
If you have ImageMagick and the RMagick gem installed, it will generate a custom grid.png file and export it to your output path

Purpose.

The purpose of re-factoring Blueprint’s compress.rb and other scripts was to make it much more extensible and useful for developers working on multiple projects. Developers using Blueprint on one or two single sites don’t care that the full Blueprint distribution is packaged with the site. However, developers working on multiple sites from a single computer are often left with the hassle of keeping all these copies up-to-date, with extra custom files floating around and very much a large mess.

The goal of rewriting the compression script was to allow for extreme customization of the output Blueprint CSS as well as ease of keeping projects up-to-date with the newest Blueprint source without much hassle.

Workflow.

The core idea is this:

Keep a core Blueprint folder checked out with Git on your computer
Create a settings.yml file within the Blueprint folder with all the specifics of each project using Blueprint
Use the command line to generate CSS for a project on command
- Incorporating any site-specific attributes
  - Namespace on all Blueprint classes
  - Custom grid template rather than the standard 24 columns / 30px column width / 10px gutter width
- Compressing any custom CSS and appending to the end of the Blueprint stylesheets
- Appending custom semantic selectors to the end of the Blueprint stylesheets

Usage.

There are two ways to use the compression script; either through the command line passing in any arguments, or using a settings.yml file to store all data and then passing one argument to the script. Command line arguments are covered under “Basic Usage”, while using a settings.yml will be covered under “Advanced Usage”.

Basic Usage.

Navigating to the blueprint/scripts folder and typing ruby compress.rb -h reveals the basics of using the command line to generate compressed Blueprint stylesheets.

ruby compress.rb -h

  
joshua-claytons-computer:scripts joshuaclayton$ ruby compress.rb -h
Usage: compress.rb [options]
Blueprint Compressor
options
  -o, --output_path=OUTPUT_PATH    Define a different path to output generated CSS files to.
  -n, --namespace=BP_NAMESPACE     Define a namespace prepended to all Blueprint classes (e.g. .your-ns-span-24)
  -p, --project=PROJECT_NAME       If using the settings.yml file, PROJECT_NAME is the project name you want to export
      --column_width=COLUMN_WIDTH  Set a new column width (in pixels) for the output grid
      --gutter_width=GUTTER_WIDTH  Set a new gutter width (in pixels) for the output grid
      --column_count=COLUMN_COUNT  Set a new column count for the output grid
  -h, --help                       Show this help message.

Arguments.

--output_path /path/to/target/locations/stylesheets
This will generate the Blueprint CSS files in a remote location instead of within the Blueprint distribution
--namespace your-namespace-
This will prepend a string to the default Blueprint classes. Selectors will change from .bp-class to .#{your-namespace-}bp-class
--project project_name
Passing in a project name will cause the compressor to look for a settings.yml file and attempt to load export settings from there
--column_width pixel_width
This sets the width of each column (in pixels) for a custom output grid
--gutter_width pixel_width
This sets the width (in pixels) between each column for a custom output grid
--column_count number_of_columns
This sets the number of columns created in the grid

Advanced Usage.

settings.yml

settings.yml is a YAML file that stores any custom settings when using the Blueprint directory as a core that generates CSS files for multiple projects.

settings.yml Sample Structure

  
project1:
  path: /path/to/my/project/stylesheets
  namespace: custom-namespace-1-
  custom_css:
    ie.css:
      - custom-ie.css
    print.css:
      - docs.css
      - my-print-styles.css
    screen.css:
      - subfolder-of-stylesheets/sub_css.css
  custom_layout:
    column_count: 12
    column_width: 70
    gutter_width: 10
  plugins:
    - fancy-type
    - buttons
project2:
  path: /path/to/different/stylesheets
  namespace: different-namespace-
  custom_css:
    screen.css:
      - custom_screen.css
  semantic_classes:
    "#footer, #header": ".span-24, div.span-24" 
    "#content": ".span-17, div.span-17, div.colborder"
    "#extra-content": ".span-6, div.span-6"
    "div#navigation": "div.span_24, .span-24"
    "div.section, div.entry, .feeds": ".span-6 div.span-6"
project3:
  path: /path/to/another/projects/styles

Structure Explanation.

If you don’t understand YAML, I suggest you go read the spec if you haven’t already. It’s very easy to understand and will take less than half an hour. If you’re a developer using Blueprint in multiple projects, believe me, it’s worth the time.

Root Nodes.

Root nodes are all project names (or whatever name you want to refer to a project as). When you pass the -p (--project) argument into the script, this is what you’re referencing. Using the example above to deploy to the project named project1:

ruby compress.rb -p project1

Children Nodes.

Under a project fall the handful of things you can set on a specific Blueprint “deployment”. They are:

path (default: BLUEPRINT_DIR/blueprint): This is the output path of the compressed Blueprint files. You do not have to use quotes if there are spaces within this string
namespace (default: none): This is a namespace that will be prepended to each Blueprint class, in order to remove any class conflicts with existing CSS. .clear would become #{.your-namespace-}clear
custom_css (default: my-ie|screen|print.css): This needs to be set if you want Blueprint to compress and append any of your CSS files to the end of its files. They are media-specific, so no screen styles will be appended to print styles unless you want them to
- ie.css (default: my-ie.css)
  - filename.css
  - filename2.css
- screen.css (default: my-screen.css)
  - filename-screen.css
  - filename-screen2.css
- print.css (default: my-print.css)
  - filename-print.css
  - filename-print2.css
custom_layout (default: none): This is to define a custom grid layout. If you don’t define this, the compressor defaults to the standard Blueprint structure
- column_count (default: 24): This is the number of columns to be generated
- column_width (default: 30): This is the width (in pixels) of each column
- gutter_width (default: 10): This is the width (in pixels) of each gutter (or margin) between columns
semantic_classes (default: N/A): This contains a list of custom selectors set to Blueprint classes to inherit from
- “#string #of, #selectors, .classes, .and .ids”: space or comma-separated list of Blueprint classes to draw styles from
plugins (default: none): This allows you to append plugin stylesheets to the output Blueprint CSS
- plugin_name: This appends BLUEPRINT_DIR/blueprint/plugins/{plugin_name}/(screen|print|ie).css to the specific Blueprint style. If none of those files exist, it looks for BLUEPRINT_DIR/blueprint/plugins/{plugin_name}/{plugin_name}.css and appends it to each generated Blueprint stylesheet
  - plugin_name_2
  - plugin_name_3

Overview.

Blueprint CSS provides a good foundation of styles as well as a standard grid. For a developer working on a single site, it is ideal to just include the entire Blueprint directory within the project. However, if you’re going to be bundling Blueprint with multiple projects, and especially if you’re doing any custom CSS or grid manipulation, it is ideal to use the settings.yml file to store site-specific data and output from that directory. An example file has been bundled within Blueprint (BLUEPRINT_DIR/lib/settings.example.yml) to act as a reference.