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" 

                          Width="100" 

                          Height="100" 

                          Transformation="ScaleToFit" 

                          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.

Transformations

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

ScaleToFit
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.

Stretch
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" 
             TagName="EPiImageResizer" 
             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"
                          Width="150" 
                          Height="150" 
                          Transformation="ScaleToFit" 
                          runat="server" />

Advanced features:

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

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