Introducing The umbraco:image Control

Heads Up!

This article is several years old now, and much has happened since then, so please keep that in mind while reading it.

As we all know, Umbraco is the friendly CMS. And maybe it is because of our fantastic community, that the act of outputting an image on a page has almost always caused a google search, and a bit of head scratching. Maybe followed by a forum post, and a pointer from one of the many helpful community members.

The scenario is: You have a documenttype that contains a media picker. Now you would like to output the image that was picked to your page. The first time you try that, you probably did this:

<umbraco:item runat="server" field="bannerImage" />

Using the standard umbraco:item control

And you probably got a bit disappointed when it returned "1063", and not an image. Then you go to google and figure out that you need a macro of some sorts, or some inline XSLT mumbo-jumbo, and after a while, you kind of just accept that.

No more!

As of Umbraco 4.11, there is a new control in town: umbraco:image. It is fairly simple to use, and should make it a bit easier to work with images. You use it like this:

<umbraco:Image runat="server" field="bannerImage" width="200" height="100" class="banner" />

Using the new umbraco:image control

And that will output this:

<img src="/media/19/73006.jpg" width="200" height="100" class="banner" />

Default output with no parameters

ZOMG! That is the most awesome thing since sliced bread. Almost :-) Let's take it a little further.

There are three attributes on the control:

  • field - The property to get the image id or path from
  • parameters - A name/value collection passed to the selected provider. (Default provider supports thumb|crop)
  • provider - Specifies which provider to use when generating the url for the image

All other attributes will be passed directly through to the img tag. For example the width and height attributes.

Providers

Per default, the control will use the built-in provider, which will allow you to select a thumb that is generated by the Upload datatype or a crop from the ImageCropper to display. You would do that like this:

<umbraco:Image runat="server" field="bannerImage" Parameters="thumb=200" />

Built in thumbnail usage

Which generates

<img src="/media/19/73006_thumb_200.jpg">

Rendering with thumbnail specified

or

<umbraco:Image runat="server" field="bannerImage" Parameters="crop=small" />

Using the small crop from the cropping datatype

Which generates

<img src="/media/19/73006_small.jpg">

Rendering with a crop specified

Roll your own

Many of you are using other forms of image tools, such as the lovely ImageGen. No problem! You can write a provider that will generate any type of URL you want! I have written a quick sample provider for ImageGen here, that you could take a bit of inspiration from: https://gist.github.com/3835255

To use a specific provider, just tell the control to do so:

<umbraco:Image runat="server" field="bannerImage" Parameters="width=200" Provider="imageGen" />

Specify custom provider

And with my custom provider, that would give you this output:

<img src="/ImageGen.ashx?image=/media/19/73006.jpg&amp;width=200">

Output from custom ImageGen provider

And Bob's you uncle! :-)

I hope you will find this useful, and maybe give some feedback on how you like it.

Morten Bock Sørensen

Morten is on Twitter as