Adventures with ImageCropMode!

I was recently working on a development project here at Offroadcode, and I noticed something strange was happening with the images being used on different sections of the site. Like many ecommerce websites, this one was particularly image-heavy with banners, thumbnails, multiple product images, etc. Which means, of course, that we were taking full advantage of James South's fantastic Image Processor, which is in Umbraco core. But something was weird and it wasn't until I did some digging that I realized what the source of the problem was...


As a primarily back-end developer, I don't like to set the image dimensions on my C# models because they often require flexibility on the front. I provide our front-end developers with access, instead, to all of the image data and the extensions that are built into Umbraco for images, such as GetCropUrl(). That means that we all have the flexibility to modify images on the fly based on our clients' needs, which is my preference, especially with responsive design being the baseline (remember when it wasn't?!). However, it hadn't occurred to me that we could actually be using the extension differently based on how we learned it.

For that reason, half the site had images that were padding on crop and showing black borders to fill in the missing resize space and the other half of the site had images that were cropping to the dimensions and "cutting" the images into the desired shape (also known as ImageCropMode.Pad vs ImageCropMode.Crop). The differences between how we use GetCropUrl() was the culprit, so I'm going to quickly explain it (without delving into the bowels of Umbraco because I have not run any speed tests on any of these, sorry).

"My" Way

For the most part, when I use GetCropUrl(), it's primarily only with dimensions: @Model.Image.GetCropUrl(100,100). Although, in some cases, we'll also set the quality as we allow (and encourage) our content editors to upload large, gorgeous images and let Image Processor handle making them web-friendly. In the case of my example here, I've applied GetCropUrl() directly to the image, which is how I've always done it (that's how you had to do it pre-7.3.5, so that's how I learned it). But there are actually three ways to use GetCropUrl() (who knew?!), and they function differently. Hence the mystery.

The first way to use GetCropUrl() is by applying it the way I learned it - to the IPublishedContent of the image. This way defaults (as I thought all modes default to...) ImageCropMode.Crop. If you want to call it with width & height dimensions, you would use it like so:

@Model.MainImage.GetCropUrl(300, 300)

The Training/Documentation Way

I've done a few Umbraco trainings as time has passed and Umbraco has changed so that I can keep up-to-date with best practices, and the way that I see them generally teaching how to use GetCropUrl() now is also the way that it's referenced in the documentation. And that's to use the UrlHelper instead of the extension for IPublishedContent. This version works the same as the pre-7.3.5 version that I use (which still works, as a note, as we always build new sites on the most recent release of Umbraco) in the sense that it also defaults to ImageCropMode.Crop for what it returns. You can use it like so:

@Url.GetCropUrl(Model.MainImage, 300, 300)


So what I didn't know, but our front-end developer did (sneaky!) is that there's a third way of calling GetCropUrl(), which defaults to ImageCropMode.Pad and caused a great amount of confusion as to what was happening in the image settings across the site. This third way is actually a string extension that can be called at the end of any image Url. You can use it very similar to "My" way of cropping images, except the call is done on the Url itself instead of the IPublishedContent item, like so:

@Model.MainImage.Url.GetCropUrl(300, 300)

As you can see, this pads the image instead of crops it, which can be overridden by using one of Image Processor's gigantic amount of settings, changing the call to:

@Model.MainImage.Url.GetCropUrl(300, 300, imageCropMode: ImageCropMode.Crop)

However, I just swapped everything out to one of the other two options that have ImageCropMode.Crop set to the default until I have time to look into the core code and see if there are any differences in processing power.

Want to know more about Images and Umbraco? You can check out the documentation here. You can also learn about the in depth workings of Image Processor on it's website here.

If you know anything about the differences in loading speeds or processing requirements for these three different methods, I'd love to hear from you about your results :) Send me a ping on the Umbraco slack, twitter, or an e-mail! Cheers :)

Did this help you? Give it a tweet!

Keep up to date with our posts via our RSS feed

Drop us a line

Got a project in mind or just want to say hello? Send us a mail right here.