Overview#

Brian's jspWiki ~PhotoCollectionPlugin is a subclass of WikiPlugin. It generates virtual hyperlinks (i.e. "why not create this page?") in wiki pages as their parent pages are created. These links will map the natural directory structure of an existing (updateable) photo collection of arbitrary depth and width.

To start using the plugin, you only need to create a wiki page for the root of your ~PhotoCollection (and, of course, the associated jspwiki-custom.properties entries described below). The plugin will do the rest of the hard work for you while you add narrative to each photo folder and (only if you want!) each individual photograph. You can create new wiki pages or add extra narrative to existing pages whenever it suits you, and your narrative will automatically and immediately become available to the ~JSPWiki search engine! If you add a new photo or folder to your collection, the plugin will detect it and update its hyperlinks as soon as you refresh the wiki page associated with the parent folder.

Your root wiki page for your photo collection needs to have (at minimum) the following code somewhere within it:

[{INSERT PhotoCollectionPlugin photodir='/'}]

When this root wiki page is displayed, the plugin will execute and generate a list of hyperlinks that represent the top-level folders in your collection.

By default, folders are sorted with the oldest first. This is usually what you want with a folder that contains photos, but not for a folder that contains other folders. I need to sort my own top level list of directories by name, e.g.

[{INSERT PhotoCollectionPlugin photodir='/' sortmethod='name'}]

Valid "sortmethod" values are: name, newdate, and date (the default value). Remember that whenever you update the contents of a folder, the file system date of that folder will change. Because I want my photo collection folders to remain in a predictable order, even after I've modified their contents, I make sure they are named appropriately and sorted by name (e.g. 04-france).

If a subdirectory or an image file in your collection already has a wiki page associated with it, the plugin will automatically generate a hyperlink to that wiki page. However, if the corresponding wiki page does not yet exist, it will generate a hyperlink to create the new page. If you click on that hyperlink, you will start to edit the new page which will already have been seeded with correct the plugin invocation to generate hyperlinks for all of its contents. Simply add some narrative to the new page and save the contents... and you will immediately see hyperlinks for all the folders and/or photos in that folder!

The wiki page names are derived from the relative filesystem paths to the folders and photos, which makes them unique. However, the first part of these paths will usually be constant, so the page names will be unnecessarily cluttered. The plugin has an optional feature to remove (or alias) the constant part of the path from each page name when it is displayed, even though the full derived name is used to save and access it in the page store.

Although the current version of the plugin cannot create thumbnails of the photos, it will use them if they exist in a suitable parallel file structure. This can dramatically speed up the display of pages that contain many images although, by default, the plugin will work with just the image files.

---

Getting Started - Basic Installation#

You should get a simple system working first. After you are comfortable with the basic features of the ~PhotoCollectionPlugin, you can start to enable its optional features to customise the way the plugin handles your photo collection.

Environment#

You really must have jspWiki working properly before you start incorporating your photo collection. You should be able to create a main page and a link to a subordinate page to confirm you have it set up properly. If you want any access controls, get those working properly too!

Webapp access to photo collection#

I assume that you already have a directory hierarchy for your photo collection. The PhotoCollectionPlugin will generate url's that point directly to your image files, so they MUST be able to be found within your webapp container, otherwise the client browsers will not be able to request them for display. However, in most cases it would be desirable to keep your photo collection folders outside the web server's part of the file system. This is possible with a linux system, but I don't know how to do it with windows.

To test the plugin, you can simply copy a few of your photos into the webapp container, e.g. ../files/. With unix systems, you can define a symbolic link to your collection as follows:

e.g. ln -s /home/shared/pictures/ /opt/apache-tomcat-5.5.27/webapps/wiki/files/pictures

If you are using Tomcat, you need to permit it to follow symbolic links that lead out of the webapp container. You need to assign the allowLinking="true" attribute to the Context element. I found that defining a META-INF/context.xml file did not enable traversal of symlinks on my system - possibly because my Host is configured to auto-deploy webapps. I had to create a $CATALINA_HOME/conf/context.xml file that permitted ALL webapps to follow symbolic links.

Making the plugin available to jspWiki#

The photocollection.jar file is not currently shipped with jspWiki, so you need to copy it to the jspWiki WEB-INF/lib/ directory.

jspWiki properties#

You only need to add a definition for photoCollection.collection.base to your WEB-INF/jspwiki-custom.properties file to get the plugin working in its most basic mode. This is the file system path to the root folder that holds your photo collection. This path must be relative to the webapp container! (e.g. the relative path of the symbolic link to the root of your collection). Obviously, your web server must have read access to this root folder and all of its subordinates. There is no harm defining this property early, because it will not be used until you save a wiki page that contains a call to the PhotoCollectionPlugin.

Cascading Style Sheet extension#

The plugin uses some additional CSS styles that are not part of the jspWiki style sheet. Download the file that defines these additional styles. You can simply paste them at the end of your existing templates/defaults/jspwiki.css file, but there is a better way to achieve the same result...

Create a new folder, e.g. templates/photoCollection/, and copy the default jspwiki.css file into it. The append the additional styles to the new copy. Finally, tell jspWiki to use the new stylesheet by adding the name of the new folder (e.g. photoCollection) to the jspwiki.templateDir entry in your jspwiki-custom.properties file.

---

Optional Features#

Multiple Image Types#

The default is to manage a collection containing jpeg and png images (file types JPG, JPEG, PNG), so there is no need to do anything unless you have other types of image files. The file types are matched in a case-insensitive manner, so there is no need to specify lower-case alternatives. The plugin can manage a collection of multiple file types - you only need to tell it what to treat as an image file. If you have a small number of directories with mixed types, simply add the desired types to the plugin invocation in your wiki page source, e.g.

[{INSERT PhotoCollectionPlugin photodir='/' phototype='png, jpg'}]

However, if you intend to support multiple image types throughout your collection, it will be simpler to add photoCollection.default.phototype to your WEB-INF/jspwiki-custom.properties file. This property defines a comma or white-space delimited list of filetypes that are to be treated as images.

Friendly Page Names#

If you are running the basic installation, you will have undoubtedly noticed that the the wiki page titles of your photo collection (in large bold face letters) are all prefixed in the same way - they start with the collection root filesystem path, e.g. ~FilesPictures200904-garden and ~FilesPictures200905-myHoliday. In other words, the url's of these pages must be unique within the webapp container, but the default jspWiki behaviour is to use the url file path component as the wiki page name and also as the visible title of the page.

You might feel (like me) that prefixing the bold face visible title of every wiki page in your collection with the same file system root path is distracting. If so, you can add photoCollection.collection.alias to your WEB-INF/jspwiki-custom.properties file.. This property defines a text string which will replace the value of photoCollection.collection.base in your photo collection page titles. Note: this feature is entirely cosmetic because it does not alter the unique names and url's assigned to your photo collection wiki pages. Note: this feature only applies to wiki pages in your photo collection, so all other wiki pages will continue to have their normal titles.

Unfortunately, with this version of the plugin, you need to some more work because it is not integrated into the jspWiki distribution... The photocollection.jar file includes its own taglib containing an enhanced version of the pagename tag class. However, the default jspWiki jsp's will not use it unless they are modified. The best way to achieve this change is to create a very simple skin that invokes the new tag class.

Assuming that you have already created a new template directory for your modified css (described earlier: i.e. your WEB-INF/jspwiki-custom.properties file must also define your new jspwiki.templateDir), then copy templates/default/Header.jsp to your new template directory. Edit this new copy by changing the line

<div class='pagename'><wiki:PageName /></div>

to

<div class='pagename'><photo:PhotoPageName /></div>

When you restart jspWiki, your photo collection wiki page urls and content will remain unchanged, but their titles will be more attractive, e.g. my folder page ~FilesPictures200904-garden has a nicer title of Photos 2009 04-garden.

Thumbnails#

When a client browser displays a wiki page associated with a folder of images, its default behaviour is to display small versions of each image. Unfortunately, the browser still has to download the individual image files (a megabyte or more for each image) before it can scale them down to the desired size. This can cause slow page loads, particularly over slow communications links. To make matters worse, the browser will purge the large images from its cache more quickly, thus forcing further slow reloads of the same page.

The current version of this plugin does not generate thumbnail files for its images, but it does have sufficient logic to detect the presence of thumbnails within the collection and use these much smaller files for pages that do not require the full-size images.

The current logic is rather primitive. It assumes you have a consistent scheme for naming and locating thumbnails relative to the corresponding full-size images. You need to express this relationship in terms of the following optional plugin properties:

• photoCollection.default.thumbspath defines the relative path from the directory that holds the original image to the directory that holds the thumbnail file.

• photoCollection.default.thumbspfx defines the prefix to be appended to the filename of the original image file to produce the name of the corresponding thumbnail file.

• photoCollection.default.thumbssfx defines the suffix to be appended to the base filename (i.e. prior to the DOS-style filetye) of the original image file to produce the name of the corresponding thumbnail file.

e.g. a thumbspath of ".thumbs", a thumbsprefix of "200-" and a a thumbssuffix of "0-thumb" provided to the plugin when generating a url of files/pictures/2009/holiday/P0000001.JPG would cause it to search for a thumbnail called files/pictures/2009/holiday/.thumbs/200-P0000001-thumb.JPG. If it finds the thumbnail file exists, then it substitutes the url for the thumbnail - otherwise it uses the url of the original image (in other words, you do not need to have thumbnails for all of your images).

Note: if you have a collection containing multiple image types, the thumbnails MUST be of the same type as their corresponding full-size image files.

---

FAQ#

• Does the plugin support multiple photo collections? No. The best I can suggest is to make a directory called files/pictures/ and populate it with symlinks to your individual collection root directories.
• I have setup my photo collection, but why does a search on "holiday", not find the folder called "2009/04-holidays"? The jspWiki search engine only knows about the wiki pages that exist, not those you might create in the future! Once you've clicked on the "create page" hyperlink for your "04-holidays" folder and saved the content, the name of the page will become visible to the search engine. You can even search on substrings, e.g. the search engine will match "holiday" against a page containing the text string "holidays".
• I haven't got any thumbnails of my images, so how can I get some? The imagemagick and graphicsmagick-imagemagick-compat packages can do this for linux users. (I've been using the ginp project to manage my photo collection and it automatically creates thumbnails for me).

~ToDo List#

• generate a thumbnail on the fly if one does not already exist.
• nicer boxes around thumbnails and better layout and resizing capability.
• thumbnail caption text should be less cluttered (show the simple title and use mouse-over event to reveal the whole url).
• subfolder caption text should be less cluttered (show the simple title and use mouse-over event to reveal the whole url).
• full image display should contain a hyperlink back to the parent folder wiki page.

---

Category.Plugins