Nikwus 0.5.4
Automatically sprite images in CSS files
License: BSD

Nikwus: Automated CSS Sprite Generation
=======================================

Nikwus is a tool to automatically create CSS sprites. It works by parsing a CSS
file and adding all the background images it can find to a sprite image.

The CSS is rewritten to use that generated image and all background positions
are written.

To make best use of Nikwus, some custom CSS rules will have to be added to the
CSS file.


Usage
-----

Nikwus is used as a library from existing Python code. The public method
``nikwus.sprite`` is provided and it takes three arguments:

- ``directory``: The image directory where the sprites are written to.
- ``cssfile``: The file name of the CSS file to process. The default sprite
  will have the same name as this file with the ``css`` extension changed to
  ``png``.
- ``outfile`` (optional): The file name where to write the converted CSS file
  to. If this is not provided, the original CSS file is overwritten.


Example::

    nikwus.sprite('img/icons/', 'css/main.css')


Custom Rules
------------

The following rules can be used in CSS files to change the behavior of Nikwus.

``-sprite-name``
~~~~~~~~~~~~~~~~

Multiple sprites can be generated by using ``-sprite-name``. Every image that
does not specify this will go into the default sprite.

Example::

    .icon.world {
        background: url(world.png) no-repeat;
        /* Put login-related icons into a separate sprite for fast loading */
        -sprite-name: login;
    }


``-sprite-selector``
~~~~~~~~~~~~~~~~~~~~

By default Nikwus will repeat the full background, including the sprite URL on
each CSS rule. By using a sprite selector this can be avoided and only the
background position will be set.

The selector can also be used for generating Retina versions, see the chapter
on Retina below.


Example::

    .icon {
        /* This becomes the container for the default sprite */
        -sprite-selector: default;
    }
    .login-icon {
        /* Login icons are put into a separate sprite, that will be configured
           on this CSS rule */
        -sprite-selector: login;
    }
    .icon.world {
        background: url(world.png) no-repeat;
        -sprite-name: login;
    }
    .icon.mars {
        background: url(mars.png) no-repeat;
        /* This does not have a ``-sprite-name``, so it goes into the default
           sprite */
    }


``-sprite``
~~~~~~~~~~~

Spriting can be turned off for individual CSS rules by using the ``-sprite: no``
declaration. ``.gif`` images are not included in a sprite by default as they are
often used for animated backgrounds. That can be changed by using
``-sprite: yes``.

Example::

    .logo {
        background: url(logo.png) no-repeat;
        -sprite: no;
    }
    .check {
        background: url(check.gif) no-repeat;
        -sprite: yes;
    }

``-sprite-autosize``
~~~~~~~~~~~~~~~~~~~~

By default Nikwus will write the width and height of the image into it's CSS
rule. This can be turned off with ``-sprite-autosize``.

The width and height are not written into the container if:

- it's exactly the same as specified in the sprite selector rule
- a width, height, or both have already been specified in this rule

Example::

    .icon.world {
        background: url(world.png) no-repeat;
        -sprite-autosize: no;
    }
    .icon.mars {
        /* Sizes won't be specified for this icon either, because it already
           has a width */
        background: url(mars.png) no-repeat;
        width: 10px;
    }


Retina Sprites
--------------

For mobile devices with higher pixel densities, it's recommended to create
different sprites to take advantage of that fact.

Nikwus supports this by specifying a special ``-sprite-selector``. Start by
changing the CSS to something like this::

    .icon {
        -sprite-selector: default;
    }
    .icon.world {
        background: url(world.png) no-repeat;
    }

    /* Retina Handling */
    @media only screen and (-webkit-min-device-pixel-ratio: 2) {
        .icon {
            -sprite-selector: default 2x;
        }
    }

Now for each image that is specified in the CSS, a separate retina version
needs to exist. In the example above ``world.png`` needs to be accompanied by
``world-2x.png`` image. That second version must be exactly double the size of
the original.

Nikwus will abort with an error if the ``2x`` version can't be found or if it is
not exactly double the size.


Support
-------

Niwkus was developped by `Patrice Neff <http://patrice.ch/>`_ for the use at
`Squirro <https://squirro.com/>`_. The project is
`hosted at GitHub <https://github.com/pneff/nikwus>`_.