CSS Sprites : New in 6.4

sugarcrmdevelopers —  January 31, 2012 — 1 Comment

1. What is CSS Sprites:

One of the new features of CSS used in 6.4 is CSS sprites. Sprites is a smart way of using CSS to boost web performance by reducing the number of http requests that browser makes to the server. The way it works is that we combine several small images in one big image called sprite sheet. So now instead of making request for each small image, there will be just one request to the server for the big image that consists of all other small images. This way our page loads faster than usual. We use CSS to display selected parts of the big image which is required at a given time.

Picture below shows the number of http requests made to server when sprites is not used:

Picture below shows number of http requests made to server when sprites is used:

2.How it is used in Sugar:
In cache/sprites directory every theme has three files: a css file – sprites.css, a meta file – sprites.meta.php and the sprite canvas image – sprite.png
I. css file defines position of each image in the big parent image, where each small image is identified by a sprite id which it got during the time of css file creation.
II. meta file i.e. sprites.meta.php  that contains a big array of key value pairs where key is the name of image and value is again an array that contains the id of the image, its height and width.
III. sprites.png is the big master image that contains all small images arranged based on their position given in meta file. Below is a small portion from sprite sheet used for default theme in Sugar 6.4

sprite sheet

When a particular small image is required to be displayed then css is used to show only those coordinates of the big image that contain the big image. A user can tell when sprites is used by inspecting an image element, it will not have img tags, it will have span tags. Where sprites is not used, image will have img tags.

3. How it is loaded and invoked :  
We load all sprites related data i.e. meta file, sprites css and the big sprite image in cache. Depending on which image needs to be shown, using css those coordinates are displayed from the big sprite image. Below are the technical details explaining how we have implemented this:
I. Class SugarSprites.php in include/SugarTheme is the class that defines sprites used in sugar and has functions that load Sprites meta data.

private function loadMetaHelper($dir, $file) {
if(file_exists(“cache/sprites/{$dir}/{$file}.meta.php”)) {
$sprites = array();
$GLOBALS[‘log’]->debug(“Sprites: Loading sprites metadata for $dir”);
foreach($sprites as $id => $meta) {
$this->sprites[$id] = $meta;

Function above checks if sprites meta file is present in cache/sprites directory and obtains details of each image in array $sprites.

II. SugarTheme.php instantiates SugarSprites and calls its various functions to load meta data and css in cache. There are functions like getCSS() and getSpriteMeta() where getCSS() loads sprite css files that are to be used application wide, theme specific etc to cache and getSpriteMeta() loads sprite meta files to cache.

To get a small image from big sprite image we have function getSprite($class, $attr, $title) in SugarTheme.php where it takes the class of the image (this is the id of the small image) and returns that small portion from the the image wrapped in span tag.

4. How you can disable sprites:
very simple, go to your config.php file, and there is a parameter named use_sprites, set it to false, by default it is set to true (if you have GD libraries installed).

5. Handling Upgrades:

modules/Administration/SugarSpriteBuilder.php has functions that do upgrades for Sprites. Function rebuildSprites() in modules/UpgradeWizard/uw_utils.php calls  createSprites() function from SugarSpriteBuilder.php to do the upgrade. While upgrade to 6.4 it creates sprites—-
a. First of all it checks if GD libraries are installed in user’s system.

b. Then getFileList() function  processes files (image files, that are to be added in big sprite canvas) in a directory and adds them to the sprites array—Themes, custom Themes

c. Function createSprites() creates namespace for sprites, sets the type to repeat or boxed then SpritePlacement.php arranges the images to create that big image.- function processSprites() in SpritesPlacement.php places those small images in big image.
function processSprites() {

foreach($this->spriteSrc as $id => $info) {

// dimensions
$x = $info[‘x’];
$y = $info[‘y’];

// update min surface
$this->minSurface += $x * $y;

// get coordinates where to add this sprite
if($coor = $this->addSprite($x, $y)) {
$this->spriteMatrix[$id] = $coor;
Then initSpriteImg() blends those images in sprite canvas image.
Then css and metadata is created by createSprites(), where css will have coordinates for each small image in the big sprite image and each small image has unique id and metadata file created is sprite.meta.php that has an array with key value pairs.

6. Repairing and Rebuilding Sprites:
– Admin can do this from the application interface by going to admin->Repair->Quick Repair and Rebuild
-How Sugar handles it:
There exists a tpl file in modules/Administration/templates/RebuildSprites.tpl. This files defines javascript function for rebuilding sprites css. The tpl file is used by modules/Administration/RebuildSprites.php

So everytime a new custom theme is added admin needs to do quick repair and rebuild in order sprite to be effective for the newly created theme.

7. Future Enhancements:

Algorithm for arranging small images in big sprite image based on coordinates needs to be optimized.

8. Benefits:

People that will get the most benefit from sprites are those who use sugar instances on low bandwidth link.

One response to CSS Sprites : New in 6.4


    Amazing article and features. Very interesting read. Thank you for sharing.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s