ACE Sprite Image Generation

Sprite Image Generation

Contents:

• SmartSprites Tool
• Sprite Generation Approach in ICEfaces

SmartSprites Tool

This section describes the basics of the SmartSprites tool per se and not how it is integrated into ICEfaces.

Introduction

SmartSprites is an open-source tool, written in Java, that generates sprite images based on individual source images and annotated CSS files. It is advanced enough to handle repeating background images and other issues.

Annotating a CSS file for SmartSprites

A CSS file meant to be processed by SmartSprites must have some special annotations and conventions. These are the four main requirements:

1. Annotations consist of CSS comments, similar to JavaDoc comments, containing semi-colon delimited entries, which are key/value pairs which are themselves colon delimited.
2. A sprite image declaration at the beginning of the file, specifying its identifier.
3. Use of the 'background-image' CSS property to indicate source image locations (Do not use the more general 'background' property).
4. An annotation next to the 'background-image' property to associate it with a declared sprite image.

The next example illustrates the basic usage.

/** sprite: mysprite; sprite-image: url('../out/mysprite.png'); sprite-layout: vertical */

#header-box {
   background-image: url(logo.gif); /** sprite-ref: mysprite; */
}

In the declaration, the 'sprite' property specifies an identifier to be used within the file. The 'sprite-image' property specifies the location and format of the output image. The 'sprite-layout' property specifies whether the source images are to be placed below the previous ones (vertical) or just after them at the same height (horizontal).

The 'background-image' property specifies a location of a source image, relative to the location of this CSS file.

The 'sprite-ref' annotation next to 'background-image' associates this source image with a declared sprite image to be included in it.

There can be more than one declarations in a single CSS file, resulting in the same number of output sprite images. Also, source images can be included in sprites declared in another CSS file as long as they use the correct identifier and both CSS files are processed in the same invocation of SmartSprites.

The next example illustrates how to declare an image to be repeat along the x-axis.

#main-box {
   background-image: url(tile.gif); /** sprite-ref: mysprite; sprite-alignment: repeat; */
   background-repeat: repeat-x;
}

This will make SmartSprites to repeat the source image throughout the entire width of the output image, so that web browsers do not display blank space. If there is more than one image repeating along the x-axis in the same sprite, then the width of the output image will be the common denominator of the widths of all repeating images along the x-axis. Thus, web browsers will always show complete repetitions of the images.

For images repeating along the y-axis, the value of the 'sprite-alignment' annotation must be the same, just 'repeat'. However, the referenced sprite must have a horizontal layout. Furthermore, it is not possible to include images repeating along the x-axis and images repeating along the y-axis in the same sprite image. Separate sprite images for each type of repetition must be created. This implies that any image meant to be repeated along both axes cannot be included in a sprite.

The following table specifies the type of layout needed for the different types of image repetition.

 Along the x axis -> Vertical layout
 Along the y axis -> Horizontal layout
 Over both axes -> Not to be included in sprite

Basic Command Syntax

Once the CSS files are correctly annotated and the source images are in the right locations, it's time to run SmartSprites from the command line. There are a few ways to run SmartSprites. The easiest and most convenient way is by using the '--root-dir-path' parameter. Here is an example:

 > smartsprites --root-dir-path C:\css\sprites

SmartSprites takes the directory specified and searches for CSS files to process in that directory and all subdirectories. SmartSprites outputs one CSS file for every source CSS file. This output file has the same name of the source CSS file plus a suffix (default is '-sprite'). This file is created in the same directory as the source CSS file. Also, All image locations specified in CSS files are relative to the CSS file location, as one would expect.

It is also possible to specify a different output directory. If this directory does not exist, it will be created. This directory will keep the same structure as the root directory. Here is an example:

 > smartsprites --root-dir-path C:\css\sprites --output-dir-path C:\css\out

References

More information can be found at the SmartSprites web site: http://csssprites.org/

Sprite Generation Approach in ICEfaces

This section explains how SmartSprites is used in the ICEfaces build system to generate sprite images. It also mentions the conventions used in this approach.

Introduction

ICEfaces uses the SmartSprites tool to generate sprite images for its components. It is also possible to easily extend these sprite images for additional components or even as stand alone styling not related with a particular component. In order to understand how to extend these sprites, it is necessary to know some annotation, naming and directory conventions.

Annotation conventions

First of all, all CSS files meant to be integrated into the sprite generation utility must be correctly annotated, as described above. However, in the ICEfaces approach there are two important points to keep in mind for these CSS files:

• It is not necessary to make new sprite declarations in the file.
• The sprite references to be used should be either 'sprite' (for non-repeating images), 'sprite-x' (for images repeating along the x-axis) or 'sprite-y' (for images repeating along the y-axis).

While it is still possible to declare new sprites, there is no need to do so. The three sprite references in use cover all cases. These declarations are included in a file called 'base.css', which is added at build time to every skin. A typical CSS file would look like this:

 #container {
	background-image: url(background.png); /** sprite-ref: sprite-x; sprite-alignment: repeat; */
	background-repeat: repeat-x;
}

Note that if an image is meant to be repeated over both x and y axes, then it shouldn't be incorporated into a sprite. It should simply stand alone and be placed somewhere in the directory of the skin it belongs to, or directly under the /resources directory if it's not related to a skin in particular.

Naming and directory conventions

Since many different skins can be supported, all the source image and CSS files related to a particular skin, for a particular component, should be inside the same directory, which should have the name of the skin, by convention.

Moreover, it is recommended, but not necessary, that all skin directories for a particular component be inside the same directory. At the time of this writing, ICEfaces Advanced Components have a subdirectory named 'skins' which contains all their skins.

The following figure illustrates the recommended directory hierarchy.

src/org/icefaces/component/my_component
                            |
                            +-- /skins
                            |     |
                            |     +-- /sam
                            |     |     |
                            |     |     +-- mycomponent.css
                            |     |     |
                            |     |     +-- icon.png
                            |     |
                            |     +-- /rime
                            |           |
                            |           +-- mycomponent.css
                            |           |
                            |           +-- icon.png
                            |
                            +-- MyComponent.java
                            |
                            +-- MyComponentMeta.java
                            |
                            +-- MyComponentRenderer.java

How to include source images and CSS files into the generated sprites

Once the source images and CSS files are placed in the correct locations, it is necessary to declare them in the component build script. Inside the 'skins' target, each set of files should be included by adding a line like the following:

 <includeresources dir="path/to/skin/directory" name="component_name" skin="skin_name" />

The 'dir' attribute specifies the directory that contains the resources to be added. The 'name' directory specifies the output name of the directory that will contain the parsed CSS files within a skin directory. This name is usually the name of the component, but it can be anything. The 'skin' attribute specifies the name of the skin these resources are part of. This same name will be used as the name of the output directory that will contain all images and parsed CSS files for a the skin. A concrete example of this declaration would be the following:

 <includeresources dir="src/org/icefaces/component/selectinputdate/skins/sam" name="calendar" skin="sam" />

If a completely new skin is added, it will also be necessary to add a line like the following, at the end of the 'sprites' task:

 <generatesprites skin="skin_name" />

 resources/org.icefaces.component.skins
            |
            +-- /rime
            |     |
            |     +-- /calendar
            |     |     |
            |     |     +-- calendar.css
            |     |
            |     +-- sprite-x.png
            |
            +-- /sam
                  |
                  +-- /calendar
                  |     |
                  |     +-- calendar.css
                  |
                  +-- sprite-x.png

Image duplication

Sometimes two or more different components might use the exact same image file for similar or different purposes. One might think that, for performance reasons, that file should be included for only one component and have the other component access it as well. It is actually recommended to do the opposite: to include a copy of the same file for each component. The motivation of having separate image and CSS files for each component, even if those images and CSS are the same or similar, is to ease the job of overriding the appearance of specific components. For example, if an application developer only wants to change the appearance of checkbox buttons, they would only have to modify the checkbox button skin files. If all button types used the exact same image and CSS files, it would be more difficult to decouple and then customize them. Fortunately, SmartSprites is smart enough to detect duplicate images and only include them once in the final sprite image.