github-migration/compass
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

broke out sprite docs to be less complex

Browse Source
This commit is contained in:
Scott Davis 2011-09-06 22:39:31 -04:00
parent e95ba13082
commit 16bbc81763
5 changed files with 14 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc-src/Gemfile
View File

@ -12,8 +12,9 @@ gem 'nokogiri'
gem 'coderay'
gem 'haml'
gem 'rake'
gem 'activesupport', '~> 3.0.10', :require => 'active_support/inflector'
gem 'compass', :path => ".."
gem 'compass-theme', '~> 0.0.1'
gem 'compass-theme', :path => '../../compass-theme' #:git => 'git://github.com/Compass/compass-theme.git'
# gem 'compass-susy-plugin', ">=0.7.0.pre8"
# gem 'css-slideshow', "0.2.0"
gem 'json'

1
doc-src/Rules
View File

@ -63,6 +63,7 @@ end
compile '*' do
if item[:extension] == "markdown"
filter :erb
filter :rdiscount
elsif item[:extension] == "haml"
filter :haml, :ugly => true

125
doc-src/content/help/tutorials/spriting.markdown
View File

@ -5,12 +5,16 @@ crumb: Spriting
classnames:
- tutorial
---
# Spriting with Compass
Spriting has never been easier with Compass. You place the sprite images in a folder,
import them into your stylesheet, and then you can use the sprite in your selectors in one
of several convenient ways.
## Sprite Tutorial Contents
<%= sprite_tutorial_links(true) %>
## Setup
For this tutorial, let's imagine that in your project's image folder there are four icons:
@ -23,6 +27,9 @@ For this tutorial, let's imagine that in your project's image folder there are f
Each is an icon that is 32px square.
## Basic Usage
****Note**: The use of `icon` is only for this example, "icon" represents the folder name that contains your sprites.
The simplest way to use these icon sprites is to let compass give you a class for each sprite:
@import "icon/*.png";
@ -45,31 +52,13 @@ 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
stylesheet is [magic](/help/tutorials/spriting/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
[Customization Options](/help/tutorials/spriting/customization). 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.
<a name="layout-control"></a>
## Layout Control
Set the `$<sprite>-layout` variable to the preferred layout method.
* vertical - default
* horizontal - lays images out side by side
* diagonal - lays images out corner to corner none of the spacing of padding options are taken into account
* smart - lays the images out using a bin packing algorithm which allows for much smaller surface areas in your sprite files - does not support spacing or padding
Example:
$icon-layout:horizontal;
@import "icon/*.png";
$dropcap-layout:diagonal
@import "dropcap/*.png";
<a name="selector-control"></a>
## Selector Control
@ -119,102 +108,6 @@ might want to avoid it. For instance, if your sprite map has more than about 20
sprites, you may find that hand crafting the import will speed up compilation times. See
the section on [performance considerations](#performance) for more details.
<a name="magic-selectors"></a>
## Magic Selectors
If you want to add selectors for your sprites, it's easy todo by adding `_active` `_target` or `_hover` to the file name, In the example below we have a sprite directory that looks like:
* `selectors/ten-by-ten.png`
* `selectors/ten-by-ten_hover.png`
* `selectors/ten-by-ten_active.png`
* `selectors/ten-by-ten_target.png`
Now in our sass file we add:
@import "selectors/*.png";
a {
@include selectors-sprite(ten-by-ten)
}
And your stylesheet will compile to:
.selectors-sprite, a {
background: url('/selectors-sedfef809e2.png') no-repeat;
}
a {
background-position: 0 0;
}
a:hover, a.ten-by-ten_hover, a.ten-by-ten-hover {
background-position: 0 -20px;
}
a:target, a.ten-by-ten_target, a.ten-by-ten-target {
background-position: 0 -30px;
}
a:active, a.ten-by-ten_active, a.ten-by-ten-active {
background-position: 0 -10px;
}
Alternatively you can use the `@include all-selectors-sprites;` after the import and get the following output:
.selectors-sprite, .selectors-ten-by-ten {
background: url('/selectors-sedfef809e2.png') no-repeat;
}
.selectors-ten-by-ten {
background-position: 0 0;
}
.selectors-ten-by-ten:hover, .selectors-ten-by-ten.ten-by-ten_hover, .selectors-ten-by-ten.ten-by-ten-hover {
background-position: 0 -20px;
}
.selectors-ten-by-ten:target, .selectors-ten-by-ten.ten-by-ten_target, .selectors-ten-by-ten.ten-by-ten-target {
background-position: 0 -30px;
}
.selectors-ten-by-ten:active, .selectors-ten-by-ten.ten-by-ten_active, .selectors-ten-by-ten.ten-by-ten-active {
background-position: 0 -10px;
}
<a name="customization-options"></a>
## 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`.
* `$<map>-spacing` -- The amount of transparent space, in pixels, around each sprite.
Defaults to `0px`. E.g. `$icon-spacing: 20px`.
* `$<map>-repeat` -- Wether or not each sprite should repeat along the x axis. Defaults
to `no-repeat`. E.g. `$icon-repeat: repeat-x`.
* `$<map>-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%`.
* `$<map>-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`.
* `$<map>-sprite-base-class` -- The base class for these sprites. Defaults to `.<map>-sprite`.
E.g. `$icon-sprite-base-class: ".action-icon"`
* `$<map>-clean-up` -- Whether or not to removed the old sprite file when a new one is created. Defaults to true
### Options per Sprite
When constructing the sprite map, each sprite can be configured in the following ways:
* `$<map>-<sprite>-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`.
* `$<map>-<sprite>-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`.
* `$<map>-<sprite>-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%`.
<a name="performance"></a>
## Performance Considerations

2
doc-src/content/index.haml
View File

@ -12,7 +12,7 @@ layout: homepage
%ol
%li Experience cleaner markup without presentational classes.
%li It’s chock full of the web’s best reusable patterns.
%li Developing a personal framework is simple.
%li It makes creating <a href="/help/tutorials/spriting/">sprites</a> a breeze.
%li Compass mixins make CSS3 easy.
%li Download and create extensions with ease.
.sass