========================
Sprite Generation Recipe
========================

The p01.recipe.cdn:glue recipe offers a sprite generation script which is able
to generate sprite images based on image source folders.


glue
----

This recipe uses the glue library wher you can find on pypi:
http://pypi.python.org/pypi/glue


p01.recipe.cdn:glue
-------------------

Options
~~~~~~~

The 'glue' recipe accepts the following options:

eggs
  The names of one or more eggs, with their dependencies that should
  be included in the Python path of the generated scripts.
  Note; Pillow get additional added to this eggs if the pil option get not set
  to skip! For more information see pil option described below

source
  The source directory where the glue starts with. For more information see:
  http://glue.readthedocs.org/en/latest/quickstart.html

css_dir
  The css output directory where the glue starts with. For more information see:
  http://glue.readthedocs.org/en/latest/quickstart.html

img_dir
  The img source directory where the glue starts with. For more information see:
  http://glue.readthedocs.org/en/latest/quickstart.html

url
  The url prefix used in generated css or less file. For more information see:
  http://glue.readthedocs.org/en/latest/options.html

project
  if set to ``true`` glue will generate several sprite images based on
  the given folder structure. For more information see:
  http://glue.readthedocs.org/en/latest/options.html#project

html
  Using the html option, glue will also generate a test html per sprite using
  all the available CSS classes. This option is only useful for testing
  purposes. Glue generate the html file in the same directory as the CSS
  file.. For more information see:
  http://glue.readthedocs.org/en/latest/options.html

less
  less is a dynamic stylesheet language that extends CSS with dynamic behaviors.
  glue can also create .less files using less=true. This files contain
  exactly the same CSS code. This option only changes the file format.
  For more information see:
  http://glue.readthedocs.org/en/latest/options.html

pil (optional)
  the pil option can get set to ``pillow`` or ``skip``. If the pil option is
  set to ``pillow`` Pillow (PIL fork) get used. It the pil option is set to
  ``skip`` no additional PIL or PIL replacement get injected and you have to
  make sure your own eggs define PIL or a replacement. The glue library tries
  the following imports for import the PIL image and PNGImagePlugin;
  try:
      from PIL import Image as PImage
      from PIL import PngImagePlugin
  except ImportError:
      import Image as PImage
      PngImagePlugin

environment (optional)
  The environement if needed by your application code.

NOTE
  Any other ``glue`` option can get defined within the config file concept.
  for more information see: http://glue.readthedocs.org/en/latest/files.html

  You can define a relative path starting in your package development root
  location (normaly starting with src) e.g. src/my/package/css/source
  Or you can define a relative path prefixed with a package name wraped with
  brackets [] followed with an empty space and a relativ path to the source
  folder e.g. [my.pkg] images/foo


glue
----

Lets define some (bogus) eggs and sprite sources that we can use in our
buildout:

  >>> mkdir('demo')
  >>> write('demo', 'setup.py',
  ... '''
  ... from setuptools import setup
  ... setup(name = 'demo')
  ... ''')

  >>> mkdir('demo', 'images')
  >>> mkdir('demo', 'images', 'actions')
  >>> write('demo', 'images', 'actions', 'edit.png', "dummy")
  >>> write('demo', 'images', 'actions', 'delete.png', "dummy")
  >>> mkdir('demo', 'images', 'icons')
  >>> write('demo', 'images', 'icons', 'smile.png', "dummy")
  >>> write('demo', 'images', 'icons', 'grin.png', "dummy")
  >>> write('demo', 'sprite.conf',
  ... '''
  ... [sprite]
  ... url=../img
  ... ''')
  >>> mkdir('demo', 'sprites')


We'll create a `buildout.cfg` file that defines our script:

  >>> write('buildout.cfg',
  ... '''
  ... [buildout]
  ... develop = demo
  ... parts = glue
  ...
  ... [glue]
  ... recipe = p01.recipe.cdn:glue
  ... eggs = demo
  ... source = demo/images
  ... css = demo/images
  ... img = demo/sprites
  ... project = true
  ... pil = pillow
  ...
  ... ''' % globals())

Now, Let's run the buildout and see what we get:

  >>> print system(join('bin', 'buildout')),
  Develop: '...demo'
  Installing glue.
  Generated script '...glue'.

The bin folder contains the new generated minify script:

  >>> ls('bin')
  -  buildout-script.py
  -  buildout.exe
  -  glue-script.py
  -  glue.exe

The sprites-script.py contains the sprite generation script code. This means
you can run the script if you need them witout to run buildout again. You only
need to generate the script again if you change your configuration:

  >>> cat('bin', 'glue-script.py')
  import sys
  sys.path[0:0] = [
      ...
      ]
  import os
  sys.argv[0] = os.path.abspath(sys.argv[0])
  import p01.recipe.cdn.sprites
  if __name__ == '__main__':
      sys.exit(p01.recipe.cdn.sprites.main(['/sample-buildout/demo/images', '/sample-buildout/demo/images', '/sample-buildout/demo/sprites', '', 'true', 'false', 'false']))
