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.

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:

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.

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:

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.