Programmatically creating thumbnails from full size images

Updated on 20-October-2016 at 10:16 AM

Business Catalyst End of life announcement - find out more details.

This system is designed with the functionality to automatically scale and display thumbnail images (smaller versions) of existing image files in your site. In this article, you'll learn how to add code to your pages and leverage this capability, so that you don't have to manually create smaller versions of the image files and upload them to the live site.

Adding code to generate a thumbnail image from an existing image in the site

1. Begin by accessing the source code for the page, by choose Site Manager > Pages and selecting the page from the list.

2. The Web Page Details page appears, and the page is displayed by default in the Design tab. Click the HTML tab to see the source code displayed.

or if you are using the new Redactor editor click this button:

3. Place your cursor at the location on the page where you want to insert a thumbnail image. Type the following code:

<img src="/folder_name/image_file_name.jpg?Action=thumbnail&Width=80&Height=80" />

In the example above, replace this part of the code:


With the actual path to your full size image file, like this example:


Also, update the two numeric values in the following part with the width and height of the thumbnail you want to display (in pixels):


For example, if you'd like the thumbnail image to be 70 pixels wide by 50 pixels high, update the values like this:


Setting the aspect ratio of the source image that is resized

If you want to preserve the aspect ratio for the larger image size (to prevent a squashed or squished looking thumbnail image), you can add an additional parameter, thumbnail, to the <img> tag, as shown in the example below:

<img src="/folder_name/image_file_name.jpg?Action=thumbnail&Width=80&Height=80&algorithm=fill_proportional" />

The algorithm parameter accepts the following three values:

  • proportional
  • fill
  • fill_proportional
  • proportional_noupscale

The default setting for the thumbnail generator is proportional; if you want this setting, you don't need to add the parameter.

Here's a description of the results of each value:

proportional: The thumbnail maintains the aspect ratio of the source image and uses the specified width or height of whichever side of the image file is proportionately bigger.

fill: The dimensions of the thumbnail are resized to fill the specified Width and Height settings as defined in the parameters; the aspect ratio of the original source image is not maintained.

fill_proportional: The dimensions of the thumbnail are resized to fill the specified Width and Height settings as defined in the parameters; the extra pixels from the top/bottom or left/right are cropped on whichever side of the image is proportionally larger, if needed, to maintain the aspect ratio of the original source image and ensure that the thumbnail does not look squashed or squished. If the desired thumbnail dimensions are larger than the source image dimensions then the image is not resized and transparent pixels are added around the image.

proportional_noupscale: maintains the original aspect ratio as the original (does not enlarge the image). If the specified size is larger than the original size extra "white space" is added to the image to maintain the proportions:

Setting the output format of the generated thumbnail image

You can set the output format of the generated image by appending the &Format= parameter.

For instance, to generate the thumbnail in .png format, this would be the thumbnail URL:

<img src="/folder_name/image_file_name.jpg?Action=thumbnail&Width=80&Height=80&Format=png" />

Accepted output parameters include png, jpg and gif.

Generating thumbnail images for Web Apps

Similar to the process of displaying thumbnail images on web pages and photo galleries, you can also generate thumbnail images programmatically for Web App image content. Simply add parameters to the image source tag as shown in the following example:

<img src="{tag_myimage_value}?Action=thumbnail&Width=80&Height=80" />

In the example above, the part {tag_myimage_value} is replaced with the path to the full sized image when the Web App is dynamically rendered by the browser.

The system uses the data of the full size image to automatically scale it to the height and width values (in pixels) that you specify in the parameters of the <img> tag.

Generating thumbnail images for products in an online store

Programmatically generated thumbnail images are also very useful when displaying product images in a catalog.

Here's an example of an image tag used to generate a thumbnail image of a larger product image:

<img src="{tag_largeimage_path}?Action=thumbnail&Width=50&Height=50" />

In the example above, {tag_largeimage} was originally our dynamic image tag. However, we appended _path to the tag. Doing so will output the path to the full sized image. The same method will work for {tag_smallimage}.