Image Renditions


Image renditions are new to SharePoint 2013 publishing sites, and allow you to customise the appearance of an image and save that customisation as a template. You can upload a large photo to your SharePoint image library and ensure that it is always a given size on a given page, display template, search result etc. The best reason to use renditions is instead of using CSS where a 4mb image after it is resized, it is still a 4mb in size. Using renditions SharePoint will resize your image and create a new file, therefore your 4mb 1680×1050 resized to 100×62 could end up being 22kb, which is a lot better for a web image.

Update: To get Image Renditions to work you must turn on BLOB cache feature. For more information on how to configure BLOB cach, refer to http://technet.microsoft.com/en-us/library/cc770229.aspx

The point and click way.

  1. On your site, goto site settings.
  2. Under Look and Feel click on Image Renditions.
  3. The page you will be taken to will probably have a few renditions on the page. As you can see from my screen shot, they have an ID, Name, Width and Height. When you upload a picture to the image library, SharePoint will create 4 images, one for each rendition. If there is a Width but no Height, SharePoint will ratio the height to the given width.
  4. Click Add new item, fill in the Name, Width (optional), and Height (optional) then click Save.

The coding way.

Using an XML file and an elements file you can code the image rendition. Before showing you how to do this, I’ll show you where the file needs to be uploaded too. From Site Settings under Web Designer Galleries click on Master pages and page layouts. In the Master Page Gallery you will see a PublishingImageRenditions.xml file. Download a copy of this file, we will use this as a base template for our demo.

  1. Open up Visual Studio and create a new SharePoint 2013 empty project (Sandbox, as this will work for SharePoint online too)
  2. Right click the project and add new item. Select Module and give it a name. (I’ve called mine MO_ImageRendition)
  3. Rename the Sample.txt to PublishingImageRenditions.xml and paste in the content from the downloaded PublishingImageRenditions.xml from earlier. Or replace the file with the downloaded file. Whatever is easier for you.
  4. To add a new Rendition, change the NextId to the next number up. Then add the following section after the last </ImageRendition> but before </Renditions>
    <ImageRendition>
    <Height>-1</Height>
    <Id>5</Id>
    <Name>CannonFodder Display Rendition</Name>
    <Version>1</Version>
    <Width>150</Width>
    </ImageRendition>
    

    Above I have put -1 for height. This means I don’t want a given height, I want a ratio based on the Width. So it will take the original image ratio and calculate the height automatically based on the width being 150px. I have also given it a name of CannonFodder Display Rendition, which isn’t really meaningful. I recommend giving it a name for where you expect to us it. So for example you have a HomePage news rollup which will have an image of 150px x 150px the name could be HomePage News 150×150.

  5. In the Elements file, change the file line so that it says the following.
    <File Path=”MO_ImageRendition\PublishingImageRenditions.xml” Url=”_catalogs/masterpage/PublishingImageRenditions.xml” ReplaceContent=”TRUE” />
    
  6. Ensure your module is part of Feature1 and scoped at Site, Publish the project and create a WSP.
  7. Upload your solution to SharePoint, and activate your feature. Then head back to Image Renditions under Look and Feel.

See Image Renditions in action

If you go to your publishing Images and upload a picture. After the picture has been uploaded, click on the 3 ellipse and click on Edit Renditions.

From using Chrome Network, I’m able to see the size of each image on this page. The original image is 53Kb 610px x 469px, as you can see each Rendition is a different file size. Rendition 3, which is Display Template Large Picture is 468×220 at 16.8kb.

Here in the Edit Renditions you can edit the image of each rendition, if you want. For example if you think that SharePoint has trimmed the image and remove the most important part of the image, you can move the trimmed area to include the bit you think that should be showing. Unfortunately, I am unsure how to do this in code at the moment.

Using Image Rendition with point and click.

I have a publishing page and I’m using the out the box page layout Article Page – Image on the Left. I’ve clicked to insert an image and it’s brought up the Edit Image Properties dialog box. Once I have selected the picture, under Selected Images there is Image Rendition.

Below I have selected Display Template Large Picture. You can see here why the naming is important.

Using Image Rendition in your code

To use an image rendition all you need to do is in the src of your image tag include ?RenditionId= with the number of the Rendition. Ideally you could create a knockout webpart, or use the rendition in a display template for a search query web part. Below I’m just adding a Script Editor to a page and adding the following line of code:

<h3>My Image using Rendition ID 5</h3>
<img alt="picture" src="/sites/OTBPUB/PublishingImages/cl01cloudgate.jpg?RenditionID=5" />

Couple of gotchas with Renditions and Search

I have been playing about with Renditions and Search for a couple of weeks now, and they have tripped me up a couple of times. Here is what I have learnt.

  1. When you use a rendition for example on a publishing page, so that the article image is always the same size no matter what size the user uploads, the search picks up the Rendition string as well. So in display templates for search query webparts, you need to check the src of the picture and possible strip out the Rendition ID and then replace with the Rendition ID you want to use for the display template.

    In my display template my JavaScript code look like the following

    var pictureURL = $getItemValue(ctx, "Picture URL");
    pictureURL.overrideValueRenderer($urlHtmlEncode);
    
    //get the Src of the picture
    var pictureSrc = pictureURL.inputValue.match(/src="([^\s]+)"/i)[1];
    if (pictureSrc.toLowerCase().indexOf("renditionid") >= 0) {
         pictureSrc = pictureSrc.replace(/RenditionID=\d/i, "RenditionID=" + renditionID)
    } else {
         pictureSrc = pictureSrc + "?RenditionID=" + renditionID;
    }
    
  2. The rendition file PublishingImageRenditions.xml needs to be where the picture is being pulled from, not where the picture is being displayed.

Hopefully you can see Image Rendition is a great addition to SharePoint.

Advertisements