Views: 7102
Number of votes: 6
Average rating:

EPiImage Part 1: EPiImageResizer

What is EPiImage?

EPiImage is a free module on EPiCode that provides basic image scaling functionality, as well as two new property types: EPiImage Property that extends “URL to image” with a preview, and EPiImageGallery Property that provides a editor friendly way to add pictures to a gallery including drag and drop sorting, description texts etc. It is not ment to do everything, but what it does it does well, and should be useful for any EPiServer project.


The EPiImageGallery Property in edit mode.


How did the module come about?

The EPiImage module is the result of two things.

  1. My frustration over developers building an image resizer and/or image gallery functionality from scratch in every project (or every developer having their own homegrown version they reuse). Often having too few features and too many bugs :-)
  2. The astonishing fact that this functionality isn’t built into EPiServer. It should have been in version 4 if you ask me.

I know a lot of you have a similar module/library in their toolbox, but I wanted to create a module that easily can be added into any EPiServer project, that follows a few best practices, have some cool features and that we can get the whole community to help debug. (Hello JavaScript errors in edit mode ;-) )


EPiImage: Part 1 of 4

EPiImage consist of 4 parts, and I will write a blog post about each:

  1. EPiImage Resizer (User Control): Resize images automatically with caching.  (This blog post)
  2. EPiImage Property: Extends "URL to image" with preview and description/alt text 
  3. EPiImageGallery Property: Create an image gallery with previews, description/alt texts and drag and drop sorting.
  4. EPiImageGallery Viewer (User Control): Sample implementation of using a EPiImage Gallery Property


In this blog post we will look at the first part: EPiImageResizer.


Part 1: EPiImageResizer

EPiImageResizer provides an out of the box automatic resize functionality to EPiServer. There is nothing to configure (although you can if you want) and it simply works. All resized images are stored in a cache folder for performance, and the resized image has a SEO friendly URL.

So lets see it in action.

<EPiImage:EPiImageResizer ImageUrl="/images/MyImage.jpg" 
                          runat="server" />


As you can the original image is resized from 150 x 150 pixels to 100 x 100 pixels. The width and height attributes defines the maximum width and height of the resized image, in this case 100 x 100 pixels. The resized image is cached in the /Globals/Scaled/ folder in VPP, so the next time someone visits the page it simply uses the cached image.



In the above example we use the “ScaleToFit” transformation, but EPiImageResizer actually supports 3 different transformations:


This is what you normally want. It simply scales the image perserving the aspect (width/height) ration to fit inside the width and height you specify.

Scale To Fill
This transformation scales the image to fill the specified width and height maintaining the aspect ratio, but crops away anything that ends up outside the width/height box.

This transformation simply scales the image to the specified width and height without preserving the aspect ratio.


How do I start using it?

Simply download the module from EPiCode and install it using EPiServer Deployment Center. (It just copies in a few files, it doesn’t touch your web.config or require a rebuild)


Register the EPiImageResizer user control on the page you want to use it:

<%@ Register TagPrefix="EPiImage" 
             Src="~/EPiImage/UserControls/EPiImageResizer.ascx" %>

Then specify the url to the image to be scaled, max width and height and what transformation you would like:

<EPiImage:EPiImageResizer ImageUrl="/images/MyImage.jpg"
                          runat="server" />


Advanced features:

The user control also have a bunch of other attributes for more advanced features:


Attribute: What does it do?
PropertyName Specify the name of a property to fetch the image url from instead of using ImageUrl.
FallbackImageUrl If the ImageUrl or PropertyName is empty, use this image instead.
LinkURL Adds a <a href tag around the rendred img tag.
Alt Adds an alt attribute to the rendered img tag
Tooltip Adds a title attribute to the rendered img tag for mouse over tooltips in all browsers
CssClass Adds a class attribute to the rendered img tag
CssStyle Adds a style attribute to the rendered img tag
LinkCssClass Adds a class attribute to the a href tag.


Have feedback? Want to help out?

Feel free to email or twitter me with your feedback: @ahaneng :-) Also if you like to help out with debugging/testing let me know.

Word of warning: I want to keep this module small and simple, and no, it won’t solve everybody's needs, but it will solve basic image needs for most small/medium projects. So that means no YouTube/Viddler/Flickr support etc. (But hey, it is open source so feel free to fork it if you really want to) :-)


And finally: Thank you to Making Waves for donating it to EpiCode!


Next post: EPiImage Part 2: EPiImage Property

Sep 09, 2010

( 9/21/2010 10:33:36 AM)

Great stuff - and thanks for contributing! Personally I'm not so worried about the javascript gallery but more the Image resizing. I completely agree with you, that this type of functionality would be great to be included in the core EPiServer product.

( 9/21/2010 10:33:36 AM)

I agree with Mark on this one, I'm really surprised that at least some elements of EPiImage haven't made it into the core product. I've tried it and it seems good so far. If I could make one minor suggestion it would be to change the logging to use log4net...

( 9/21/2010 10:33:36 AM)

Log4net logging will be added in the next release. :-)

Sandor Voordes
( By Sandor Voordes, 1/6/2011 7:01:46 PM)

Hi, I am enjoying EPiImage a lot and find it essential that editors are not forced to scale images themselves just to avoid their website to collapse. What I am missing are:
* support for images stored in as page files. At least I don't seem to see it working
* support for up-scaling images. It seems that images smaller that the requested dimensions are not scaled at all. There are some good algorithms around where a little up-scaling is quite good.

Keep up the cool work

Martin Steffensen
( By Martin Steffensen, 10/19/2012 12:54:36 PM)

Hi, great work!
A question on the caching implementation.
Is it by choice that it is set to a clean-up job after x-nr of days?
I would like either to have a event subscriber that invalidates the cache when a new version of a file is uploaded, or a check for updates when looking for the file in the cache.
Something to add maybe?

( 1/10/2013 4:17:48 PM)

Is there any way to use ScaleToFit to enlarge images? It just seems to be able to shrink them atm.

( 1/11/2013 8:57:35 AM)

I can use ScaleToFill to enlarge but then one parameter (width or height) has to be smaller than the original size. What gives? :)

Rahul Chauhan
( By Rahul Chauhan, 11/11/2013 11:51:54 AM)

Hi, I am using EPiImage:EPiImageResizer along with prettyphoto jquery and it is working well. However when i right click on the image and try to save it by clicking "save image as" then it brings up the whole image path to save ("Global-Hotel World Square-rydges-world-square-conference-room") rather than just the image name as "rydges-world-square-conference-room". Does anyone knows this strange behaviour or its just the part of EPiImage?

Please login to comment.