ericam-compass-susy-plugin 0.4.1 → 0.5.0

data/README.mkdn

@@ -70,10 +70,12 @@ Grid Basics
   grid.
 
 * Use the `+columns` mixin to declare the width in columns of an element,
+  or `+full` for any element spanning the full width of its context.
 
 * Use `+alpha` and `+omega` to declare elements which include the first or
   last column within their parent element (`+full` to declare both `+alpha`
-  and `+omega`).
+  and `+omega`). Note: `+alpha` is actually only needed in the very top level,
+  and does nothing in nested contexts. Neither is needed on a `+full` element.
 
 * Use `+prefix` or `+suffix` to give the width (in columns) of an elements
   left or right margin, or `+pad` to give both `+prefix` and `+suffix` at
@@ -91,13 +93,11 @@ That's it for the basics! Here's a sample Susy grid layout:
       +container
      
     #brand
-      +columns(8)
-      +pad(1,1)
       +full
+      +pad(1,1)
       h1
-        +columns(5,8)
-        +pad(1,2,8)
         +full(8)
+        +pad(1,2,8)
         
     #nav
       +columns(2)
@@ -108,7 +108,6 @@ That's it for the basics! Here's a sample Susy grid layout:
       +omega
       #description
         +columns(5,8)
-        +alpha(8)
       #credit
         +columns(3,8)
         +omega(8)
@@ -154,3 +153,77 @@ And then the fun stuff:
 
 * `+box-shadow(!verticaloffset, !horizontaloffset, !blur, !color)` for
   box-shadow in webkit and CSS3.
+
+Advanced Options
+================
+
+Susy is built for flexibility, so that you always write the code you want to
+write. While everything should 'just work' out of the box, there are plenty of
+advanced options hidden inside. Here's a few:
+
+* `!hacks` is a boolean constant that you can set in your base.sass file to
+  choose between using targeted hacks for IE (a variation of the star hack in
+  most cases) in your screen.css, or using a conditional-comment targeted
+  ie.css. All the needed mixins are available for either setting. `!hacks` is
+  true by default so there is no extra work maintaining multiple files unless
+  you want to.
+
+    Example 1:
+
+        !hacks = true
+    
+        #nav
+          +inline-block-list
+
+    Example 2:
+
+        !hacks = false
+    
+        (in screen.sass)
+        #nav
+          +inline-block-list
+      
+        (in ie.sass)
+        #nav li
+          +ie-inline-block
+
+  It requires more maintenance on your part, but the result is a hack-free output.
+  
+  The susy mixins that use either hacks or targeted mixins are `+omega`
+  ('+ie-omega([!right-floated = false])'), `+inline-block` (`+ie-inline-block`), and
+  `+inline-block-list` which sets `+inline-block` on the list items.
+  
+  These ie-specific mixins only add the needed ie-specific adjustments, so
+  they need to be used in addition to their counterparts, not on their own.
+
+* `gutter(!context)` is a function that you can call at any time to return the
+  size of a gutter in your given context using percentages. The number is
+  returned without units so that you can perform math on it. In order to use
+  it, you will have to add "%" to it.
+
+    Example:
+        
+        #nav
+          :padding-right= gutter(5) + "%"
+
+* `columns(!number, !context)` returns the span of `!number` columns in
+  `!context` as a percentage (again without the units declared). This span
+  includes any gutters between the columns spanned.
+
+    Example:
+        
+        #nav
+          :padding-left= columns(3,5) + "%"
+
+* `side_gutter()` is also available and takes no arguments since it is always
+  used at the top nesting level.
+
+* `px2em()` takes one numeric argument representing the number of pixels you
+  want to mimic. The return is an em value (with no units declared) that
+  approximates that number of pixels. Useful for keeping your entire design
+  fluid.
+  
+  Example:
+    
+      #nav
+        :border-bottom= px2em(2) + "em"

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.5.0

data/compass-susy-plugin.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{compass-susy-plugin}
-  s.version = "0.4.1"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Eric Meyer"]

data/docs/tutorial/index.mkdn

@@ -67,7 +67,8 @@ all your defaults.
 
 To create a grid, set the `!grid_unit` (units that your grid is based in),
 `!total_cols` (total number of columns in your grid), `!col_width` (width of
-columns), and `!gutter_width` (width of gutters) variables.
+columns), `!gutter_width` (width of gutters), and `!side_gutter_width` (width
+of side gutters) variables.
 
 The default values are 16 columns, 4em column widths, 1em gutters and side
 gutters that match the internal ones. But we want a 10 column grid, with 5em
@@ -96,43 +97,9 @@ The default values here are 12px fonts with an 18px line-height. For us:
 
 `_base.sass` also has everything you need for setting default font families,
 colors to reuse throughout, and default styles for all those elements that
-ought have a default (but don't because of the reset).
-
-We can leave most of that as it is for now, but let's fill in a few of the
-most important defaults. We want some colors to choose from, and defaults for
-links and paragraphs.
-
-So let's add some colors:
-
-    !text = #332016
-    !light = #CC8866
-    !links = #4CAAC0
-
-And style the links:
-    
-    a
-      &:link, &:visited
-        :color= !links
-        :text-decoration none
-      &:focus, &:hover, &:active
-        :color= !light
-        :border-bottom
-          :width= px2em(2) + "em"
-          :style dashed
-
-(Susy provides the convenience function `px2em`, which can approximate a pixel
-value in ems, given our chosen `!base_font_size_px`. Here we want the dashed
-bottom border to be 2 pixels wide at the default font size, but we size it in
-ems - the result here will be .1429em. Susy's math functions return bare
-numbers, so we add "em" ourselves).
-
-And we'll add a bit of margin to our paragraphs:
-    
-    p
-      :margin-bottom 1.5em
-
-That's it. You can look around at the other defaults and set what you like, or
-juse use [mine](../src/_base.sass).
+ought have a default (but don't because of the reset). we're going to skip
+that for now and play with the fun toys. You can look around at the other
+defaults and set what you like, or juse use [mine](../src/_base.sass).
 
 
 Making Semantic Grids 
@@ -148,17 +115,19 @@ First the explanation:
   building the grid shell, this sets your horizontal margins to auto (for
   centered designs) and returns your text-alignment to "left". Change the
   internal text alignment with an optional `left | center | right` argument.
-  
+
 * Use the `+columns` mixin to set the width (in columns) of a grid element.
   The first argument is the number of columns to span, the second (optional)
-  argument is the width (in columns) of the containing element when
-  nesting. If the element is not nested (its parent is the grid container),
-  don't pass a second argument.
+  argument is the width (in columns) of the containing element when nesting.
+  If the element is not nested (its parent is the grid container), don't pass
+  a second argument. For an element that will span the full width (including
+  prefix and suffix), you can simply use `+full`, which takes one argument
+  of the context (in columns) when nested.
 
 * Use the `+alpha` and `+omega` mixins to declare the first and last elements
-  in a row, or inside a nested element. In the latter case, each of these
-  mixins takes one argument, which is the size (in columns) of the containing
-  element.
+  in a row. In a nested context `+omega` takes one argument repesenting its
+  context. `+alpha` is only needed in the very top level, and does nothing in
+  nested contexts. Neither one is needed on a `+full` element.
 
 * Use the `+prefix` and `+suffix` mixins with one argument to add that many
   grid columns as padding before or after a grid element. These mixins also
@@ -179,21 +148,16 @@ is so tempting and easy with Sass. It's part personal preference and part
 Natalie Downe's voice in my head. Don't nest when you don't need to. It keeps
 your output code much cleaner.
 
-While we're at it, why don't we get the fonts and text colors going right from
-the start?
+While we're at it, why don't we get the fonts going right from the start?
 
     #page
       +container
       +sans-family
-      :color= !text
 
 Perfect. Take a look at [the results](02_container/). So far we have:
 
 * Reset everything. This happens by default in the background.
 
-* Added a few of our own replacement default styles, like links, paragraphs,
-  fonts and colors.
-
 * Created an elastic container for our grid at 70em that goes fluid for small
   windows (try it!).
 
@@ -202,7 +166,7 @@ Laying Out The Components
 --------------------------
 
 It's time to lay out our grid components. We'll just work our way through the
-DOM, starting with our brand header (#brand). We can refer back to our [target
+HTML, starting with our brand header (#brand). We can refer back to our [target
 site with a grid overlay](01_target/) to see what we need. Looks like our
 branding gets an entire row to itself, with the content starting one row
 in. For the sake of argument, let's say we want the header content contained
@@ -222,7 +186,8 @@ add:
     +omega
 
 Or we would have to, but there are several shortcuts available to us. To
-declare something as both alpha and omega we can just declare it as full:
+declare something as full width (both alpha and omega) we can just declare it
+as full:
 
     +full
 
@@ -230,26 +195,24 @@ There is also a shorcut for prefix and suffix additions (+pad), so we can
 simplify down to:
 
     #brand
-      +columns(8)
-      +pad(1,1)
       +full
+      +pad(1,1)
 
 Since we don't have an image in there yet, let's move the text over to line up
 with the future placement of our main content area. By turning the `h1` link
 into a grid element and prefixing a padding of one column, we can move the
 text without any effect on the image that will replace it (using the Compass
-utility `+replace-text`, though I'll leave the implementation that as an
+utility `+replace-text`, though I'll leave the implementation of that as an
 exercise for you to figure out). To line it all up with the content below it,
 we'll assign it 5 columns in a context of 8, with the extra 3 split between a
-prefix of 1 and a suffix of 2 - giving it a full span.
+prefix of 1 and a suffix of 2 - giving it a full span again. This time we are
+nested and need to supply the context.
 
     h1 a
-      +columns(5,8)
-      +pad(1,2,8)
       +full(8)
+      +pad(1,2,8)
 
-There is one 'gotcha' in the way Susy handles context. Direct children of your
-container (such as #brand in this case) *must not declare a context*.  If you
+Note: when not nested, you *must not declare a context*.  If you
 do, your side-gutters will be ignored. At every nested layer below that, even
 if the context hasn't changed, you *must declare a context* or it will try to
 add side-gutters again. That means even if you have one nested element
@@ -258,14 +221,18 @@ does not get a context but its descendants do, even where that context is the
 same as the full page.
 
 For example, these *will not work*:
-
+    
+    /*because context is declared at the top level:*/
     #page
       +container
+      
       .inner
-        +columns(10,10)
-
+        +columns(8,10)
+    
+    /*because context is not declared in a nested level:*/
     #page
       +container
+      
       .inner
         +columns(10)
         #brand
@@ -275,12 +242,11 @@ This *will work*:
 
     #page
       +container
+      
       .inner
         +columns(10)
         #brand
-          +columns(10,10)
-
-Remember that if your side gutters or columns ever seem the wrong size.
+          +columns(8,10)
 
 We're only worried about structure for now, so the header is done. Let's move
 on to the navigation (#nav). The nav spans 2 columns, including the first
@@ -290,40 +256,37 @@ column in it's context.
       +columns(2)
       +alpha
 
-Done. The content (#content, which includes both #description and #credit)
+Done. The #content (which includes both #description and #credit)
 spans the remaining 8 columns, including the last one.
 
     #content
       +columns(8)
       +omega
 
-Done. #description spans 5, including the first; #credit spans 3 including
-the last. Both are in a nested context of 8, which we now need to pass on:
+Done. #description spans 5; #credit spans 3 including the last. Both are in a
+nested context of 8, which we now need to pass on:
 
     #description
       +columns(5,8)
-      +alpha(8)
     
     #credit
       +columns(3,8)
       +omega(8)
 
 Done and done. All we have left is the footer (#site-info) spanning the full
-width, but only using the right 8 columns:
+width, but with two blank columns on the left:
 
     #site-info
-      +columns(8)
-      +prefix(2)
       +full
+      +prefix(2)
 
-Nested in the footer are `.license` and `.styles`, so let's put them in
-place. I'm going to say that each should match the width of the element
-visually above it on the page. So .license will span 5 columns including the
-first in its context of 8, and .styles will span 3 including the last.
+Nested in the footer are `.license` and `.styles`, so let's put them in place.
+I'm going to say that each should match the width of the element visually
+above it on the page. So .license will span 5 columns in its context of 8, and
+.styles will span 3 including the last.
 
     p.license
       +columns(5,8)
-      +alpha(8)
     p.styles
       +columns(3,8)
       +omega(8)

data/sass/susy/_grid.sass

@@ -50,44 +50,67 @@
 =suffix(!n, !context = false)
   :padding-right= columns(!n, !context) + gutter(!context) + "%"
 
+//**
+  set as shortcut for prefix and suffix
+=pad(!p = 0, !s = 0, !c = false)
+  @if !p != 0
+    +prefix(!p,!c)
+  @if !s != 0
+    +suffix(!s,!c)
+
 //**  
-  set on the first element of a row to take side-gutters into account
-  - must set !n for nested columns
+  set on any element spanning the first column in non-nested context
+  to take side-gutters into account
 =alpha(!nested = false)
-  @if !nested
-    :margin-left 0
-  @else
+  @if !nested == false
     :margin-left= side_gutter() + "%"
 
+//**
+  when global constant !hacks == true:
+  - this will be called automatically with hacks
+  when global constant !hacks == false:
+  - you can call it yourself in ie.sass without the hacks
+=ie-omega(!nested = false, !right = false, !hack = false)
+  !s = side_gutter()
+  @if !right
+    @if !hack
+      :#margin-left -1%
+    @else
+      :margin-left -1%
+  @else
+    @if !nested
+      @if !hack
+        :#margin-right -1%
+      @else
+        :margin-right -1%
+    @else
+      @if !hack
+        :#margin-right= !s - 1 + "%"
+      @else
+        :margin-right= !s - 1 + "%"
+
 //**  
   set on the last element of a row to take side-gutters into account
   - set !nested for nested columns
-  - set !right for right-floated omega elements
+  - set !float for right-floated omega elements
 =omega(!nested = false, !right = false)
   !s = side_gutter()
   @if !nested
     :margin-right 0
   @else
     :margin-right= !s + "%"
-  /* ugly hacks for IE6-7 */
-  @if !right
-    :#margin-left -1%
-  @else
-    @if !nested
-      :#margin-right -1%
-    @else
-      :#margin-right= !s - 1 + "%"
-
+  @if !hacks
+    /* ugly hacks for IE6-7 */
+    +ie-omega(!nested, !right,"*")
+    /* end ugly hacks */
+    
 //**
   set on an element that will span it's entire context
-=full(!n = false)
-  +alpha(!n)
-  +omega(!n)
-
-//**
-  set as shortcut for prefix and suffix
-=pad(!p = 0, !s = 0, !c = false)
-  @if !p != 0
-    +prefix(!p,!c)
-  @if !s != 0
-    +suffix(!s,!c)
+  - no need for +columns, +alpha or +omega on a +full element
+=full(!nested = false)
+  :clear both
+  +clearfix
+  @if !nested == false
+    !s = side_gutter() + "%"
+    margin-right= !s
+    margin-left= !s

data/sass/susy/_susy.sass

@@ -1,3 +1,7 @@
+//**
+  tell susy whether you are using hacks or conditional comments
+!hacks ||= true
+
 @import utils.sass
 @import text.sass
 @import grid.sass

data/sass/susy/_utils.sass

@@ -13,18 +13,39 @@
   div
     :background rgba(0,0,0,.125)
 
+//**
+  brings IE in line with inline-block display
+  - using hacks if called automatically because !hacks == true
+  - or without if you call it from ie.sass
+=ie-inline-block(!hack = false)
+  @if !hack
+    /* ugly hacks for IE6-7 */
+    :#display inline
+    // fixes alignment against native input/button on IE6
+    :#vertical-align auto
+    /* end ugly hacks */
+  @else
+    :display inline
+    // fixes alignment against native input/button on IE6
+    :vertical-align auto
+
+//**
+  an override for compass inline-block that lets you take advantage
+  of Susys !hacks constant. if true, hacks. if false, use ie-inline-block
+  to help ie along in your ie.sass
 =inline-block
   :display -moz-inline-box
   :-moz-box-orient vertical
   :display inline-block
   :vertical-align middle
-  :#display inline
-  // fixes alignment against native input/button on IE6
-  :#vertical-align auto
+  @if !hacks
+    +ie-inline-block("*")
 
 //** 
   an inline-block list that works in IE
   for those awkward moments when a floated horizontal list just wont cut it
+  if global !hacks == false:
+  - you'll need to fix list items in ie.sass with +ie-inline-block
 =inline-block-list(!hpad = 0)
   +horizontal-list-container
   li

data/templates/project/_base.sass

@@ -1,7 +1,7 @@
 //**
 //  Susy: Elastic-Fluid grids without all the math
 //  by Eric Meyer and OddBird Collective
-//  oddbird. 
+//  Site: www.oddbird.net/susy/
 //**
 
 //** 
@@ -14,6 +14,14 @@
 // !gutter_width = 1
 // !side_gutter_width = !gutter_width
 
+//**
+  HACKS
+  Are you using hacks or conditional comments? Susy makes both possible.
+  Leave this as 'true' to use hacks, set it as false for conditional comments.
+  Conditional comments will require overrides for +omega, +inline-block and
+  several other mixins.
+  !hacks = true
+
 //** 
   FONT-SIZE
   un-comment and override these values as needed (defaults are shown)
@@ -27,7 +35,6 @@
 //  (don't move this @import above the GRID and FONT-SIZE overrides)
 @import susy/susy.sass
 
-
 // COLORS
 // set any colors you will need later
 !dark = #000
@@ -41,18 +48,26 @@
 =serif-family
   :font-family 'Adobe Caslon Pro', 'Big Caslon', Garamond, 'Hoefler Text', 'Times New Roman', Times, serif 
 
-
 // Remember to add default styles to everything!
-/* DEFAULTS
+
+/* @group links */
+
 \:focus
 
-/* links
 a
 
-/* headers
+/* @end */
+
+
+/* @group headers */
+
 h1, h2, h3, h4, h5, h6
 
-/* forms
+/* @end */
+
+
+/* @group forms */
+
 form
 
 fieldset
@@ -65,7 +80,11 @@ input
 
 input[type=submit]
 
-/* block tags
+/* @end */
+
+
+/* @group block tags */
+
 p
 
 =list-default(!ol = false)
@@ -84,7 +103,11 @@ ul
 
 blockquote
 
-/* inline tags
+/* @end */
+
+
+/* @group inline tags */
+
 cite
 
 em
@@ -99,5 +122,11 @@ ins
 del
   :text-decoration line-through
 
-/* replaced tags
+/* @end */
+
+
+/* @group replaced tags */
+
 img
+
+/* @end */

data/templates/project/screen.sass

@@ -42,7 +42,7 @@
 
 /* @group DEBUG */
 
-/*   uncomment, adjust and use for debugging
+/*   uncomment, adjust and use for debugging    */
   
 /*
   #page

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ericam-compass-susy-plugin
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors: 
 - Eric Meyer
@@ -67,6 +67,7 @@ files:
 - compass-susy-plugin.gemspec
 has_rdoc: false
 homepage: http://github.com/ericam/compass-susy-plugin
+licenses: 
 post_install_message: 
 rdoc_options: 
 - --line-numbers
@@ -92,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: compass-susy-plugin
-rubygems_version: 1.2.0
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
 summary: A Compass grid system plugin.