Custom jquery gallery with Matrix

September 30th, 2010 | Filed in: Custom PHP • Third party add-ons | Comment on This Post

When we were designing santaclaracontainers.com, the principal focus of the site was to showcase the product line. Since the site was built on Expression Engine, crafting a product database that the client could ultimately control was the easy part. The challenge for us was finding a way to display the stark hi-resolution images from the company's catalog in a simple and easy to use layout.

Crafting The Gallery
Our client requested that we stay away from using a lightbox to showcase their product photography. The client wanted to maintain all of the product information on one page, and felt that the lightbox was adding a layer of interactivity that obscured the product details. We decided that writing some custom jQuery code to create a thumbnail list we could position over the large image (and replace dynamically when clicked) was the route we wanted to take. If we positioned our thumbnail images to float absolutely over our large image - we could maintain a single page layout and preserve the client request. We selected this option because the products our client uploads to their catalog sometimes come in a variety of colors. By showcasing the principal product image in a large size, we decided the thumbnails could showcase other available color options (when available):

The Goal
To create a simple custom field in Expression Engine that uses the Matrix add-on for uploading unique full sized product images, and their associated thumbnail images. Full sized images will display(one at a time) in a placeholder DIV. All available images in the gallery will display as thumbnails overlaid on top of our full sized image. When a user selects a thumbnail image, the full sized image will fade out, and the full sized version of the selected thumbnail will fade in to replace it.

Crafting The Styles
The simple portion of designing the gallery was the CSS. We needed only two main elements: our unordered list of thumbnail images, and a DIV to act as our large image place holder. By setting our unordered list element to an absolute position with a higher z-index, we could float the list of thumbnails over the DIV that contained our large image. Basic styles used in the creation of our gallery have been included below:

Note that the width and height of our aptly titled ID #bigimage are arbitrary values. We defined these values based on our full-size image dimensions.

Populating the gallery with data from Expression Engine
Our CSS styles were defined, the next step was writing the html mark-up into our template:

{exp:weblog:entries weblog="products" disable="categories|member_data|trackbacks" show_future_entries="yes"}<?php

$totalrows  = "{detail_images:total_rows}";
?>
<ul id="overlay">
{detail_images}
<?php
if($totalrows > 1) {
?>
<li><a href="{proshot}" onclick="null; return false;">{exp:imgsizer:size src="{thumbnail}" width="100" height="100" alt="{title}"}</a></li>
<?php
}
?>
{/detail_images}
</ul>
{detail_images limit="1"}
<div id="bigimage" >{exp:imgsizer:size src="{proshot}" width="595" alt="SCP Containers"}</div>
{/detail_images}
{/exp:weblog:entries}

Some Explanation
We used a couple of add-ons in the development of this website. Some of the custom field names present in the template mark-up above, represent the columns in Brandon Kelly's fantastic Matrix add-on, and the images are being controlled with David Rencher's essential img sizer plug-in. The images below represent the configuration of our custom field group "products." Note the field name of our custom field, and the column names in the Matrix, as they are all directly linked in the template mark-up included in the code snippet above.

Some Custom PHP
We enabled php in our product template. This is important because as you can see in the template mark-up from above, we included some custom php code. This php code has one purpose: to count the number of database rows in our custom field. We are using custom php because we want to verify the number of images inside of our custom field. If there is only one image in our gallery, we won't need to display our unordered list of thumbnails. We will only display our large image.

So reviewing our template code: after we open our weblog, we immediately define a php variable called totalrows. We set this variable equal to the number of rows in our custom field ("detail_images"):

{exp:weblog:entries weblog="products" disable="categories|member_data|trackbacks" show_future_entries="yes"}
<?php
$totalrows  = "{detail_images:total_rows}";
?>

Once we have our php variable counting the number of rows our custom field contains, we proceed with declaring our unordered list. After our <ul> opens, we call our custom field name:

<ul>

{detail_images}

The next line contains more custom php - a conditional statement which checks to see if there is more than one row in the database. If our totalrows variable is greater than only 1 row, we can populate our list items. If the variable totalrows is not greater than 1 row, our <ul> will not contain any <li> elements:

<?php
if($totalrows > 1) {
?>
<li><a href="{proshot}" onclick="null; return false;">{exp:imgsizer:size src="{thumbnail}" width="100" height="100" alt="{title}"}</a></li>
<?php
}
?>

Think of the custom php as a thumbnail counter in a sense. If the php finds more than one entry, it tells our template to go ahead and write our unordered list of thumbnail images. The rest of the mark-up involving the unordered list is self-explanatory, and involves terminating the custom filed name, and then our <ul>:

{/detail_images}
</ul>

We then declare the DIV ID of our large image. We open our custom field detail_images once again - but this time declare a limit of 1 on it. We do this because we only want one single large image displaying at a time. We define the image src content inside the DIV by calling in our matrix column name, defining the rest of the image properties, and then we close our custom field, and close the weblog:

{detail_images limit="1"}
<div id="bigimage" >{exp:imgsizer:size src="{proshot}" width="595" alt="SCP Containers"}</div>
{/detail_images}
{/exp:weblog:entries}

The images above should help illustrate the process of showing or hiding the list items in our template code. Some products come in only one color - and therefore won't need to showcase thumbnails. However other products have multiple color options, and our thumbnail list is a great way of allowing users to preview the product in multiple colors.

Adding Interactivity
Our gallery is now connected to our custom field, and populating with the correct number of thumbnails (when applicable) over our large image, or simply showcasing the large image only. We still need to add in our jQuery to make our gallery more dynamic:

We typed up a quick jQuery function that fades out our currently loaded large image (recall the div ID we created in our CSS called #bigimage) and then replaces it by fading in the associated large image of the clicked thumbnail. This jQuery code is simple to follow and heavily references our CSS mark-up, so it should be easy to understand.

Source Files
We are including a simple demo of the files used in this article (minus the expression engine mark-up, obviously) so that you can easily port the code into your own EE site and customize it with the correct custom field names. Remember that you can include our php code in your template to disable thumbnails from displaying if your have only one image in your entry.