From 7aba64eb41a9d725a185b7ccf4c523a3ce7a4c31 Mon Sep 17 00:00:00 2001 From: Chris Eppstein Date: Wed, 1 Dec 2010 01:35:05 -0800 Subject: [PATCH] Reference documentation on spriting --- .../content/help/tutorials/spriting.markdown | 8 ++ .../reference/compass/helpers/sprites.haml | 132 ++++++++++++++++++ .../compass/utilities/sprites/base.haml | 18 +++ 3 files changed, 158 insertions(+) create mode 100644 doc-src/content/help/tutorials/spriting.markdown create mode 100644 doc-src/content/reference/compass/helpers/sprites.haml create mode 100644 doc-src/content/reference/compass/utilities/sprites/base.haml diff --git a/doc-src/content/help/tutorials/spriting.markdown b/doc-src/content/help/tutorials/spriting.markdown new file mode 100644 index 00000000..cb771047 --- /dev/null +++ b/doc-src/content/help/tutorials/spriting.markdown @@ -0,0 +1,8 @@ +--- +title: Spriting with Compass +layout: tutorial +crumb: Spriting +classnames: + - tutorial +--- +# Spriting with Compass \ No newline at end of file diff --git a/doc-src/content/reference/compass/helpers/sprites.haml b/doc-src/content/reference/compass/helpers/sprites.haml new file mode 100644 index 00000000..91f70f2e --- /dev/null +++ b/doc-src/content/reference/compass/helpers/sprites.haml @@ -0,0 +1,132 @@ +--- +title: Compass Sprite Helpers +crumb: Sprites +framework: compass +meta_description: Helper functions for working with Sprite images. +layout: core +classnames: + - reference + - core + - helpers +--- +%h1 Compass Sprite Helpers + +:markdown + These helpers make it easier to build and to work with sprites. + + While it is allowed to use these directly, to do so is considered "advanced usage". + It is recommended that you instead use the sprite mixins that are designed to work + with these functions. + + See the [Spriting Tutorial](/help/tutorials/spriting/) for more information. + +#sprite-map.helper + %h3 + %a(href="#sprite-map") + sprite-map($glob, ...) + .details + :markdown + Generates a sprite map from the files matching the glob pattern. Uses the + keyword-style arguments passed in to control the placement. + + Only PNG files can be made into sprites at this time. + + The `$glob` should be glob pattern relative to the images directory that specifies + what files will be in the sprite. For example: + + $icons: sprite-map("icons/*.png"); + background: $icons; + + This will generate a sprite map and return a reference to it. It's important to + capture this to a variable, because you will need to use it later when creating + sprites. In the above example you might end up with a new file named + `images/sprites/icons-a2ef041.png` and your css stylesheet will have: + + background: url('/images/sprites/icons-a2ef041.png?1234678') no-repeat; + + The exact image name is not something you should depend on as it may change based on the + arguments you pass in. Instead, you can use the `sprite-url()` function to create a + reference to the sprite map without generating the image again. Alternatively, simply + using the sprite map variable in an property will have the same effect as calling + `sprite-url()`. + + For each sprite in the sprite map you can control the position, spacing, and whether or + not it repeats. You do this by passing arguments to this function that tell each sprite + how to behave. For instance if there is a icons/new.png then you can control it like so: + + $icon-sprite: sprite-map("icons/*.png", + $new-position: 100%, $new-spacing: 15px, $new-repeat: no-repeat); + + If you don't specify these options they will default to `0%` for `position`, + `0px` for spacing, and `no-repeat` for `repeat`. + + Default values for all sprites can be specified by passing values for `$position`, + `$spacing`, and `$repeat`. + +#sprite.helper + %h3 + %a(href="#sprite") + sprite($map, $sprite, $offset-x, $offset-y) + .details + :markdown + Returns the image and background position for use in a single shorthand property: + + $icons: sprite-map("icons/*.png"); // contains icons/new.png among others. + background: sprite($icons, new) no-repeat; + + Becomes: + + background: url('/images/icons.png?12345678') 0 -24px no-repeat; + +#sprite-map-name.helper + %h3 + %a(href="#sprite-map-name") + sprite-map-name($map) + .details + :markdown + Returns the name of a sprite map + The name is derived from the folder than contains the sprites. + +#sprite-file.helper + %h3 + %a(href="#sprite-file") + sprite-file($map, $sprite) + .details + :markdown + Returns the relative path (from the images directory) to the original file + used when construction the sprite. This is suitable for passing to the + `image-width` and `image-height` helpers. + +#sprite-url.helper + %h3 + %a(href="#sprite-url") + sprite-url($map) + .details + :markdown + Returns a url to the sprite image. + +#sprite-position.helper + %h3 + %a(href="#sprite-position") + sprite-position($map, $sprite, $offset-x, $offset-y) + .details + :markdown + Returns the position for the original image in the sprite. + This is suitable for use as a value to background-position: + + $icons: sprite-map("icons/*.png"); + background-position: sprite-position($icons, new); + + Might generate something like: + + background-position: 0 -34px; + + You can adjust the background relative to this position by passing values for + `$offset-x` and `$offset-y`: + + $icons: sprite-map("icons/*.png"); + background-position: sprite-position($icons, new, 3px, -2px); + + Would change the above output to: + + background-position: 3px -36px; diff --git a/doc-src/content/reference/compass/utilities/sprites/base.haml b/doc-src/content/reference/compass/utilities/sprites/base.haml new file mode 100644 index 00000000..5fec97e9 --- /dev/null +++ b/doc-src/content/reference/compass/utilities/sprites/base.haml @@ -0,0 +1,18 @@ +--- +title: Compass Sprite Base +crumb: Sprite Base +framework: compass +stylesheet: compass/utilities/sprites/_base.scss +layout: core +nav_stylesheet: compass/_utilities.scss +classnames: + - reference + - core + - utilities +--- +- render 'reference' do + :markdown + These mixins are useful for working with sprites. This file is imported by + magic sprite imports. + + See the [Spriting Tutorial](/help/tutorials/spriting/) for more information.