Slide Show Documentation

• Terminology
  • Gallery: One set of associated images, and the metadata associated with the group such as the theme, date created, directory where it is stored, etc.
  • Theme: Basically the title of the gallery
  • Gallery Root: Each instance of the admin that is set up must have a gallery root defined (preferably in the Application.cfm), which is the directory where all the galleries are stored (each will have its own subdirectory)
  • Admin: The administration area that is set up to allow for creation and maintenance of image galleries for a site
  • List View: the presentation that shows a list of galleries
  • Thumbnail View: the presentation that shows the thumbnails of all the images in a gallery
  • Details View: the presentation that shows a single image in a gallery; this is the view that most people would actually associate with the term 'slideshow'
• Using the Slideshow System The slideshow administration area is used to create, edit, and maintain slideshow galleries.

  • Creating a new slideshow

    1. Click on 'Create a New Gallery' on the main menu.
    2. Enter the information associated with the gallery you want to create:
       • Theme: The theme or title for the gallery (required).
       • Category: The category for the gallery (optional). This can be used to organize your galleries into categories. Select a previously entered category from the dropdown, or else select 'New Category' from the dropdown and enter the category name in the textbox provided.
       • Date: Enter the date for the gallery (required). NOTE: The date associated with the gallery is used to determine the name of the directory to create the gallery in and store all of its information and images. This date can be changed once a gallery has been created, but if there are pages that have hard-coded links to that gallery, these will be broken.
       • Description: The description associated with the gallery (optional).
    3. Click 'Submit'. The gallery will be created, and you will be taken to the gallery administration page.

  • Viewing existing galleries

    1. Click on the 'View Existing Galleries' link to view the galleries that currently exist.
    2. Clicking on either the thumbnail image or on the theme of the gallery will bring you to its gallery administration page.

  • The gallery administration page

    • You can reach the gallery administration page for a gallery by creating a new gallery or by going through the 'View Existing Galleries' link, as outlined above.
    • The gallery administration page tells you some brief info about the gallery (theme, category, date, description, and how many images are currently in the gallery).
    • From this page, you can do one of three things:

      • Edit the data for this gallery

        1. Clicking on this link will bring you to the gallery data page.
        2. Please see the section above on 'Creating a new slideshow', for this page is the same as that one (especially see the NOTE about the Date field.

      • Edit the images for this gallery

        Clicking on this link (or on the link that is on the number of images in the gallery) will bring you to the image admininstration page. There are three uses of the image administration page:
        • Upload images: You can click on '[Upload images] in order to add new images to the gallery. Uploading images involves uploading the full size image, and a thumbnail if desired. If you do not upload a thumbnail, one will be generated automatically. You can also specify image data when you upload, or you can add/edit the data associated with an image later.
        • Reorder images: You can click on '[Reorder images]' in order to change the order of the images within the gallery. The images in the gallery will be displayed, where the first image is in the top left, and then the order goes down the first column, then to the second column. Drag and drop the images where you want them, and be sure to click 'Reorder' to save your changs (or 'Cancel' to not!).
        • Edit image data: You can click on '[Image Data]' in order to edit the information associated with each image. The images will be displayed, and you can click on '[edit data]' under an image to change the its information. You can also click on 'Delete this Image' to delete an image. If you edit image information, be sure to click 'Submit Changes' at the bottom of the page to save any changes!

      • Delete this gallery

        This will permanently delete this gallery.
• Administering the Slideshow System
  • Installation

    The installation of the slide show system involves two major components: the admin area, and any instances of the custom tag that displays the galleries that are created in the admin.

    • Admin Installation

      The functional content of the admin area is centralized and shared by every instance of the admin that is used. This allows upgrades to the admin to instantly be available in all admin instances that are in use (in most cases. A notable exception would be if the upgrade actually added a new page to the admin; this would require manually adding that page to all the instances, preferably as another cfinclude).

      When a new instance of the admin is set up, the files that are installed basically consist only of ColdFusion cfinclude statements that call the one central copy of the functionality for those pages. This central admin is located at /xtras/slideshow/admin. There is a template for the set of files that need to be installed for a new instance of the admin that is maintained at /xtras/slideshow/admin.

      Installation of a new admin instance involves the following steps:

      1. Admin files: The admin framework files from /xtras/slideshow/admin_template should be copied to the location where the new admin will reside. A directory should be created that will house the new admin (and preferably be locked down with authentication), and the entire contents of the /xtras/slideshow/admin_template should be copied into it.
      2. Customization of admin Application.cfm variables: There are two Application.cfm that must be customized for the new admin: APPLICATION.path must be set to the directory where the new admin is being installed, and APPLICATION.GalleryRootPath must be set to the directory where the galleries that the admin will be administering will reside. NOTES: All galleries that this admin maintains must reside in this directory. New galleries will automatically be created there. Other galleries, as long as they were created with this system, can be dropped into this directory and they should be picked up just fine by the application. This directory should be outside of the directory that houses the admin so that the admin can be locked down and the galleries will be accessible.
      3. That's it! The admin should be able to be used to create some new galleries at this point.
    • Custom Tag Installation

      Attributes
      Template Variables
      Example
      

      The custom tag that displays image galleries is meant to provide a very simple, basic default implementation that will allow for easy setup by developers that are not overly versed in HTML or ColdFusion, as well as more advanced features that allow for the complete customization of the display of all aspects of the galleries. This is a difficult tightrope to walk, and the customization is fairly complex until a deeper understanding of the way the tag works settles in.

      The simplest possible incarnation of the custom tag is the following single line of code (please note that the tag call must have the slash at the end - it must be "... />", NOT "... >"):

      1. <cf_slideshow GalleryRoot="#APPLICATION.GalleryRootPath#" />

      The only attribute that is specified ('GalleryRoot') simply tells the the tag where to look for the galleries. The custom tag takes care of everything else, including list view, thumbnail view, and the actual slideshow single image view. The first view that the user will see is the list view, and clicking on the image in the list will take them to the details view while clicking on the title of the gallery will take them to the thumbnail view. Once in the thumbnail view clicking on any image will take them to the details view.

      From this point, the sky is the limit in terms of customization. i will present all customization options; they can be selectively enabled as desired (for the most part, some logically go together and i will try to note this).

      Custom Tag Attributes

      The custom tag has to determine two main things: what view needs to be displayed for the current request (list view, thumbnail view, or details view) and how that view should be displayed.

      Which view is to be displayed can either be 'hardcoded' in to the call of the tag, or can be specified in the URL query parameters. If it is specified in the query string, it overrides any value for the attribute specified in the tag call. Utilizing the query string attribute specification is how the simple version of the tag (above) functions.

      How each view is displayed is completely customizable. Each view has one or more templates that can be set by the calling page and passed into the tag through a tag attribute. If these are not set by the caller, a default template is provided for each view. The best way (in my opinion :-) to specify these templates is to have a .cfm file whose only purpose is to define them, and then include that file just before calling the tag (see example below). The basic process of defining a template is to utilize the cfsavecontent tag to set the template content into a variable, and then pass the variable into the tag as the appropriate attribute. Each template has variables that are used to specify where dynamic content should be inserted.

      i don't specify whether each attribute is optional or required, because the only attribute that is required is 'GalleryRoot'.

      Attribute Name	Default	Views	Description
      GalleryRoot		ALL	Defines the location where the galleries to be displayed are stored. Should be an absolute web path, such as '/photographics/slideshow/galleries/'.
      Action	list	ALL	This should have a value of 'list', 'thumbnails', or 'detail'. It can be specified in the URL query string utilizing whatever the value of the 'ActionQueryVariable' attribute is.
      GalleryDirectory		thumbnails, detail	This should have a value of the name of the directory that the gallery to be displayed resides in (just the name, not the path, since the directory must be within the directory specified by 'GalleryRoot'). It can be specified in the URL query string utilizing whatever the value of the 'GalleryQueryVariable' attribute is.
      Detail_Image		detail	This should have a value of the name of the image to be displayed (just the name, not the path, since the path is specified with the 'GalleryRoot' and 'GalleryDirectory' attributes). It can be specified in the URL query string utilizing whatever the value of the 'ImageQueryVariable' attribute is.
      GalleryListPage	#CGI.SCRIPT_NAME#	ALL	If the page locations for the views are different, this informs the tag of the location of the list view page so that any links there will be correct. The default use of the tag is for the list, thumbnail, and details view to all be on the same page.
      ThumbnailsPage	#CGI.SCRIPT_NAME#	ALL	If the page locations for the views are different, this informs the tag of the location of the thumbnail view page so that any links there will be correct. The default use of the tag is for the list, thumbnail, and details view to all be on the same page.
      DetailsPage	#CGI.SCRIPT_NAME#	ALL	If the page locations for the views are different, this informs the tag of the location of the detail view page so that any links there will be correct. The default use of the tag is for the list, thumbnail, and details view to all be on the same page.
      ActionQueryVariable	slideShowAction	ALL	This is the name for the query string variable that the tag will look for to define the view that will be presented. So if the value of this attribute was set to 'act', then to have the tag show the thumbnail view the query string would need to include a name/value pair like so: 'act=thumbnails'.
      GalleryQueryVariable	slideshowGalleryDirectory	thumbnails, detail	This is the name for the query string variable that the tag will look for to define the gallery that is being shown (in either the thumbnails or detail view). So if the value of this attribute was set to 'gal', then to have the tag show the gallery that is stored in the directory '20070214_343234' the query string would need to include a name/value pair like so: 'gal=20070214_343234'.
      ImageQueryVariable	slideshowImage	detail	This is the name for the query string variable that the tag will look for to define the image that is being shown (on the detail view). So if the value of this attribute was set to 'img', then to have the tag show the image '7.jpg' the query string would need to include a name/value pair like so: 'img=7.jpg'.
      Thumbnail_NumberOfColumns	4	thumbnails	Defines the number of columns to use when outputting the thumbnails. The particular HTML that is used can be customized, this just determines when the tag knows that it is done with a row and to start the next.
      Short_Caption_Length	30	thumbnails	Defines the number of characters to allow for the short version of the image captions that are output in the thumbnail view (if they are specified to show up in the template).
      DefaultCredit		detail	Defines the default caption that will be displayed for images that have none entered.
      Template Attributes
      Custom_List_Template	{Default Template}	list	Defines the template to use when presenting the list view (see the variable list below to see what can be used in this template).
      Custom_Detail_Template	{Default Template}	detail	Defines the template to use when presenting the detail view (see the variable list below to see what can be used in this template).
      Thumbnails_ContentBeforeThumbnails	{Default Template}	thumbnails	Defines the content that is output before the actual thumbnail output is begun. This could include gallery title or other information, or an opening <table> tag. See the variable list below to see what can be used in this template.
      Thumbnails_RowStartHtml	{Default Template}	thumbnails	Defines the content that is output before the start of each row of thumbnails. If a table structure is being used, this could simply include an opening <tr>, or it could be empty if floating <div> tags are being used. See the variable list below to see what can be used in this template.
      Thumbnails_ImageHtml	{Default Template}	thumbnails	Defines the content that is output for each thumbnail image. If a table structure is being used, this could include an table cell with an image tag (<td><img /></td>, or it could just be a floating div with an image tag <div><img /></div>, or maybe an <img /> all by itself. Experimentation is encouraged! See the variable list below to see what can be used in this template.
      Thumbnails_NoImageHtml	{Default Template}	thumbnails	With certain layout templates, it is necessary to provide some HTML when the images have run out but there is another location to be output. For example, if a table structure is being used, and there are 17 images and 4 columns are being used, this means that in the last row the final image will be placed in the first column and the tag still needs to finish the row. This template will be used for the final 3 spots. A common use (such as in this example) would be to simply make the template an empty table cell (<td></td>). See the variable list below to see what can be used in this template.
      Thumbnails_RowEndHtml	{Default Template}	thumbnails	Defines the content that is output after the end of each row of thumbnails. If a table structure is being used, this could simply include an closing </tr>, or it could be empty if floating <div> tags are being used. See the variable list below to see what can be used in this template.
      Thumbnails_ContentAfterThumbnails	{Default Template}	thumbnails	Defines the content that is output after the actual thumbnail output is begun. This could include gallery title or other information, or a closing </table> tag. See the variable list below to see what can be used in this template.

      Template Variables

      The following variables can be used within the templates listed:

      Variable	Description
      Custom_List_Template
      %%_GALLERY_FOLDER_NAME_%%	The name of the folder that the gallery resides in.
      %%_GALLERY_THEME_%%	The theme that has been entered for the gallery.
      %%_GALLERY_CATEGORY_%%	The category that the gallery has been associated with.
      %%_GALLERY_DATE_%%	The date that has been set for the gallery.
      %%_GALLERY_DESCRIPTION_%%	The description that has been entered for the gallery.
      %%_NUMBER_OF_IMAGES_%%	The total number of images that are in the gallery.
      %%_FIRST_THUMBNAIL_URL_%%	The URL to the first image in the gallery (for displaying the image in an <img /> tag).
      %%_THUMBNAIL_PAGE_%%	The URL to the thumbnail view of the gallery.
      %%_DETAIL_PAGE_%%	The URL to the detail page of the first image in the gallery.
      Custom_Detail_Template
      %%_GALLERY_FOLDER_NAME_%%	The name of the folder that the gallery resides in.
      %%_GALLERY_THEME_%%	The theme that has been entered for the gallery.
      %%_GALLERY_DATE_%%	The date that has been set for the gallery.
      %%_GALLERY_DESCRIPTION_%%	The description that has been entered for the gallery.
      %%_NUMBER_OF_IMAGES_%%	The total number of images that are in the gallery.
      %%_GALLERY_LIST_PAGE_%%	The URL to the list view of the gallery.
      %%_THUMBNAIL_PAGE_%%	The URL to the thumbnail view of the gallery.
      %%_DETAIL_PAGE_%%	The URL to the detail page of the first image in the gallery.
      %%_PREVIOUS_LINK_%%	The URL to the detail view of the previous image in the gallery.
      %%_NEXT_LINK_%%	The URL to the detail view of the next image in the gallery.
      %%_IMAGE_SOURCE_URL_%%	The URL to the image to display (for displaying the image in an <img /> tag).
      %%_CAPTION_%%	The caption that has been entered for the image.
      %%_CREDIT_%%	The credit that has been entered for this image. If no credit has been entered, the credit that is displayed is that specified in the 'DefaultCredit' attribute.
      %%_URL_LINK_%%	The URL for the link that has been entered for this image, if there is one.
      %%_URL_TEXT_%%	The text for the link that has been entered for this image, if there is one.
      %%_THIS_IMAGE_NUMBER_%%	The number of this image within the gallery.
      Thumbnails_ContentBeforeThumbnails and Thumbnails_ContentAfterThumbnails
      %%_GALLERY_FOLDER_NAME_%%	The name of the folder that the gallery resides in.
      %%_GALLERY_THEME_%%	The theme that has been entered for the gallery.
      %%_GALLERY_DATE_%%	The date that has been set for the gallery.
      %%_GALLERY_DESCRIPTION_%%	The description that has been entered for the gallery.
      %%_NUMBER_OF_IMAGES_%%	The total number of images that are in the gallery.
      %%_ALL_GALLERY_LIST_PAGE_%%	The URL to the list view of the gallery.
      %%_GALLERY_DETAILS_PAGE_%%	The URL to the detail view of the gallery.
      Thumbnails_ImageHtml
      %%_IMAGE_DETAIL_PAGE_URL_%%	The URL to view the image in the detail view.
      %%_IMAGE_URL_%%	The URL for the thumbnail image (for displaying the image in an <img /> tag).
      %%_IMAGE_CAPTION_%%	The full caption that has been entered for the image.
      %%_IMAGE_SHORT_CAPTION_%%	A short version of the caption that has been entered. The full caption will be truncated to the length specified in the 'Short_Caption_Length' attribute.

      Example

      The file that can define custom templates for a slideshow display application could look like this:

      <!--- ########################################################### --->
<!--- TEMPLATES FOR THE LIST DISPLAY --->

<cfsavecontent variable="Slideshow_CustomListTemplate">
<a href="%%_THUMBNAIL_PAGE_%%"><img src="%%_FIRST_THUMBNAIL_URL_%%" border="0" align="left" /></a>
&nbsp;&nbsp;
%%_GALLERY_DATE_%%
<br />%%_NUMBER_OF_IMAGES_%% Images
<br />
%%_GALLERY_DESCRIPTION_%%
<br /><br />
</cfsavecontent>

<!--- ########################################################### --->
<!--- TEMPLATES (and VARIABLES) FOR THE THUMBNAILS DISPLAY --->

<cfset Slideshow_Thumbnail_NumberOfColumns = 5>

<cfsavecontent variable="Slideshow_ContentBeforeThumbnails"></cfsavecontent>

<cfsavecontent variable="Slideshow_RowStartHtml">
<p class="gallery">
</cfsavecontent>

<cfsavecontent variable="Slideshow_ImageHtml">
<a href="%%_IMAGE_DETAIL_PAGE_URL_%%" title="Click the picture to see a larger version.">
<img src="%%_IMAGE_URL_%%" alt="" border="0" /></a>
</cfsavecontent>

<cfsavecontent variable="Slideshow_NoImageHtml"></cfsavecontent>

<cfsavecontent variable="Slideshow_RowEndHtml">
</p>
</cfsavecontent>

<cfsavecontent variable="Slideshow_ContentAfterThumbnails"></cfsavecontent>

<!--- ########################################################### --->
<!--- TEMPLATE FOR THE DETAILS PAGE --->

<cfsavecontent variable="Slideshow_CustomDetailsTemplate">
<a href="%%_THUMBNAIL_PAGE_%%" style="font-weight:bold;"><strong>Back to Thumbnails</strong></a>
<p align="center">
<img src="%%_IMAGE_SOURCE_URL_%%" alt="" />
</p>

<p align="center">
<a href="%%_PREVIOUS_LINK_%%"><img src="/cvpa/images/back.gif" alt="" width="45" height="27" border="0" /></a>
<a href="%%_NEXT_LINK_%%"><img src="/cvpa/images/next.gif" alt="" width="45" height="27" border="0" /></a>
</p>
</cfsavecontent>

      These could then be used with the custom tag like so:

      <--- Include the file that defines the templates --->
<cfinclude template="#APPLICATION.path#includes/gallery_templates.cfm">

<--- Call the tag, using the defined templates --->
<cf_slideshow GalleryRoot="#APPLICATION.GalleryRootPath#"
Custom_List_Template="#Slideshow_CustomListTemplate#"
Thumbnail_NumberOfColumns="#Slideshow_Thumbnail_NumberOfColumns#"
Thumbnails_ContentBeforeThumbnails="#Slideshow_ContentBeforeThumbnails#"
Thumbnails_RowStartHtml="#Slideshow_RowStartHtml#"
Thumbnails_ImageHtml="#Slideshow_ImageHtml#"
Thumbnails_NoImageHtml="#Slideshow_NoImageHtml#"
Thumbnails_RowEndHtml="#Slideshow_RowEndHtml#"
Thumbnails_ContentAfterThumbnails="#Slideshow_ContentAfterThumbnails#"
Custom_Detail_Template="#Slideshow_CustomDetailsTemplate#" />

      An approach like this is especially useful if the tag will be called on different pages where the templates will be the same. Happy hunting!