Custom Image Templates in Sitecore

This is a supplemental post to Sitecore – Captions in the Rich Text Editor and provides details about creating your own custom templates for holding images in the Media Library.

What am I trying to accomplish? I want to add a new field to the standard JPEG and Image templates to hold caption text about the image. That way I can add caption text to images in the Media Library and automatically display the caption with the image any time it appears on the site.

At first glance this is an easy task but it is definitely not as straightforward as expected. The first problem is that simply adding a new “Caption” field to the JPEG and Image templates is only a temporary solution because these templates will be reset when upgrading to a new version of Sitecore. So instead, as with any standard Sitecore template, it is recommended that you create new templates that inherit from the JPEG and Image templates.

Now that we have created new templates that inherit from the JPEG and Image templates, we have solved one problem but created another. We need all Media Library images to use the new custom templates we created (that have the additional “Caption” field) instead of the standard image templates. Usually this wouldn’t be a problem but the Media Library is set up to automatically add images using either the standard JPEG or Image template. So if you were to upload an image to the Media Library, there would be no “Caption” field since it is defined on our custom image templates.

Sitecore has us covered though because, like many cases, they have added a setting to the Web.config file that will make our life considerably easier. The “<mediaType>” settings control which templates are used when uploading images to the Media Library. So that means all we need to do is replace the path to the standard JPEG and Image templates with the path to our custom JPEG and Image templates. Of course, it is best practice to create your own custom config file to hold changes like this so you should create a config file in the “App_Config/Include” directory that holds the following settings.

<configuration xmlns:patch="">
        <mediaType name="Windows Bitmap image" extensions="bmp">
          <sharedTemplate>path/to/custom Image template</sharedTemplate>
        <mediaType name="GIF image" extensions="gif">
          <sharedTemplate>path/to/custom Image template</sharedTemplate>
        <mediaType name="PNG image" extensions="png">
          <sharedTemplate>path/to/custom Image template</sharedTemplate>
        <mediaType name="JPEG image" extensions="jpg, jpeg">
          <sharedTemplate>path/to/custom JPEG template</sharedTemplate>

At this point your newly uploaded images (jpeg, png, gif, bmp) should be created using the new templates and we will finally have the “Captions” field available to use! That’s a lot of effort for just one extra field but it is worth your time to ensure there is no heartache in the future.

It is important to note that the config change means that new Media Library images will be created with the new templates but pre-existing images will still be using the old templates. So the last step is a bit of house cleaning to make sure you change the images to make sure they are now up to date using the new template. Don’t forget that Sitecore Rocks can help you change the template for multiple items at once!

Posted in Sitecore
2 comments on “Custom Image Templates in Sitecore
  1. […] As you can see in the image above, I added a Caption Text field to the image templates. You can add this field directly to the JPEG and Image templates but you need to consider that the templates will be reset when upgrading to a new version of Sitecore. Your best bet is to create your own custom image templates that inherit from the default JPEG and Image templates. This topic is discussed in a supplemental blog post named Custom Image Templates in Sitecore. […]

  2. Kevin Becker says:

    Can you be more specific about how to create the template(s)? Do I need to create a template for each format? What is the base template that I should use? What’s a real example path that goes into the Config file?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s