crispy-grid 0.3.1 → 0.4.0

data/README.md

@@ -36,19 +36,17 @@ way.
 
 Crispy tries to support you even if you go beyond the main grid.
 
-## Usage
-
-Pending. Please have a look at the source.
-
 ## Installation
 
 1. In your Gemfile add:
 
-    gem 'crispy-grid'
+    ``gem 'crispy-grid'``
 
-2. In your project configuration file (e.g. initializers/compass.rb, [you might want to](https://github.com/Compass/compass-rails/blob/stable/README.md#configuration) create one if it does not exist yet) add:
+2. *Skip this step if you have Rails >= 3 and Compass >= 0.11.*
+ 
+    In your project configuration file (e.g. initializers/compass.rb, [you might want to](https://github.com/Compass/compass-rails/blob/stable/README.md#configuration) create one if it does not exist yet) add:
 
-    require 'crispy-grid'
+    ``require 'crispy-grid'``
 
 3. Customize and import the grid in your application stylesheet:
 
@@ -86,6 +84,131 @@ $grid-columns: 30, 24, 24, 13
 @import crispy/grid
 ```
 
+### Configuration for using border-box
+
+By default, Crispy Grid mimics this more natural behavior for a box-sizing: content-box setting by doing calculations. If you start a new project and do not have to support IE7, we recommend you to use box-sizing: border-box instead.
+When switching an old project to border-box-sizing you need to tell Crispy Grid so. This is as simple as initializing it with `$grid-box-sizing` like so
+
+``` sass
+...
+$grid-box-sizing: border-box
+
+// Import Crispy Grid below the configuration
+...
+```
+
+Setting the `$grid-box-sizing` to `border-box` will tell the grid to
+ignore its padding calculations as they are no longer needed when using
+the `border-box` box-model. However this will not apply `border-box` to
+your elements. Most likely you'll want to apply `border-box` to all your
+elements. The way [Paul Irish recommends](http://www.paulirish.com/2012/box-sizing-border-box-ftw/) looks like this when using Compass.
+
+``` sass
+*
+  +box-sizing(border-box)
+```
+
+In most cases this will be the way to go. However, there might be the
+edge cases where you don't want to apply `border-box` to all your
+elements. That's why setting the box-model is not part of Crispy Grid's
+`$grid-box-sizing` option.
+
+## Usage
+
+### Mixins
+
+The only things you need to know for using Crispy Grid are these 3 mixins:
+
+1. `+grid-container`
+  * Include this in your container element(s) that contain your whole grid.
+2. `+column`
+  * This is the most important mixin. Include e.g. `+column(5)` to span 5 columns, each having a gutter to the right-hand side.
+3. `+last`
+  * Use this to indicate that a column is the last one in a row. It just removes the right gutter.
+
+Use might also find these mixins useful:
+
+1. `+last-column`
+  * This combines `+column` and `+last`. You should favor it over the two in order to reduce CSS output.
+2. `+row`
+  * Use this for columns that span the whole row. This mixin just calls `+column` with the configured count of `$grid-columns`.
+
+### Options
+
+#### Options for `+column`, `+last-column`, `+row`
+* `$colspan`
+  * Specifies the number of grid columns the element should span
+  * If the element does not fit into the grid, you can also specify a fixed width.
+  * It is the only mandatory parameter.
+  * Examples: `+column(5)`, `+column(120px)`, `+row($colspan: 23)`
+* `$device`
+  * Relevant if you have [configured multiple devices](#configuration-for-multiple-devices)
+  * Default: `default-device()` - that is the value of `$device` or the first one in `$devices`
+  * The device must be contained in your `$devices` configuration.
+  * Examples: `+column(3, $device: tablet)`, `+last-column(1, $device: handheld-320)`
+* `$padding`
+  * Now the fun stuff: Even when you use the browser default setting `box-sizing: content-box`, it is ensured that you do not break the grid by setting padding or a border.
+  * Default: 0
+  * Reduces the resulting `width` attribute of your column (unless you configured `$grid-box-sizing: border-box`)
+  * It is applied to both left and right by default.
+  * `padding-top` and `padding-bottom` are out of scope - just set them separately.
+  * Just like `$colspan`, you can also specify a number of columns.
+  * Examples: `+column(5, $padding: 10px)`, `+column(10, $padding: 1)` - they will have the same overall width as `+column(5)` / `+column(10)`
+* `$differing-right-padding`
+  * Override `$padding` for the right side or exclusively set `$padding` for the right side
+  * Default: false
+  * Examples: `+column(5, $padding: 10px, $differing-right-padding: 15px)`, `+column(5, $differing-right-padding: 10px)`
+* `$border-width`
+  * Same principle as `$padding`
+  * This just sets the CSS `border-width` property when using `$grid-box-sizing: border-box`. Otherwise, it also effects the `width` property.
+* `$differing-right-border-width`
+  * Same principle as `$differing-right-padding`
+* `$gutter`
+  * Customize the gutter (i.e. right margin) of a column
+  * Default: `grid-gutter-width($device)`
+  * Does not affect the "inner gutters"; i.e. if your `grid-gutter-width()` is 10px, `+column(5, $gutter: 15px)` will just add 5px overall whitespace, not 5*5px.
+* `$left-gutter`
+  * Normally, gutters are only right with Crispy Grid. But you might have your reasons.
+  * Default: false
+  * Examples: `+column(5, $gutter: 10px, $left-gutter: 10px)`, `+last-column($left-gutter: 10px)`
+* `$subtract-border-from`
+  * Sometimes you could say `+column(10, $padding: 1)` if there wasn't a 1px border that tries to ruin your grid (because you rely on box-sizing: content-box).
+  * You can use e.g. `+column(10, $padding: 1, $border-width: 1px, $subtract-border-from: padding)` instead of `+column(10, $padding: 29px, $border-width: 1px)`.
+  * Default: false
+  * Possible values: `padding`, `left-padding`, `right-padding`, `gutter`, `left-gutter`, `right-gutter`
+  * Example: `+column(10, $border-width: 2px, $subtract-border-from: gutter)`
+  * This option does nothing useful when using `$grid-box-sizing: border-box`.
+
+#### Options for `+grid-container`
+* `$device`
+  * see above
+* `$colspan`
+  * Default: `grid-columns($device)`
+  * see above
+* `$padding: 0`
+  * Unlike with columns, paddings and borders of a container do not affect its inner width.
+  * So the real grid starts with within the container paddings
+  * Example: `+grid-container($colspan: 24, $padding: 30px)` still leaves 24 full columns to its content
+* `$differing-right-padding`
+  * see above
+* `$border-width`
+  * see above
+* `$differing-border-width`
+  * see above
+* `$left-margin`
+  * Normally containers should be horizontally centered on the page.
+  * Default: auto
+  * If you wish to enforce to have whitespace around your container even if the browser window is not bigger than your content, you should do so by setting `$padding`.
+* `$right-margin`
+  * see above
+* `clearfix`
+  * Clearfixing has to be done in order to enforce the container to enclose its content.
+  * Default: overflow
+  * Possible values: `overflow`, `pie`, `pie-clearfix` (same as `pie`)
+  * By default, the overflow: hidden method is used. This might get in your way when you have content that wants to 'break out' of your container.
+  * Specify `$clearfix: pie` if container contents should be visible outside of the container (e.g. when positioned absolutely).
+  * See the used [Compass clearfix lib](http://compass-style.org/reference/compass/utilities/general/clearfix/)
+
 ## Changelog
 
 There is one. [Have a look at it](https://github.com/ChristianPeters/crispy-grid/blob/master/CHANGELOG.md).

data/stylesheets/_crispy-grid.sass

@@ -9,6 +9,7 @@
 // $grid-column-width: 30px
 // $grid-gutter-width: 10px
 // $grid-columns: 24
+// $grid-box-sizing: content-box
 
 // Configuration for Multiple Devices
 // ----------------------------------

data/stylesheets/crispy/_grid.sass

@@ -9,6 +9,7 @@ $grid-column-widths: false !default
 $grid-gutter-width: false !default
 $grid-gutter-widths: false !default
 $grid-columns: 24 !default
+$grid-box-sizing: content-box !default
 
 @function default-device()
   @return $device or nth($devices, 1)
@@ -106,7 +107,10 @@ $grid-columns: 24 !default
     width: $column-width
   @else
     // Paddings and borders do not affect the outer width of a column.
-    width: $column-width - $padding-sum - $border-width-sum
+    @if $grid-box-sizing == 'border-box'
+      width: $column-width
+    @else
+      width: $column-width - $padding-sum - $border-width-sum
 
   // Setting other box attributes
   padding:

metadata

@@ -1,16 +1,23 @@
 --- !ruby/object:Gem::Specification 
 name: crispy-grid
 version: !ruby/object:Gem::Version 
+  hash: 15
   prerelease: 
-  version: 0.3.1
+  segments: 
+  - 0
+  - 4
+  - 0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Christian Peters
+- Lucas Nolte
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2012-05-04 00:00:00 Z
+date: 2013-10-28 00:00:00 +01:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: compass
@@ -20,6 +27,10 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 29
+        segments: 
+        - 0
+        - 11
         version: "0.11"
   type: :runtime
   version_requirements: *id001
@@ -31,11 +42,16 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 1
+        - 2
         version: 3.1.2
   type: :runtime
   version_requirements: *id002
 description: In short, Crispy Grid closes the gap between easy-to-use grids for simple web pages and doing everything by hand due to layout complexity.
-email: info@c-peters.net
+email: crispy.dev@gmail.com
 executables: []
 
 extensions: []
@@ -50,6 +66,7 @@ files:
 - stylesheets/crispy/_grid.sass
 - templates/project/_crispy-grid.sass
 - templates/project/manifest.rb
+has_rdoc: true
 homepage: https://github.com/ChristianPeters/crispy-grid
 licenses: []
 
@@ -63,17 +80,23 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.4.2
 signing_key: 
 specification_version: 3
 summary: A Compass-based Grid that strives for lean & sane CSS and supports complex layouts