From 99e6d068ed879efac475ed814d206721c5634ff1 Mon Sep 17 00:00:00 2001 From: Olav Bjorkoy Date: Tue, 18 Mar 2008 16:20:31 +0000 Subject: [PATCH] First draft of bundled tutorial on BP. --- CHANGELOG | 8 +- TUTORIAL | 350 +++++++++++++++++++++++++++++++++++++++++ blueprint/src/grid.css | 8 +- 3 files changed, 358 insertions(+), 8 deletions(-) create mode 100644 TUTORIAL diff --git a/CHANGELOG b/CHANGELOG index 478dde08..1dcf5e0f 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,14 +1,18 @@ Blueprint CSS Framework Change Log ---------------------------------------------------------------- -Version 0.7.1 - Date 21/02/2007 +Version 0.7.1 - Date 21/02/2008 -- + New features: + * Rubydoc for compressor [JC] + * + Bug fixes: * Fixed bug in the compressor related to Rubygems. [JC] * should be inline, not block. [OFB] -Version 0.7 - Date 19/02/2007 +Version 0.7 - Date 19/02/2008 -- New features: * New directory structure. [OFB] diff --git a/TUTORIAL b/TUTORIAL new file mode 100644 index 00000000..a6571b50 --- /dev/null +++ b/TUTORIAL @@ -0,0 +1,350 @@ +Blueprint CSS Framework Tutorial +------------------------------------------------------------------------------------------- + +Welcome to this tutorial on Blueprint. It will give you a thorough intro to what you can +do with the framework, and a few notes on what you shouldn't do with it. Let's get started. + + +About Blueprint: + + Blueprint is a CSS framework, designed to cut down on your development time. It gives + you a solid foundation to build your CSS on top of, including some sensible default + typography, a customizable grid, a print stylesheet and much more. + + However, BP is not a silver bullet, and it's best suited for websites where each page + may require it's own design. Take a look at existing BP pages before deciding if the + framework is right for you. You may also check out the test files in the "tests" + directory, which demonstrates most of the features in Blueprint. + + The word "framework" may be a bit misleading in this context, since BP does not make + suggestions on how you should organize or write your CSS. It's more like a + "css toolbox" with helpful bits and pieces, from which you may pick and choose based + on your needs. + + +Structural overview: + + From the bottom up, here are the CSS layers in Blueprint: + + CSS reset: Removes any default CSS rules set by each browser. + Typography: Gives you some nice default typography and colors. + Grid: Provides a set of CSS classes for making grid layouts. + + The second part of Blueprint are the scripts, which lets you customize most + aspects of the framework, from column count and widths, to output paths and + CSS class namespaces. We have two scripts: + + Compressor: For compressing and customizing the source files. + Validator: For validating the Blueprint core files. + + That's the quick overview, so now we can finally get into the details. First, we'll take + a look at the CSS in Blueprint. We'll then move on to the scripts, where I'll show you + how to customize the framework. + + +Setting up Blueprint: + + To use Blueprint, you must include three files in your HTML: + + blueprint/screen.css: All CSS for screen, projection viewing. + blueprint/print.css: A basic stylesheet for printing. + blueprint/ie.css: A few needed corrections for Internet Explorer + + To include them, use the following HTML (make sure the href paths are correct): + + + + + + Remember to add trailing slashes if you're using XHTML (" />"). + + +Using the CSS in Blueprint: + + As mentioned before, there's basically three layers of CSS in Blueprint. The first + two layers, the browser CSS reset and the default typography, apply themselves by + changing CSS of standard HTML elements. In other words, you don't need to change anything + in these files. If you for instance want to change the font size, do this in your own + stylesheet, so that it's easy to upgrade Blueprint when new versions arrive. + + Classes for typography: + + While the typography of Blueprint mainly applies itself, there's a few classes + provided. Here's a list of their names and what they do: + + .small: Makes the text of this element smaller. + .large: Makes the text of this element larger. + .hide: Hides an element. + .quiet: Tones down the font color for this element. + .loud: Makes this elements text black. + + .highlight: Adds a yellow background to the text. + .added: Adds green background to the text. + .removed: Adds red background to the text. + + .first: Removes any left sided margin/padding from the element. + .last: Removes any right sided margin/padding from the element. + .top: Removes any top margin/padding from the element. + .bottom: Removes any bottom margin/padding from the element. + + Styling forms: + + To make Blueprint style your input elements, each text input element should + have the class ".text", or ".title", where ".text" is the normal size, + and ".title" gives you an input field with larger text. + + There's also a few classes you may use for success and error messages: + + div.error: Creates an error box (red). + div.notice: Creates a box for notices (yellow). + div.success: Creates a box for success messages (green). + + Creating a grid: + + The third layer is the grid CSS classes, which is the tool Blueprint gives you to + create almost any kind of grid layout for your site. Keep in mind that most of the CSS + behind the grid can be customized (explained below). In this section however, I'm using + the default settings. + + The default grid is made up of 24 columns, each spanning 30px, with a 10px margin between + each column. The total width comes to 950px, which is a good width for 1024x768 + resolution displays. If you're interested in a narrower design, see the section on + customizing the grid, below. + + So how do you set up a grid? By using classes provided by Blueprint. To create a column, + make a new
, and apply one of the .span-x classes to it. For instance, if you want + a 3-column setup, with two narrow and one wide column, a header and a footer here's how + you do it: + +
+
+ The header +
+ +
+ The first column +
+
+ The center column +
+
+ The last column +
+ +
+ The footer +
+ + In addition to the spans, there are two important classes you need to know about. First + of all, every Blueprint site needs to be wrapped in a div with the class "container", + which is usually placed right after the body tag. + + Second, the last column in a row (which by default has 24 columns), needs the class + "last" to remove its left hand margin. Note however that each span-24 don't need the + "last" class, since these always span the entire width of the page. + + To create basic grids, this is all you need to know. The grid CSS however, provides + many more classes for more intricate designs. To see some of them in action, check out + the files in /tests/parts/. These files demonstrate what's possible with the grid + in Blueprint. + + Here's a quick overview of the other classes you can use in to make your grid: + + .append-x: Appends x number of empty columns after a column. + .prepend-x: Preppends x number of empty columns before a column. + .push-x: Pushes a column x columns to the left. Can be used to swap columns. + .pull-x: Pulls a column x columns to the right. Can be used to swap columns. + + .border: Applies a border to the right side of the column. + .colborder: Appends one empty column, with a border down the middle. + .clear: Makes a column drop below a row, regardless of space. + .showgrid: Add to container or column to see the grid and baseline. + + In this list, "x" is a number from 1 through 23 for append/prepend and 1 through 24 + for push/pull. These numbers will of course change if you set a new number of + columns in the settings file. + + Here's another example where we have four columns of equal width, with a border + between the two first and the two last columns, as well as a four column gap in + the middle: + +
+
+ The first column +
+
+ The second column +
+
+ The third column +
+
+ The fourth (last) column +
+
+ + You may also nest columns to achieve the desired layout. Here's a setup where we + want four rectangles with two on top and two below on the first half of the page, + and one single column spanning the second half of the page: + +
+
+
+ Top left +
+
+ Top right +
+
+ Bottom left +
+
+ Bottom right +
+
+
+ Second half of page +
+
+ + Try this code in your browser it it's difficult to understand what it would + look like. To see more examples on how to use these classes, check out + /tests/parts/grid.html. + + +The scripts: + + Blueprint comes with two scripts: one for compressing and customizing the CSS, + and one for validating the core CSS files, which is handy if you're making + changes to these files. + + The validator: + + The validator has a fairly simple job - validate the CSS in the core BP files. + The script uses a bundled version of the W3C CSS validator to accomplish this. + To run it, you'll need to have Ruby installed on your mashine. You can then + run the script like so: $ruby validate.rb + + Note that there are a few validation errors shipping with Blueprint. These + are known, and comes from a few CSS hacks needed to ensure consistent rendering + across the vast browser field. + + The compressor: + + As the files you'll include in your HTML are the compressed versions of the + core CSS files, you'll have to recompress the core if you've made any changes. + This is what the compressor script is for. + + In addition this is where you customize the grid. To customize the grid, a + special settings file is used, and the new CSS is generated once you run the + compressor. The new compressed files will then reflect your settings file. + + To recompress, you just have to run the script. This will parse the core CSS + files and output new compressed files in the blueprint folder. As with the + validator, Ruby has to be installed to use this script. In the "lib" directory, + run: $ruby compress.rb + + Calling this file by itself will pull files from blueprint/src and concatenate + them into three files; ie.css, print.css, and screen.css. However, argument + variables can be set to change how this works. Calling $ruby compress.rb -h + will reveal basic arguments you can pass to the script. + + Custom Settings: + + To use custom settings, the file need to be stored in settings.yml within the "lib" + directory. An example YAML file has been included. + + Another ability is to use YAML for project settings in a predefined structure and + store all pertinent information there. The YAML file has multiple keys (usually + a named project) with a set of data that defines that project. A sample structure + can be found in settings.example.yml. The basic structure is given below. + + Root nodes are project names. You use these when calling compress.rb as such: + ruby compress.rb -p PROJECTNAME + + A sample YAML with only roots and output paths would look like this: + + project1: + path: /path/to/my/project/stylesheets + project2: + path: /path/to/different/stylesheets + project3: + path: /path/to/another/projects/styles + + You can then call "$ruby compress.rb -p project1" or "$ruby compress.rb -p project3". + This would compress and export Blueprints CSS to the respective directory, checking + for my-(ie|print|screen).css and appending it if present. A more advanced structure + would look like this: + + 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 + + project2: + path: /path/to/different/stylesheets + namespace: different-namespace- + custom_css: + screen.css: + - custom_screen.css + semantic_classes: + "#footer, #header": column span-24 last + "#content": column span-18 border + "#extra-content": last span-6 column + "div#navigation": last span-24 column + "div.section, div.entry, .feeds": span-6 column + plugins: + - fancy-type + - buttons + - validations + project3: + path: /path/to/another/projects/styles + + In a structure like this, a lot more assignment is occurring. Custom namespaces are + being set for two projects, while the third (project3) is just a simple path setting. + + Also, custom CSS is being used that is appended at the end of its respective file. + So, in project1, print.css will have docs.css and my-print-styles.css instead of the + default my-print.css. Note that these files are relative to the path that you defined + above; you can use subdirectories from the default path if you would like. + + Another thing to note here is the custom_layout; if not defined, your generated CSS + will default to the 24 column, 950px wide grid that has been standard with Blueprint + for quite some time. However, you can specify a custom grid setup if you would like. + The three options are column_count (the number of columns you want your grid to have), + column width (the width in pixels that you want your columns to be), and gutter_width + (the width in pixels you want your gutters - space between columns - to be). + + To use the Blueprint default, do not define this in your settings file. + + Defining semantic_classes, with nodes underneath, will generate a class for each node + which has rules of each class assigned to it. For example, in project2 above, for + '#footer, #header', elements with id's of footer and header will be assigned all the + rules from the classes 'span-24, column, and last', while divs with classes either + entry or section, as well as any element with class of feed, is assigned all the rules + from 'span-6 and column'. Although it is a crude way do accomplish this, it keeps the + generated CSS separate from the core BP CSS. + + Also supported is plugins. The compressor looks within BLUEPRINT_DIR/blueprint/plugins + to match against what's passed. If the plugin name matches, it will append + PLUGIN/(screen|print|ie).css to the corresponding CSS file. It will append the plugin + CSS to all three CSS files if there is a CSS file present named as the plugin (e.g. the + fancy-type plugin with a fancy-type.css file found within the plugin directory). + + +Blueprint resources + +# TODO: Add resources + diff --git a/blueprint/src/grid.css b/blueprint/src/grid.css index 301f7169..f9c00dce 100755 --- a/blueprint/src/grid.css +++ b/blueprint/src/grid.css @@ -21,14 +21,10 @@ } /* Use this class on any div.span / container to see the grid. */ -.showgrid { - background: url(src/grid.png); -} +.showgrid { background: url(src/grid.png); } /* Body margin for a sensile default look. */ -body { - margin:1.5em 0; -} +body { margin:1.5em 0; } /* Columns