Some reference material in the original sprite JIRA:

http://jira.icefaces.org/browse/ICE-1896

I played with every option and annotation of the SmartSprites tool and analyzed its source code. This is what I found...

• After running the tool on a CSS file (or files) and source images, SmartSprites generates one or more sprite images (depending on how many we specified in the CSS file(s)) and an augmented CSS file (suffixed with "-sprite", or with another specified suffix) per input CSS file, containing the offsets of all the source images in the generated sprite image(s) plus some other adjustments, and also removes all SmartSprites annotations.

• The current available options and annotations give us great flexibility for every possible scenario.
• It is possible to generate different sprite images from the same CSS file (for example, if we want to include an image that repeat on the x-axis and another one that repeats on the y-axis, we will have to use separate sprite images, since the browser would display any contents of the actual image file after the specified offset).
• It is also possible to generate only one sprite image from two or more CSS files, as long as we refer to the same sprite id in the annotations.
• It is possible to specify exactly which CSS files we want to process or instruct SmartSprites to process all CSS files under certain root directory.
• We can also specify an output directory for all the generated sprite images and CSS files.
• We can supply a custom suffix for the generated CSS files' names.

• So, it is not necessary to modify the source code, since it already does all we need it to do. However, if at some point, we find the need to modify the source code, it would be relatively easy. The code has a very good and simple design that makes sense to me. Every source file is thoroughly commented. I've already identified the methods in the API that we can use if we want to programmatically supply the input parameters from our own java code, or if we want to access the offsets and other data of the source images in the resulting sprite image.

• Other nice features are that it can handle some problems with IE6, there's an Ant task to use this tool, and it prints to the console detailed messages and warnings of the whole process.

I think we can proceed in the following ways:

• We could simply create a separate tool that generates a CSS file with all the required annotations and image locations. This CSS file would serve as input for SmartSprites.

For example, for a component based on YUI2, this CSS file would include:

• The core yui CSS (as explained in the previous message).
• All the skin-related CSS rules signatures.
• These rules would be empty except for those rules that contain image locations. We would include these locations and maybe some other positioning rules.
• Annotations for SmartSprites.
• Additional comments indicating what aspect of the presentation each rule controls and how each image is meant to be used.

• The above suggests that we should not only offer this tool as a sprite image generator, but as an entire skinning tool, since it's very likely that ICEfaces users would also want to add their custom styles to match the images, and it would be easier to simply follow the existing CSS pattern/approach.

• Another approach would be to modify the SmartSprites source code so that it runs as a single tool. Personally, I think that it would be better to follow the UNIX philosophy and create separate tools that do only one thing and do it well. Besides, it would be easier to upgrade to new versions of SmartSprites if we keep them separate.

• As for how to supply the input to our tool, one approach would be to look in a specified directory for specific image file names, defined by convention, that the ICEfaces user wants to include in the new skin, or probably we could use XML input files with all the configuration.

• In reality, it is not really necessary to create a separate tool to create an input CSS file for SmartSprites. We could simply provide, for each component, a prototype of a skin in a subdirectory that includes a CSS file like the one mentioned above and the source images. The user can simply copy this directory, rename it, and modify anything they want. Then, our build script can invoke SmartSprites.

• For example, the general approach to modify a particular aspect of the YUI "sam" skin would be to "unsprite" the skin and provide all the source images in this directory along with the base CSS file. Then, a user can simply replace one of the images, and maybe add a few styles. Then, in production, the "sam" skin would be normally included in the page, and the generated CSS file would have to be loaded after the "sam" skin so that it overrides whatever the user wanted to override.

• We can still create a tool for internal use that generates these CSS files based on some metadata.

Let's proceed as you've described below:

• In reality, it is not really necessary to create a separate tool to create an input CSS file for SmartSprites. We could simply provide, for each component, a prototype of a skin in a subdirectory that includes a CSS file like the one mentioned above and the source images. The user can simply copy this directory, rename it, and modify anything they want. Then, our build script can invoke SmartSprites.

• For example, the general approach to modify a particular aspect of the YUI "sam" skin would be to "unsprite" the skin and provide all the source images in this directory along with the base CSS file. Then, a user can simply replace one of the images, and maybe add a few styles. Then, in production, the "sam" skin would be normally included in the page, and the generated CSS file would have to be loaded after the "sam" skin so that it overrides whatever the user wanted to override.

Please take the Slider and then the Calendar, and "de-sprite" their images from the existing YUI Sam theme, and then use the SmartSprites tool to generate a new sprite image for each component, that also incorporates the custom images that may have been added for these components by Adnan/Yip.

This will give us a real-world example to evaluate further.

attached a demo for the calendar component

Attached demo2.

There is a problem with slider and potentially with any yui3 component. YUI3 will automatically download the slider js files, any other dependencies, and CSS files whenever the 'slider' module is loaded. This is done in the client side, after the page has been loaded, so all these styles will come after the ones that appear in the HTML document that was sent from the server. So this is not allowing us to override the styles we wanted to override.

It is possible to load all dependencies manually, so that they don't get loaded dynamically on the client side. I tried it but ran into some JS errors, so right now the slider demo doesn't work.

attached source files: annotated css files and images for SmartSprites

Commited SmartSprites integration into the Sparkle build tool at revision 21372...

Typing 'ant sprites' creates sprites only. The task is also performed by default.

Source CSS and image files go under org.icefaces.component.sprites, where each subdirectory represents a skin.
Output files are written to org.icefaces.component.sprites/out, while keeping the same directory hierarchy.

Hi Art,

I came across an issue with the URL format in SmartSprites-generated CSS. See if you have a better workaround.

Input:
background-image: url(cal_arrow_left.gif); /** sprite-ref: rime-sprite-x; */
Output:
background-image: url('../sprite-x.png');

The problem is that our framework can't use the url format '../sprite-x.png'; we have been doing something like: 'images/cal_arrow_left.gif.jsf?ln=org.icefaces.component.selectinputdate'

So my workaround is:

Input:
background-image: url(cal_arrow_left.gif); /** sprite-ref: rime-sprite-x; */
background-image: url(../sprite-x.png.jsf?ln=org.icefaces.component.sprites);
Output:
background-image: url('../sprite-x.png');
background-image: url(../sprite-x.png.jsf?ln=org.icefaces.component.sprites);
i.e. I had to add an extra background-image property to override the annotated background-image property.

This is rather clumsy. Is there a cleaner way to do it?

Thanks.
Yip

Ideally, we don't want the component author to need to reference artifacts generated by SmartSprite directly, those should just be produced by the generation step.

Art says:

Alright, I committed the smarter ant task to revision 21477.

Here are some details:

• All skins were directly under resources\org.icefaces.component.sprites. Now, they are under resources\org.icefaces.component.sprites\src. I think this should answer Ken's question. There shouldn't be any problems with this change. In production, all components would still access the CSS and image files generated under resources\org.icefaces.component.sprites\out. I made sure all moved files preserved their version history.
• The way a change in a source file is detected is by keeping a file named 'cache.properties' with information about the last modified times of all files under resources\org.icefaces.component.sprites\src. This is done by ant. This file is automatically generated and checked by ant everytime the task is invoked.
• If this file is missing, then the sprites will be rebuilt. If this file is not missing and there are no changes detected, then the sprites won't be rebuilt.
• When calling 'ant clean', the generated sprite files will only be deleted if 'cache.properties' is not present. This is just mirroring the behavior of not rebuilding if it's not necessary (if we deleted the generated sprites every time, then they wouldn't be rebuilt if no changes are detected, and the jar wouldn't contain these resources).
• I added a 'sprites-reset' task that deletes 'cache-poperties' and generated sprites files under resources\org.icefaces.component.sprites\out, in order to force re-generation next time the project is built.

I will add this documentation to the wiki. Let me know if you have any comments or concerns.

A couple of requests/changes:

• All skins were directly under resources\org.icefaces.component.sprites. Now, they are under resources\org.icefaces.component.sprites\src. I think this should answer Ken's question. There shouldn't be any problems with this change. In production, all components would still access the CSS and image files generated under resources\org.icefaces.component.sprites\out.

This is a large concern in general in that we don't want to force all the components to manage their resources in a common directory like this. As an alternative, would it be possible to have each component include their own resources in a "well-known" location (configurable in the build somehow) instead, and have the build copy all the images to a staging directory for generation into a sprite image? So for example, use the following structure in svn:

sparkle/component/slider/src/org/icefaces/component/slider
sparkle/component/slider/resources/org.icefaces.component.slider

We would also like the ability to somehow specify a specific set of components to include in a sprite image, as well as the current / default behavior of all the components under the build dir. The idea is to be able to support 3rd party component development using the same build system, etc.

Also, I don't see how you are distinguishing between image resources that should be x-axis repeated, y-axis , or neither. Is this automatically determined from the CSS?

• When calling 'ant clean', the generated sprite files will only be deleted if 'cache.properties' is not present.

We would like 'ant clean' to remove the cache.properties file also to ensure that clean is clean in all cases.

> This is a large concern in general in that we don't want to force all the components to manage their
> resources in a common directory like this. As an alternative, would it be possible to have each
> component include their own resources in a "well-known" location (configurable in the build
> somehow) instead, and have the build copy all the images to a staging directory for generation
> into a sprite image? So for example, use the following structure in svn:
>
> sparkle/component/slider/src/org/icefaces/component/slider
> sparkle/component/slider/resources/org.icefaces.component.slider

I don't understand this point very well. Maybe I didn't explain myself clearly in the first place. It is not the case that all source files (images, css) for all components, for all skins, are inside the same directory without any order or structure. The old structure was preserved: one subdirectory for each skin, and, inside this directory, each component has its own directory. All what was done was to move all these skin subdirectories inside the '/src' directory so that ant had a single starting point to check for changes under that directory, recursively.

Having sprite source files scattered in different locations would be more difficult for both, ant and smartsprites, to locate them, check for changes, etc.

I wonder if this clarifies the concern or if a different structure is preferred.

> We would also like the ability to somehow specify a specific set of components to include in a
> sprite image, as well as the current / default behavior of all the components under the build dir.
> The idea is to be able to support 3rd party component development using the same build system, etc.

This is possible to do with smartsprites, but it would be very tricky to try to apply the "smarter" build task (i.e. rebuild only when there are changes) to it since there would be just too many possible combinations of components. We could provide this as a separate utility task that takes the names of the components to include as parameters, and then, following directory conventions, locates all the necessary resources to build the sprites.

> Also, I don't see how you are distinguishing between image resources that should be x-axis
> repeated, y-axis , or neither. Is this automatically determined from the CSS?

The CSS file under the '/base' subdirectory defines these three different sprite images (sprite, sprite-x, and sprite-y). Then, all other CSS files in the component subdirectories reference these sprite images by their id's in order to include images in them.

> We would like 'ant clean' to remove the cache.properties file also to ensure that clean is clean in all cases.

Alright, no problem.

Important changes starting from revision 21672.

• All source images and CSS files were moved from resources\org.icefaces.component.sprites\src to '\sprites' subdirectories inside the main source directory for each component (e.g. 'src\org\icefaces\component\selectinputdate\sprites')
• All generated files are now written to 'resources\org.icefaces.component.sprites' instead of 'resources\org.icefaces.component.sprites\out' (i.e. the 'out' part was removed), so you might need to do some modifications to your component source files to use the new path.
• For new skins, it is no longer necessary to create a new base.css file and to use different sprite reference id's (e.g. 'rime-sprite-x'). You simply use the same id's for any skin (i.e. 'sprite', 'sprite-x', and 'sprite-y').
• In order to include source images and css into the sprite generation, it is necessary to declare them in the build script. This is done within the 'sprites' task, adding a line like the following:
  <includeresources dir="src\org\icefaces\component\selectinputdate\sprites" name="calendar" skin="sam" />
• If you add a completely new skin, you will also have to declare it like this:
  <generatesprites skin="rime" />