Creating a fancybox album with Uploads module | calguy1000.com

Some of the most frequently asked questions on the CMSMS forum are about photo galleries or albums.  For some this is a complex manner, many just want a simple list of pictures to be displayed in a grid, and use something like lightbox to display the images once somebody clicks on a thumbnail.  CMS Made Simple has lots of ways this can be done... Heck you can even do it by hand within a content page.

This article will illustrate how to use the Uploads module (an addon for CMS Made Simple) to create a photo gallary using fancybox in five minutes or less.   Seriously, five minutes.  Well, if you are at all experienced with CMSMS, it will probably take longer to read this article than to implement the steps in it.

Why would you want to use the Uploads module for this you may ask.... There are a few reasons I can think of:

• The Uploads module supports allowing users to upload files.  Maybe you want to allow some authorized site visitors to upload files to your gallery,
• The Uploads module supports automatic thumbnailing and watermarking of images
• You can add a one line summary, and a detailed description to each file
• You can mix media types in the same gallery.  I.e: maybe you want to mix in PDF's, MP3's, JPGS, and other file types in the same gallery... and still have thumbnails work like a gallery.
• You can count the number of times an image has been viewed in detail mode (though we'll cover this in a later blog entry)
• Using a module like CGFeedback, you can allow users to add comments to each image.
• There are alot more reasons.

Step 1 : Install the modules

What modules will you need?  Essentially, you will need both the Uploads module, and the JQueryTools modules.  Also, please note that both the Uplaods and JQueryTools module are dependant upon CGExtensions for some functionality, so you'll want to install those first.   You should be able to do that via the module manager. (note, recent versions of CGExtensions requires PHP 5.2+)

Step 2 : Configure Uploads Module

Next you'll need to create a category in the uploads module.  In the Uploads module a 'category' is synonymous with a directory.   On the Categories tab in the Uploads module admin panel you will see an "Add Category" link.  Clicking on this will display a form to allow you to create a new uploads category.   Fill in the details as follows, then click submit.

• Category Name:   Album Demo
• Description:         A quick gallery using fancybox.
• Server Path:        album_demo
• Files in this category can be listed:  Checked

Step 3 : Upload some Images

You will need to upload some images to the uploads/album_demo directory of your CMS Made Simple install.   You can either upload these images using the uploads module admin interface, or via ftp.  it is your choice.   This should take you maybe a minute or two.

Step 4 : Configure the Uploads Summary Template

We need to create a new summary display template in the Uploads module admin console.  This new template will display our thumbnails, and display the fancy popup box for each image.  We'll also allow scrolling forward and backwards between images.  To create a new summary template click on the "Modify Templates" link in the Uploads module admin concole, then click the "New Template" link on the "Summary Templates" tab.  This will display a form allowing you to specify a new template name, and it's contents.

For the template name, I used "Album Demo".   The template contents consist of the default uploads module summary template.  We'll have to tweak this a bit to add the fancybox code.

At the top of the template, I simply added this text:

<!-- Start Upload Summary Template -->
<script type="text/javascript">
{literal}
jQuery(document).ready(function() {
jQuery('.fancybox').fancybox();
});
{/literal}
</script>

This text defines a jQuery ready function that will be executed each time the page loads.  That function says that fancybox should be performed on each element in the document with the class 'fancybox'.

Next, for each file, we need to create a link to the larger file that surrounds the thumbnail.  At first glance through the sample template you won't see anything that directly links to the original file.  You will see smarty variables that will link to a URL to allow downloading the image, but nothing that contains the URL of the original file.   However, by using the techniques described in this article I was quickly easy to find a smarty variable called origfile_url which could be addressed like  {entry->origfile_url}.

The rest is simple, a small change to the summary template like this (note the colored portions):

<a href="{$entry->detailurl}">{$entry->upload_name}</a> ({$entry->size})<br/>
<a href="{$entry->origfile_url}" title="{$entry->upload_name}" class="fancybox" rel="album">
{if isset($entry->thumbnail_url)}
<img src="{$entry->thumbnail_url}" alt="">
{else}
<img src="{$entry->iconurl}" alt="">
{/if}
</a>
<br/>

As you can see this will create a link surrounding our thumbnail.  The link has the class "fancybox", and points to the original file location.

You should now be able to submit this template, and then mark it as the "default" Uploads module summary template by clicking on the red X in the default column

Step 5: Create an Album Page

The last step is to actually display our photos using the template we just created.  To do this I created a new content page in CMS Made Simple, provided a title, menu text, and a parent, and also performed the following:

a) Call the JQueryTools module

Add the following code into the "Page Specific Metadata" area on the options tab when editing your new page.

{JQueryTools action=incjs}

This tag will be called from the section of your page template, and will result in the appropriate javascript tags being generated in the header of the page when the page loads.

b) Call the Uploads module

This last part is the most important, because up until now we haven't seen any images, but it's also the simplest.   I simply placed this tag into my default content area on the 'main' tab, when editing content:

{Uploads category='Album Demo'}

Step 6: Profit!

If you now click the 'submit' button on the edit content form, and then navigate your browser to the newly created page, you should see an album with three columns of thumbnails of the images you uploaded earlier (the initial display may take a little bit of time as thumbnails are generated).   You will also see other details like the title of the image, a brief description, the author of the image, and a link to take you to a detail view.   Click on one of the thumbnail images, and

Voila!

You should see the fancybox window grow, and your full size image appear inside it.  You should also be able to scroll through the images by clicking on arrows that appear in the window as your mouse pointer gets nearer to the left or right edges.

There are alot more things you could do with this template to make it into a full album, and we could style the fancybox stuff completely, change it's effects, etc.  but the basics are there.

I encourage you to read the fancybox documentation, and the smarty documentation, and also explore the options of the Uploads module, there is alot of power to create some advanced gallery pages using this module.

Later I'll cover how to use the same technique to do some fancy ajax stuff with fancybox.