Make Sitecore deliver images which fits the screen, part 2

This is the second part of a mini-series where I show how you can make Sitecore deliver images that fully support a responsive web design. See the first post here if you haven’t read it already.

In this part I will show how to make Sitecore center-crop images through the media handler using query string parameters.

The concept is basically that you call the media handler with specific querystring parameters that will make Sitecore center-crop the image. Similar to the out-of-the-box Sitecore image parameters.

The previous post in this series showed how to set JPEG compression level dynamically using a querystring parameter.

The whole point of these extra media features is to prevent unnecessary bandwidth use in responsive web design. JavaScript on the client can request Sitecore to deliver images in a compression ratio, resized and cropped to fit with the current screen view.

In a later bonus post I will show how this can be implemented client side.

Why make yet another image cropper?

Several very fine modules already exists out there that can both crop and center crop images. For example Image Cropper on MarketPlace do exactly this.

The main reason for yet another cropping module is that I once again started coding before I googled the subject. It just seemed as an obvious thing to implement along with the JPEG compression processor.

The code that I show here also differ a bit from ImageCropper on some other key points.

  1. The code does not use the normal  width and height parameters to crop the image. Instead there is separate querystring parameters for the crop width and height. This is done so Sitecores ResizeImageProcessor is not skipped. Using this approach you can  control the size of the image before cropping it to fit the screen.
  2. The code does not extend or change the  sc:Image webcontrol. This is a design choice since the code is intended for supporting responsive web design and not something set server-side. The media handler is in this case supposed to be called from the client using JavaScript.
  3. None of the existing getMediaStream processors are replaced or extended and the code does not rely on one big processor which can perform a large set of actions. Instead each action that can be performed on the image is performed in a specific separate processor with clear responsibility (in the end this is just an architectural preference and not related to the end functionality).

Lets just look at some code instead of me trying to explain myself.

Cropping the image

Center-cropping an image in .NET using C# is quite straight forward when all input parameter validation is in place.

The following class center crops an image from a Stream and returns a Stream with the cropped image in the format that is passed to the method as a parameter. The code will center-crop any bitmap image format.

Handling the media request

Now we can center crop the image so all we need to is simply make yet another getMediaStream pipeline processor to handle the media request.

In this processor we first check if the media request is for a “crop-able” image using the mimetype from the media item. Then we look for a query key indicating if we should crop the image.

If this key is present then we look for a crop-width and a crop-height key. These defaults to the actual image width or height if not set. If neither is set then we exit the processor since there is no cropping to perform. Otherwise, we do the cropping and set the new Stream as outputstream in the getMediaStream pipeline args.

Finally we insert the processor in config and add the various settings that the processor uses in an include config file.

 The above config also contain the processor from the previous post.

Notice the order in  which the processors are patched in. We want Sitecore to resize or grayscale the image before we do anything. then we want to crop the image and as the last step we want to set the JPEG compression ratio.

Once again the Windows Koala will be my victim.


First the full image proportionally resized by standard Sitecore with height set to 400

koala_cropheight300 Here we have the Koala center-cropped using a cropping height on 300 px.

koala_cropwidth300 Here we have the Koala center-cropped using a cropping width on 300 px.


Now we cropped down the Koala to height 75 (almost no Koala left)

koalacroppedascubeAnd now cropped to a 125 x 125 centered cube still using height 400.


Finally we have the Koala in a 200 x 200 cube using JPEG compression level 5 and even in grayscale using Sitecores pre-built gray query.

That was it, I hope someone find this useful.

Where can I get my hands on this code precompiled?

I’ve tried uploading the module to Sitecore MarketPlace but they apparently have some issues at the moment.  I kept getting the Sitecore login screen when I was editing the module I’ll try again soon and keep this post updated.

Until then simply copy-paste the code from this post.

Let me know if anybody want the code in a Github repo instead of MarketPlace then I’ll create one.

Anders Laub Christoffersen

Anders has been working with Sitecore for over a decade and has in this time been the lead developer and architect on several large scale enterprise solutions all around the world. Anders was appointed the title of Sitecore Technical MVP in 2014 and has been re-appointed the title every year since then.

4 thoughts on “Make Sitecore deliver images which fits the screen, part 2

  1. Very useful stuff. I was implementing something similar and half way through i thought of searching over net. Glad, i saved my time and effort.

  2. This is great! It would be helpful if you had included the using directives at the top of each class. 🙂 I think I know which one’s are needed, but just in case. Thanks

  3. Small issue that caused some weird effects on the media cache running version 8.1.
    Don’t get the custom options directly from the url, use the args.Options.CustomOptions (GetQueryOrCustomOption).

    If your initial request contains parameters, Sitecore will actually run the GetMediaStream pipeline twice. First for caching the original image, then the version with parameters.

    Also keep the media request protection in mind starting from version 7.5, this involves adding custom parameters to Sitecore.Media.Requestprotection.config.

    Great extension, thanks!

  4. Hi Andrew

    Awesome work Andrew. Saved me a day of work!! Did you get a chance to upload this to Github.


Leave a Reply

Your email address will not be published. Required fields are marked *