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 and manage their update process.

Managing image tags

Each image resource uploaded to the cloud has a unique Public ID (assigned by you or randomly generated). You can assign one or more tags for each uploaded image.

Tags are used for generating sprites. If, for example, you uploaded dynamic images of logos to your site, you should give them the tag 'logo' for easily generating a sprite that contains all of them.

You can assign tags to resources while uploading them. See Tagging Images for more details.

You can manage tag assignments using our Management Console and you can also use our Tags API for adding and removing tags of resources. If you're using our client libraries, managing tags is very easy. See Ruby On Rails integration for details. You can also easily do it by yourself:

Managing tags is done by sending an HTTP POST request to:

For example, if your cloud name is 'demo', the POST request should be sent to:

Parameters:

• tag - The tag name to assign or remove.
• public_ids - A list of Public IDs of images uploaded to Cloudinary.
• command - The action to perform on image resources using the given tag. Supported values:
  • add - Assign the given tag to the resources with the given Public IDs.
  • remove - Remove the given tag from the resources with the given Public IDs.
  • replace - Assign the given tag to the resources with the given Public IDs while clearing all other tags assigned to these resources.
• api_key - Your unique Cloudinary API Key.
• timestamp - Unix time in seconds of the current time.
• signature - A signature of all request parameters, based on your Cloudinary API Secret. See Request Authentication 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:

http://res.cloudinary.com/demo/image/sprite/logo.png

275x459 PNG

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('http://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 Request Authentication for more details.

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

{
  css_url: 'http://res.cloudinary.com/demo/image/sprite/v1315740225/logo.css',
  image_url: 'http://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="http://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:

http://res.cloudinary.com/demo/image/sprite/w_150,h_60,c_fit/logo.png

150x202 PNG

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('http://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"/>