Metadata-Version: 1.1
Name: Nikwus
Version: 0.5.3
Summary: Automatically sprite images in CSS files
Home-page: UNKNOWN
Author: Patrice Neff <mail@patrice.ch>
Author-email: UNKNOWN
License: BSD
Description: 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>`_.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
