Photos Taglib and Filter
The Photos taglib / filter is my attempt to create simple photo galleries and slideshows in JSP pages without much coding. (This project was recently called Moss Gallery, but was renamed when the scope has expanded.) It also lets you secure high quality images, and only display lower quality versions, if desired; this can help combat unauthorized image duplication. For the slideshow, I use a simple javascript to fade between images in a loop. For the image gallery itself, I use Lightbox 2 scripts to show larger versions of thumbnails.
How to Use this Component
This is one of the most complicated, but also the most powerful, of the Moss J2EE components. Because it includes both taglibs as well as filters, it is recommended that you have a good understanding of JSP web applications before using it. If you need assistance setting this (or other) components up, I am available on a consulting basis to assist.
Dependencies
This filter relies on the following libraries:
Installation
To use this component, you must include the .jar file (plus any dependencies) in the web application's classpath (either in WEB-INF/lib or in the server's lib folder). You must then add the following code to the web.xml file:
<filter>
<filter-name>ImageFilter</filter-name>
<filter-class>ca.digitalcave.moss.jsp.gallery.ImageFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>ImageFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
To add a gallery to a given page, you must first include the taglib definition at the top of your JSP:
<%@ taglib prefix="p" uri="/photo-tags" %>
You must then include the 'p:header' tag in the HTML header, and the 'p:gallery' or 'p:slideshow' tags where you want the gallery or slideshow to display. See the following code for a simple example:
<%@ taglib prefix="p" uri="/photo-tags" %>
<html>
<head>
<title>Sample Gallery Page</title>
<p:header>
</head>
<body>
<p:gallery packageName="/MyGallery" thumbSize="210" fullSize="700" showTitle="true"/>
</body>
</html>
<%@ taglib prefix="p" uri="/photo-tags" %>
<html>
<head>
<title>Sample Gallery Page</title>
<p:header>
</head>
<body>
<p:slideshow packageName="/MyGallery" center="true" random="true" size="-200"/>
</body>
The gallery tag allows the following attributes:
- packageName <string> (required): This is the folder name where your pictures are located, relative to the WEB-INF/galleries folder.
- thumbSize <integer>: Define the size of the thumbnail images. This value determines the size of the thumbnail diagonal cross-section (with a bit of an adjustment factor included to ensure that very long / tall images are not completely out of proportion to other images). Defaults to 128 if not specified.
- fullSize <integer>: Define the size of the full images. Uses similar calculations as the thumbSize does. Defaults to 800 if not specified.
- thumbQuality / fullQuality <integer>: The JPG compression ratio for the thumbnails and full images, respectively. Valid numbers are between 1 and 100. Defaults to 50 and 75.
- showTitle <boolean>: This determines if the title (file name) be shown below the image. Defaults to false.
- includeLink <boolean>: This determines if clicking on the thumbnail should link to the full version of the image, using Lightbox 2. Defaults to true.
- showFullQualityDownload <boolean>: Should a link be included underneath the image which allows people to download a full sized version of the image. This can be useful if you wish to show a copy of the image which fits on a user's screen, but you still wish to allow users to download the full sized version as well, for instance to print. Defaults to false.
- matchRegex / excludeRegex <string>: These two regular expressions determine which files are matched in the gallery package. This defaults to show commonly used image formats, such as jpg, png, etc, and to not show hidden (dot) files. You probably won't need to change these attributes.
The slideshow tag allows the following attributes:
- packageName <string> (required): This is the folder name where your pictures are located, relative to the WEB-INF/galleries folder.
- size <integer>: Define the size of the slideshow images. There are three options for this: size is greater than 0, size is exactly 0, size is less than 0. If the size value is set greater than zero, then the slides are scaled to this value (the value approximately maps to the length of the hypotenuse of the image, just as it does for the gallery images). If the size value is equal to zero, the full image size is used. If the size is less than zero, the image is scaled to fit the screen height of the client browser, less the value specified. Defaults to -100 (100 pixels smaller than the client browser screen height) if not specified.
- random <boolean>: Shuffle the images, so that they are looped through randomly each page load. Defaults to false if not specified.
- center <boolean>: Center the images using javascript. You may need to define additional CSS offsets for the parent container div to specify additional offsets. Defaults to false if not specified.
- quality <integer>: The JPG compression ratio for the slide images. Valid numbers are between 1 and 100. Defaults to 85.
- fadeSpeed / photoSpeed <integer>: How long (in milliseconds) to take to fade in and out, and how long to show each image in the slideshow before changing to the next one. Defaults to 500 / 4000 respsectively.
- matchRegex / excludeRegex <string>: These two regular expressions determine which files are matched in the gallery package. This defaults to show commonly used image formats, such as jpg, png, etc, and to not show hidden (dot) files. You probably won't need to change these attributes.
Configuration
For security to ensure that visitors to your site cannot download only images which you have specified, at the desired resolution / quality, you must define a settings.xml file within each package in WEB-INF/galleries/*. This file specifies the maximum and minimum size and quality for images in your galleries, as well as whether or not full quality (byte-for-byte copies of the source images) downloads are allowed. This can prevent people from downloading high quality versions of your images by manually typing in the URL. Make sure that you don't set these values to be lower than the values you define in fullSize/fullQuality and thumbSize/thumbQuality (in the gallery tag), as this value will take precedence over the tag attributes. If you have enabled showFullQualityDownload (gallery tag) or size == 0 (slideshow tag), the full quality images will be copied byte-for-byte from the source image, as long as this is enabled in the settings.xml.
These restrictions are defined in a file called settings.xml, located in each gallery. For instance, put the following file in WEB-INF/galleries/MyGallery/settings.xml to prevent downloading anything larger than 1000:
<?xml version="1.0"?>
<settings>
<size max="1000" min='50'/>
<quality max='85' min='5'/>
<full-quality allowed='true'/>
</settings>