mirisuzanne/tutorial.mkdn

## tutorial.mkdn

      
    Raw
  

              tutorial.mkdn
            
          
    Susy 0.9 Tutorial

See the official Susy site for 1.0 documentation.
For this tutorial I'm assuming you are already comfortable with CSS, Sass (I'll use the SCSS syntax) and Compass. Please get set up with each one of those before attempting to use Susy. Sass and Compass both have their own setup instructions and tutorials that you can use.
There is also reference documentation in the works.
Building a Susy Grid

Step 1: Declare Your Grid

In the provided '_base' sass partial you have this:
$total-cols             : 12;  
$col-width              : 4em;  
$gutter-width           : 1em;  
$side-gutter-width      : $gutter-width;  

$total-cols is the number of columns in your grid, $col-width is the width of any one column, $gutter-width is the space between columns, and $side-gutter-width is the space between your outer columns and the edge of the container. Set each one to match your desired grid. The default above is elastic, but what if we want something else?
// Fixed Grid

$total-cols             : 6;  
$col-width              : 150px;  
$gutter-width           : 20px;  
$side-gutter-width      : 5px;

// Fluid Grid

$total-cols             : 24;  
$col-width              : 3%;  
$gutter-width           : 1%;  
$side-gutter-width      : 0%;

Step 2: Apply Your Grid

There are four main mixins required in the use of Susy: 'container', 'columns', 'alpha' and 'omega'. I'm only using non-semantic markup in these examples so that you can see what I am doing. Use the markup that you like. I'm also assuming the default elastic 12-column grid.
// Two-Sidebar Example SCSS

#container {  
  @include container;  
}

.left-sidebar {  
  @include columns(3);  
  @include alpha;  
}

.main-content {  
  @include columns(6);  
}

.right-sidebar {  
  @include columns(3);  
  @include omega;  
}

Compiled into CSS, we get the following (along with some clearfix and IE hasLayout help):
#container {  
  margin: auto;               /* centering */  
  width: 61em;                /* grid container size */  
  max-width: 100%;            /* responsive layout */  
}

.left-sidebar {  
  float: left;                /* float left */  
  width: 22.951%;             /* span 3 columns */  
  margin-right: 1.639%;       /* right gutter */  
  margin-left: 1.639%;        /* left side gutter */  
}

.main-content {  
  float: left;                  
  width: 47.541%;             /* span 6 columns */  
  margin-right: 1.639%;       
}

.right-sidebar {  
  float: right;               /* float right */  
  width: 22.951%;             /* span 3 columns */  
  margin-right: 1.639%;       /* right side gutter */  
}

Making Complex Grids

Nesting Columns

There are many ways to get more complex with Susy, but nesting columns inside other columns is probably the most common. And it's easy if you understand how Susy handles context. Once you start nesting columns, you need to know the width of the parent column in order to determine the relative width of the child. I've written a more detailed context demo that I recommend. This can be the trickiest part to understand. But here's how we might use it:
.main-content {  
  @include columns(6);      /* this will be our context for items nested inside it */
  
  .main-left-half {  
    @include columns(3,6);    /* 3 columns out of 6 */  
                              /* we don't need alpha when we are nested */  
  }
  
  .main-right-half {  
    @include columns(3,6);  
    @include omega(6);        /* we do need omega, this time with context */  
  }
}

That's all it takes. Here's the result for our two nested classes:
.main-content .main-left-half {  
  float: left;                  
  width: 48.276%;           /* 3 columns out of 6 */  
  margin-right: 3.448%;     /* right gutter */  
}

.main-content .main-right-half {  
  float: right;                  
  width: 48.276%;           /* 3 columns out of 6 */  
  margin-right: 0;          /* no right gutter */  
}

Prefix, Suffix and Shortcuts

Susy also provides some shortcuts for adding blank columns before and after the column you are working on. They work exactly like 'columns', but they add to the left and right padding of the element you are working on:
.column-with-padding {  
  @include columns(3,6);  
  @include prefix(1,6);  
  @include suffix(2,6);  
  @include omega(6);  
}

That will give us a width of 3 columns, with 1 column padding on the left and 2 columns padding on the right, all floated left, with no right gutter. We just used all six columns. Let's clean that up with some shortcuts.
The 'pad' shortcut allows us to add both prefix and suffix. The 'full' shortcut replaces columns, alpha and omega when we plan to span the full context:
.column-with-padding {  
  @include full(6);  
  @include pad(1,2,6);  
}

The only change in output is that Susy wont bother setting a width and floating it left. Why should we? The width will happen automatically, and the float isn't needed.
Accessing The Math with Functions

You can also access the math more directly and use it wherever you want with Susy's functions. The functions work exactly like their mixin counterparts, but only return the numbers:
.functions {  
  width: columns(3);  
  margin-right: gutter();  
  margin-left: columns(4) + gutter() + side-gutter();  
  padding-right: columns(1);  
}

Visualizing Your Grid

Susy includes a mixin to show you the grid as a background-image on your container element:
.container {  
    @include container;  
    @include susy-grid-background;  
}

Right-to-Left or Multi-Direction Grids

Susy now handles grids going in any direction, even multiple directions in one site. The simplest option is to change the $from-direction setting in your 'base' sass file. By default it is set to 'left'. Change that, and everything in Susy should just work:
$from-direction: right;

Now alpha columns will be on the right, and omega columns on the left. Gutters will be on the left of columns, etc. Everything works the same.
If you need to override the direction for specific widgets, all the affected mixins can be sent a final $from argument. Those mixins include columns, alpha, omega, prefix, suffix and pad:
.rtl-widget {  
  @include columns(3,6,right)  
  @include prefix(1,6,right)  
  @include omega(6,right)  
}