Sprite generation

Overview

As explained in detail in Sprite generation, sprites are a great way to improve user experience by reducing network overhead and bypassing download limitations.

A sprite is a single image that contains many images you need display in your web application. The browser downloads only a single image and your CSS code directs the browser which part of the sprite to use for display each contained image.

Cloudinary can generate sprites for you based on all images with a specified tag.

You can assign one or more tags for each uploaded image. If, for example, you uploaded dynamic images of logos to your site, you could give them the tag 'logo' to easily generate a sprite that contains all of them.

You can assign tags to resources while uploading them, using our Management Console, or using the 'tags' API to add or remove tags on existing resources. See Tagging images and Tags API for more details.

Creating sprites

After you upload images and assign a tag to a group of images you want to merge into a sprite, you are ready to dynamically create a sprite.

You can do that lazily by pointing to a dynamic URL that generates the sprite on demand when accessed for the first time (limited to 100 images) or eagerly using a direct API call (limited to 500 images).

Accessing the sprite (or lazily creating it if it doesn't already exist) is done using a simple address URL.

For example, to our 'demo' account we uploaded 4 logos with the public IDs: amazon_logo, apple_logo, microsoft_logo and google_logo. We assigned the tag 'logo' to all of them. The following URL delivers the generated sprite:

As you can see, a single image with all 4 logos was created. In order to use the sprite in your HTML code, you need to use the generated CSS of the sprite:

.google_logo, .apple_logo, .microsoft_logo, .amazon_logo {
  background: 
    url('https://res.cloudinary.com/demo/image/sprite/v1315740225/logo.png') 
    no-repeat;
}      
.google_logo { background-position: 0px 0px; width: 275px; height: 95px; }
.apple_logo { background-position: 0px -97px; width: 206px; height: 250px; }
.microsoft_logo { background-position: 0px -349px; width: 216px; height: 70px; }
.amazon_logo { background-position: 0px -421px; width: 162px; height: 38px; }

The generated CSS and PNG files are automatically distributed through a CDN and smartly cached. Note that the sprite will be generated if it doesn't exist whether you access the '.png' URL or the '.css' URL.

As you can see, the CSS includes style class names for each of the 4 logos. The style class name is the Public ID of the uploaded image resource.

Displaying an image contained in the sprite is very easy. Just include the CSS in your page and use style class names. For example, displaying the logo of Amazon is done using the following HTML code:

<div class="amazon_logo"></div>

Managing sprite versions

You might want to regenerate sprites when your content changes. In the example above, you would want to regenerate the sprite when adding a fifth logo or when replacing one of the four logos with a better quality one.

In such cases you want your users to use the updated sprite right away after it is generated. However, the sprite resources are already cached on users' browsers and in the CDN. In order to allow immediate update of the sprite while still using high-performance cache and delivery techniques, version management is needed.

When a sprite is generated it is assigned a version, which is the time stamp of its creation. You should use this version for accessing the CSS of the sprite. This way, your users will always get the most updated sprite.

You can use our API for generating or re-generating a sprite when needed (new uploaded images of the relevant tag, updated images, tag assigning or removal, etc.). While using our client side libraries, version management of sprites is transparent to you. But you can also perform version management directly.

Eagerly generating sprites is done by sending an HTTP POST request to (replace 'demo' with your cloud name):

Parameters:

  • tag - The tag name assigned to images that we should merge into the sprite.
  • api_key - Your unique Cloudinary API Key.
  • transformation (Optional) - A transformation to run on all images before merging them into the sprite. See Sprite with transformations for more details.
  • timestamp - Unix time in seconds of the current time.
  • signature - A signature of all request parameters, based on your Cloudinary API Secret. See Creating API authentication signatures for more details.

The API call returns a JSON with the URLs for accessing generated sprite

{
  css_url: 'https://res.cloudinary.com/demo/image/sprite/v1315740225/logo.css',
  image_url: 'https://res.cloudinary.com/demo/image/sprite/v1315740225/logo.png',
  secure_css_url: 
    'https://res.cloudinary.com/demo/image/sprite/v1315740225/logo.css',
  public_id: 'logo',
  version: '1315740225',
}

To use the sprite in your HTML code, simply link to the generated CSS in your HTML page:

<link href="https://res.cloudinary.com/demo/image/sprite/v1315740225/logo.css" 
      media="screen" rel="stylesheet" type="text/css" />

Sprite with transformations

In the example above with the 4 logos, you probably noticed that each logo has a different size. If you want to display related images that share the same dimensions, you probably want to transform them before merging them into a single sprite.

You can provide transformation instructions while generating sprites (whether you are using the direct API for generating sprites or whether you access a dynamic URL of a sprite). Cloudinary will transform all images according to your instructions and generate a sprite with the transformed versions of the original images.

For example, the following URL will deliver a sprite with the 4 images marked with the 'logo' tag while transforming each to fit in a 150x60 shape:

If for example you are using our Ruby on Rails library, integrating the CSS of the sprite into your page is done using the following view helper method:
cl_sprite_tag("logo", :width => 150, :height => 60, :crop => :fit)

You might also need to prevent style class names collisions with the names already used or in your site (for other sprites or static content). You can easily prevent such collisions by adding a 'prefix' parameter:

The generated CSS includes adds 'home_thing_' as a prefix of all style class names:

.home_thing_google_logo, .home_thing_apple_logo, 
.home_thing_microsoft_logo, .home_thing_amazon_logo {
  background: 
    url('https://res.cloudinary.com/demo/image/sprite/p_home_thing_/v1315743843/logo.png') 
    no-repeat;
}
.home_thing_google_logo { 
    background-position: 0px 0px; width: 275px; height: 95px; 
}
.home_thing_apple_logo { 
    background-position: 0px -97px; width: 206px; height: 250px; 
}
.home_thing_microsoft_logo { 
    background-position: 0px -349px; width: 216px; height: 70px; 
}
.home_thing_amazon_logo { 
    background-position: 0px -421px; width: 162px; height: 38px; 
}

Displaying an image is now done in the following way:

<div class="home_thing_amazon_logo"/>