The goal of this tutorial is to explain how to set up Jawr to generate sprites for CSS images using smartsprites.
This feature is available since the version 3.2 of Jawr.
Smartsprites allows the user to create sprites for CSS images from annotations in the CSS files.
The reference documentation for smartsprites, containing the different annotations can be found on the smartsprites project site.
It is important to note that the sprite generation feature works only in production mode.
Jawr will not generate the referenced image sprites in the CSS files if you are in debug mode.
Jawr requires at least the version 0.2.5 of smartsprites for the sprite generation feature.
Smartsprites is a tool, which helps the developer to generate sprites from special annotations in the CSS files. When the user enables the sprite generation feature, Jawr will first let smartsprites process all the CSS files available in the CSS bundles to generate the CSS sprites, and then it will process the CSS files to generate the bundles.
Please check the quickstart tutorial for the instruction about Jawr installation in your project.
Then add the dependency to smartsprites in your project.
If you don’t use maven, you can find smartsprites jar and the libraries associated in the package file available in the download section of smartsprites site. From there, download the version 0.2.5 or greater. In the zip file, you will find in the lib folder the smartsprites jar and the jars used by smartsprites.
If you’re using maven, you must add in your dependencies, the following section :
<dependency>
<groupId>com.carrotsearch</groupId>
<artifactId>smartsprites</artifactId>
<version>0.2.12</version>
</dependency>
You must configure Jawr to use the CSS and the image servlets.
Please check the tutorial on how to setup jawr to serve images.
Jawr uses a global preprocessor to generate the CSS sprites. To enable the sprite generation feature, you need to add the following property in your configuration file:
jawr.css.bundle.factory.global.preprocessors=smartsprites
With this property set, when you start your application in production mode, jawr will generate the image sprite, and these image sprites will be referenced in the bundles.
Create an /img directory at the root of your web application and copy 2 png images in it, and rename them as img1.png and img2.png.
Create an /css directory at the root of your web application and write a test CSS file named test.css and add the following content:
/** sprite: mysprite; sprite-image: url('../img/mysprite.png'); sprite-layout: vertical */
.style1 {
background-image: url("../img/img1.png"); /** sprite-ref: mysprite; */
background-repeat: no-repeat;
}
.style2 {
background-repeat: no-repeat;
background-image: url("../img/img2.png"); /** sprite-ref: mysprite; */
}
Sprite declaration:
/** sprite: mysprite; sprite-image: url('../img/mysprite.png'); sprite-layout: vertical */
This first line defines a new sprite named mysprite, whose the URL will be /img/mysprite.png. you must note that in this example the sprite URL is given relatively to the CSS sprite in which it’s declared.
The argument sprite-layout: vertical defines that we use a sprite with a vertical layout. So all the image will be appended vertically.
Sprite reference:
background-image: url("../img/img1.png"); /** sprite-ref: mysprite; */
Here we define that the image /img/img1.png belongs to the sprite mysprite.
Please check the smartsprites documentation for more information about the available directives
Write a test JSP page, which has a reference to a bundle containing test.css and add the following content:
<%@ taglib uri="http://jawr.net/tags" prefix="jwr" %>
<%@ page contentType="text/html;charset=UTF-8" %>
<html>
<head>
<!-- Reference to a bundle containing test.css -->
...
</head>
<body>
...
<div class="style1">div content</div>
<div class="style2">div content</div>
</body>
</html>
Deploy your application to a server and open the JSP you created. Check the content of the CSS bundle which contains test.css, you must find references to a new “../img/mysprite.png”, where you had before references to img1.png and img2.png.
You can define sprites in a CSS created by a generator. But there is one constraint, which is that you need to define the sprite URL with a sprite prefix, and the URL must be absolute. Don’t use relative path like ‘sprite:../../mysprite.png’.
For generated CSS, the smartsprites directive must looks like
/** sprite: mysprite; sprite-image: url('sprite:/img/mysprite.png'); sprite-layout: vertical */
...
...
It’s possible that the design of your page may be altered after the use of sprite generation. This is an issue which can happen while using smartsprites. Please check the FAQ section of smartsprites for more information.