Creating and Accessing Image Renditions

Often, when you have a photo gallery or other uses of a number of images, you need those images in more than one size. Typically, you'll want a thumbnail, and you may want other sizes as well. Each size is called a rendition.

Webvanta can automatically create multiple sizes for you when you upload images. Just check the box labeled "Create Renditions" in the file upload form (accessed via the Files page).

The sizes of the renditions that are generated are determined by a Global Setting. In most of our SmartThemes, the default setting is for a 120-pixel-wide rendition that maintains the aspect ratio of the original image.

You can change the size of the thumbnail, choose cropping options, and create multiple sizes, by setting the appropriate values in the Global Setting named "image.thumbnail.settings". The syntax for this is JSON, which you don't need to understand; just follow the examples below.

Specifying the Renditions to be Created

This is the default setting:

  [{"geometry": "c80x80", "alias": "square_thumb"}, {"geometry": "80x80", "alias": "thumb"}, {"geometry": "640x480>", "alias": "medium"}]

This setting creates two thumbnails, one cropped to be 80 pixels square, and the other scaled (but not cropped) to have a maximum dimension of 80 pixels. It also creates a 640 x 480 pixel "medium" rendition, if the original is larger than this; if the original is smaller, the medium rendition will be the same size as the original.

You can add as many sizes as you want, each within curly brackets, separated by commas.

For each size that you want to have created, you specify a name (the alias, e.g., "thumb") and the geometry specification. The names can be anything you want, and you can create as many renditions as you want.

Geometry Specifications

These are the options for the geometry specification:

General notes on geometry specifications:

• There must not be any spaces in the string.
• The image is never distorted. Unless using the crop option, the resulting image will have the same aspect ratio as the original.

Generating Renditions

The renditions are generated when you upload an image, unless you uncheck the box in the Processing Options section of the upload dialog labeled "Create Renditions".

If you want to regenerate the renditions for an image you have already uploaded (if you have changed the Config Setting that determines what renditions are generated, or didn't check "Create Renditions" when you first uploaded the image), select the file in the Files screen, click the EDIT button in the right-hand column, make sure Create Renditions is checked in the Processing Options section of the dialog, and click Update. (Note that you do not need to specify a file to upload, if you want to work with the already-uploaded file as the master.)

You can also regenerate the renditions for all the images in a folder by selecting the folder in the Files screen and clicking the REGEN button in the right-hand column. This will regenerate the renditions for all images in the selected folder, for which the "Create Renditions" checkbox is checked.

Accessing Renditions

When accessing the "master" image (the one you uploaded), you can use the filename directly:

  <img src="/filename.jpg" />

The best way to directly access a rendition is by creating a special source path. Simply prepend the path to the file with /rendition.rendition-name.

For example, suppose that you have an image named "product.jpg", it is in a folder called "images", and you want to access a rendition called "thumbnail". You can access it as follows:

<img src="/rendition.thumbnail/images/product.jpg">

You can also use a WebvantaScript asset tag to create the filename, but this is slower than the approach described above:

<img src="<w:asset name='filename.jpg' rendition='thumb' />" />

Notes on asset tag usage:

• Since there are nested quotes, you must use single and double quotes appropriately.
• For the name, you can use the filename with or without the extension, as long as it is unique.
• The rendition name must match the name of one of the renditions that was listed in the Config Setting when the renditions were generated.

Using Asset Iterators

You can also access all the assets with a given tag, which is often useful for generating slideshows and image galleries. The following example displays all of the thumbnails with the tag "cats", with each thumbnail linked to the full-size image:

  <w:assets tag='cats'>
    <w:each>
      <w:if_rendition name='thumb'>
        <a href="<w:path />"><img src="<w:path rendition='thumb' />"></a><br />
      </w:if_rendition>
    </w:each>
  </w:assets>

Note that this code also checks for the existence of the rendition via "if_rendition".

The "path" statement retrieves the relative URL for the requested image rendition.

Using Icons and Dedicated Files

In general, any place you can reference a file in WebvantaScript, you can specify a rendition. For example, if you are using the Icon field for a given item type, you can access the thumbnail rendition of the icon as follows:

<img src="<w:icon rendition="thumbnail" />">