Using XSLT, ImageGen and jQuery
This is an old post written for Umbraco 4 using XSLT and isn't really relevant for Umbraco 7.
In this blog post I'll show you how to create a simple photo gallery using the Umbraco CMS (I'll be targeting the Umbraco 4.5 and above schema). Whilst there are already a few gallery packages available I often find that "rolling your own" gives you more flexibility and control over the end results. It's also more instructive and fun to create your own, too!
Note: In the following tutorial I will assume you understand the basic concepts of Umbraco and are comfortable building simple pages with it. If you're a complete beginner, this might not be for you...
Basic Concepts
To create the gallery we'll use a few components:
- An Umbraco document-type that allows an editor to create a new gallery page
- An XSLT file that generates the HTML for the photos in the gallery
- A 3rd party jQuery plugin for generating a 'lightbox' style modal window for each image
- An excellent Umbraco package called ImageGen for generating thumbnails
The basic concept for the gallery is that an editor will create a gallery page within their Umbraco site. The gallery page will have one property that utilises the built-in Media Picker datatype to allow the editor to select a folder in the Media Library. A macro will be added to a template that calls the XSLT, passing in the id of the media folder. The XSLT will then iterate through every image in the folder, generating an unordered list of images and links. The image will be a thumbnail, generated using ImageGen, and it will be surrounded with a hyperlink to the original image. A little jQuery magic will the pop-up the original image in a nice lightbox. Bobs your uncle!
Putting It All Together
OK, now we (hopefully!) understand the idea behind the gallery and what components we'll be using we can start to look at some snippets of code. Note I won't be giving out the entire code to the gallery; rather I'll be using this tutorial as a way of pointing you in the right direction to create your own. In the long-run it's better to understand how to build something than blindly copying and pasting (not that I don't indulge in the latter sometimes myself, of course).
Creating a Gallery Document Type
The first thing we'll need to do is create a new Document Type in Umbraco (under the Settings section). You can call it what you like (such as Media Gallery). This can inherit from a common Master if you like, it doesn't matter. The main thing is that you add a new property to it that uses the Media Picker datatype. In my example I'll give this an alias of mediaFolderId as we will be using it to select a folder within the media library.
Once you've created a page instance using this Document Type you can then use it to select a folder in the Media Library containing the images you want to display in your gallery. This way you can easily add new images simply by uploading them to the folder.
Installing ImageGen Package
As mentioned, we will be using Douglas Robar's excellent ImageGen package for creating the image thumbnails, so before we proceed you should install ImageGen from the Umbraco Package Repository (you'll find it under Website Utilities). If you're not sure how to do this, check this blog post by Tim Geyssens. Note the standard version is free to use and this does everything we need (but if you like it support Doug and buy the pro version!).
Adding the XSLT
OK, now we've created a way of selecting a Media Folder we need to create the XSLT that grabs all the images from the selected folder and generates the HTML list. To do this we make use of an umbraco Library XSLT extension called umbraco.library:GetMedia(). What this basically does is return some XML that describes all the images in the folder - we can then iterate over them using XSL for-each. Note I'm calling GetMedia() with the second parameter as 'true' which I believe tells it to optimise the query to return all items in a go.
This is illustrated below in the following XSLT snippet:
<xsl:output method="xml"omit-xml-declaration="yes"/>
<xsl:param name="currentPage"/>
<xsl:variable name="mediaFolderId" select="number($currentPage/mediaFolderId)"/>
<xsl:variable name="thumbWidth" select="number(256)"/>
<xsl:variable name="thumbHeight" select="number(170)"/>
<xsl:template match="/">
<!-- Displays all images from a folder in the Media Library -->
<xsl:if test="number($mediaFolderId)">
<ul id="gallery">
<xsl:for-each select="umbraco.library:GetMedia($mediaFolderId, true())/Image">
<xsl:iftest="umbracoFile !=''">
<li>
<a href="{umbracoFile}"title="{@nodeName}"rel="gallery">
<imgsrc="/imageGen.ashx?image={umbraco.library:UrlEncode(umbracoFile)}&width={$thumbWidth}&height={$thumbHeight}"width="{$thumbWidth}"height="{$thumbHeight}"alt="{@nodeName}"title="{@nodeName}"class="thumbnail"/>
</a>
</li>
</xsl:if>
</xsl:for-each>
</ul>
</xsl:if>
</xsl:template>
As you can see we use a for-each loop to get all the images in the folder with the id that matches the value stored in the current page's mediaFolderIdproperty. This in turn generates an unordered list that consists of a link to the original image and a thumbnail of the image resized dynamically by ImageGen. We also add a few ids and classes to the HTML that can be used to style the list using CSS and also to identify the gallery so we can use it with a jQuery lightbox plugin. For accessibility we also ensure that we use the image name (@nodeName) in any alt tags and title tags.
For reference, the generated HTML would look something like this:
<ul id="gallery">
<li><a href="/media/18228/ferrari_f40.jpg"title="Ferrari F40"rel="gallery">
<img src="/umbraco/imageGen.ashx?image=%2fmedia%2f18228%2fferrari_f40.jpg&width=256&height=170"
width="256"height="170"alt="Ferrari F40"title="Ferrari F40"class="thumbnail"/></a>
</li>
<li><a href="/media/18233/ferrari 365.jpg"title="Ferrari 512BB"rel="gallery">
<img src="/umbraco/imageGen.ashx?image=%2fmedia%2f18233%2fferrari+365.jpg&width=256&height=170"
width="256"height="170"alt="Ferrari 512BB"title="Ferrari 512BB"class="thumbnail"/></a>
</li>
</ul>
Once you've created the XSLT you can then add it to a Macro and embed it within a page template. I'll assume you know how to do this. But as an example, it would look something like this:
<div id="photos">
<umbraco:MacroAlias="DiploMediaGallery" runat="server"></umbraco:Macro>
</div>
Just insert the macro inside the template where you want the gallery to be displayed.
Add a jQuery Lightbox
Finally to finish things off we will add a nice jQuery 'lightbox' style plugin that will turn the link to the original image into a nice modal pop-up window. For this example I'll be using a lightweight jQuery plugin called ColorBox. However, you can easily adapt it to use any other similar plugin, such as FancyBox. Just follow the instructions on colorpowered.com/colorbox/ for installing ColorBox and remember to include a reference to the jQuery library. You should then be able to use a simple bit of jQuery script to initialise the gallery, such as the code I use on my site which is:
<script type="text/javascript">
$(document).ready(function()
{
$('#gallery').find("li a").colorbox(
{
maxWidth:"94%",
maxHeight:"94%"
});
});
</script>
Basically when the DOM is loaded this calls the ColorBox plugin telling it to work it's lightbox magic on all the nested LI A child elements of the UL id of#gallery UL element. This turns the hyperlinks into nice lightboxes (for users that have JavaScript enabled). In other words, when a user clicks an image instead of it opening in another window it pops-up in the lightbox with a nice caption (based on the title).
2 Comments
HEy
How can we reorder the images or add text to teh images
Dan Diplo
You can either sort the items in Umbraco or add an order-by query when you get the media out. To add text, you can either use the name or add a custom property to your image media item.
Leave a Comment
Just fill in the form and click Submit. But note all comments are moderated, so spare the viagra spam!
Tip: You can use Markdown syntax within comments.