Skip to main content

Automatically sprite images in CSS files

Project description

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 for the use at Squirro. The project is hosted at GitHub.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Nikwus-0.5.4.zip (50.7 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page