diff --git a/doc-src/content/CHANGELOG.markdown b/doc-src/content/CHANGELOG.markdown index b3400b65..f0763321 100644 --- a/doc-src/content/CHANGELOG.markdown +++ b/doc-src/content/CHANGELOG.markdown @@ -14,8 +14,14 @@ The Documentation for the [latest stable release](http://compass-style.org/docs/ The Documentation for the [latest preview release](http://beta.compass-style.org/) +0.11.alpha.2 (12/05/2010) +------------------------- + +* Merge with Lemonade. Compass now provides a full featured spriting solution. + See the [spriting tutorial](/help/tutorials/spriting/) for more information. + 0.11.alpha.1 (11/22/2010) ---------------------------- +------------------------- * Support for Sass 3.1 alpha version * CSS3 PIE module. [Docs](/reference/compass/css3/pie/). @@ -30,8 +36,8 @@ The Documentation for the [latest preview release](http://beta.compass-style.org and `box-shadow` mixins. * The docs are [getting a make-over](http://beta.compass-style.org/) by Brandon :) -0.11.alpha.0 (11/15/2010) ---------------------------- +0.11.alpha.0 (11/15/2010) +------------------------- Note: Compass does not currently support Sass 3.1 alphas. diff --git a/doc-src/content/help/tutorials/spriting.markdown b/doc-src/content/help/tutorials/spriting.markdown index cb771047..448aff9e 100644 --- a/doc-src/content/help/tutorials/spriting.markdown +++ b/doc-src/content/help/tutorials/spriting.markdown @@ -5,4 +5,162 @@ crumb: Spriting classnames: - tutorial --- -# Spriting with Compass \ No newline at end of file +# Spriting with Compass + +Spriting has never been easier with Compass. You place the sprite images to be in a folder, +import them into your stylesheet, and then you can use the sprite in your selectors in one +of several convenient ways. + +## Setup + +For this tutorial, let's imagine that in your project's image folder there are four icons: + +* `public/images/icon/new.png` +* `public/images/icon/edit.png` +* `public/images/icon/save.png` +* `public/images/icon/delete.png` + +Each is an icon that is 32px square. + +## Basic Usage +The simplest way to use these icon sprites is to let compass give you a class for each sprite: + + @import "icon/*.png"; + @include all-icon-sprites; + +And you'll get the following CSS output: + + .icon-sprite, + .icon-delete, + .icon-edit, + .icon-new, + .icon-save { background: url('/images/icon.png?1291584143') no-repeat; } + + .icon-delete { background-position: 0 0; } + .icon-edit { background-position: 0 -32px; } + .icon-new { background-position: 0 -64px; } + .icon-save { background-position: 0 -96px; } + +You can now apply the `icon-XXX` classes to your markup as needed. + +Let's go over what happened there. The import statement told compass to [generate a +stylesheet that is customized for your sprites](https://gist.github.com/729507). This +stylesheet is [magic](#magic-imports), it is not written to disk, and it can be customized +by setting configuration variables before you import it. See the section below on +[Customization Options](#customization-options). The goal of this stylesheet is to provide a +simple naming convention for your sprites so that you they are easy to remember and use. You +should never have to care what the is name of the generated sprite map, nor where a sprite +is located within it. + +## Selector Control + +If you want control over what selectors are generated, it is easy to do. In this example, +this is done by using the magic `icon-sprite` mixin. Note that the mixin's name is dependent +on the name of the folder in which you've placed your icons. + + @import "icon/*.png"; + + .actions { + .new { @include icon-sprite(new); } + .edit { @include icon-sprite(edit); } + .save { @include icon-sprite(save); } + .delete { @include icon-sprite(delete); } + } + +And your stylesheet will compile to: + + .icon-sprite, + .actions .new, + .actions .edit, + .actions .save, + .actions .delete { background: url('/images/icon.png?1291584143') no-repeat; } + + .actions .new { background-position: 0 -64px; } + .actions .edit { background-position: 0 -32px; } + .actions .save { background-position: 0 -96px; } + .actions .delete { background-position: 0 0; } + + +## Magic Imports + +As noted above, compass will magically create sprite stylesheets for you. Some people like +magic, some people are scared by it, and others are curious about how the magic works. If +you would like to avoid the magic, you can use compass to generate an import for you. On the +command line: + + compass sprite "public/images/icon/*.png" + +This will create file using your project's preferred syntax, or you can specify the +output filename using the `-f` option and the syntax will be inferred from the extension. +If you do this, you'll need to remember to regenerate the import whenever you rename, add, +or remove sprites. + +Using the magic imports is recommended for most situations. But there are times when you +might want to avoid it. For instance, if your sprite map has more than about 20 to 30 +sprites, you may find that hand crafting the import will speed up compilation times. See +the section on [performance considerations](#performance) for more details. + + +## Customization Options + +### Options per Sprite Map + +When constructing the sprite map, the entire sprite map and it's associated stylesheet +can be configured in the following ways. Each option is specified by setting a [configuration +variable](/help/tutorials/configurable-variables/) before importing the sprite. The variables +are named according to the name of the folder containing the sprites. In the examples below +the sprites were contained within a folder called `icon`. + +* `$-spacing` -- The amount of transparent space, in pixels, around each sprite. + Defaults to `0px`. E.g. `$icon-spacing: 20px`. +* `$-repeat` -- Wether or not each sprite should repeat along the x axis. Defaults + to `no-repeat`. E.g. `$icon-repeat: repeat-x`. +* `$-position` -- The position of the sprite in the sprite map along the x-axis. Can + be specified in pixels or percentage of the sprite map's width. `100%` would cause the + sprite to be on the right-hand side of the sprite map. Defaults to `0px`. + E.g. `$icon-position: 100%`. +* `$-sprite-dimensions` -- Whether or not the dimensions of the sprite should be + included in each sprite's CSS output. Can be `true` or `false`. Defaults to `false`. +* `$-sprite-base-class` -- The base class for these sprites. Defaults to `.-sprite`. + E.g. `$icon-sprite-base-class: ".action-icon"` + +### Options per Sprite + +When constructing the sprite map, each sprite can be configured in the following ways: + +* `$--spacing` -- The amount of transparent space, in pixels, around the sprite. Defaults + to the sprite map's spacing which defaults to `0px`. E.g. `$icon-new-spacing: 20px`. +* `$--repeat` -- Wether or not the sprite should repeat along the x axis. Defaults + to the sprite map's repeat which defaults to `no-repeat`. E.g. `$icon-new-repeat: repeat-x`. +* `$--position` -- The position of the sprite in the sprite map along the x-axis. Can + be specified in pixels or percentage of the sprite map's width. `100%` would cause the + sprite to be on the right-hand side of the sprite map. Defaults to the sprite map's + position value which defaults to `0px`. E.g. `$icon-new-position: 100%`. + + +## Performance Considerations + +Reading PNG files and assembling new images and saving them to disk might have a non-trivial +impact to your stylesheet compilation times. Especially for the first compile. Please keep +this in mind. + +## Large numbers of sprites +The magic stylesheet can get very large when there are large numbers of sprites. 50 sprites +will cause there to be over 150 variables created and then passed into the `sprite` function. +You may find that customizing the sprite function call to only pass those values that you +are overriding will provide a performance boost. + +## Oily PNG + +Compass generates PNG files using a pure-ruby library called +[`chunky_png`](https://github.com/wvanbergen/chunky_png). This library can be made faster by +installing a simple C extension called [`oily_png`](https://github.com/wvanbergen/oily_png). +Add it to your `Gemfile` if you have one in your project: + + gem 'oily_png' + +Or install the Rubygem: + + gem install oily_png + +Compass will automatically detect its presence. \ No newline at end of file