About XSLT-Gallery™

Normally, something like XSLT-Gallery™ requires a server.  Not here.  All you need are a XSLT 1.0 compliant brower like Firefox 8+.  That is how I use it.  I developed it mainly for personal offline use.  If you decide to use it on a server, great.  In fact, please let me know of such uses.  But I didn't develop it for that.  There are systems for servers like the Codex gallery system.  What I wanted was much lighter and simpler.

Notes:

• I am really only satified with the way it works with Firefox 8.  Newer versions of Firefox as well as other Gecko-powered browsers should do nicely.  Those would include Seamonkey, Camino, and more.

  As for other browsers, I have only tested IE9 and Chrome 15.  IE9 displays the pages, but has problems with the formatting.  It looks like it can't properly display the inline lists I used.  If you can put up with tables, it is possible to modify the XSL and CSS to use tables.  But I won't help.>  Chrome, on the other hand, won't display anything but a blank page.  I don't know if it even supports XSLT.

  I personally have no interest in supporting browsers other than Firefox.  But if you want to help out there, let me know in in the Join the project forum.

• Even with Firefox 8, the transformation process can be rather slow.  I am hoping Mozilla speeds it up in future versions.  If you think the nightly, Aurora, or Beta versions speed it up, please let me know in the Project Discussion forum.  Be sure to mention which version.

• No browser yet supports XSLT 2.0.  If Firefox 8 did, I would add some code that picked thumbnails for each gallery by random from all the thumbnails in that gallery.  Also, the process of escaping filenames would be faster.

• Your file system may pose limits on the length of item names as those names are the same as the names of folders (for galleries) and files (for images).  However, my personal preference is to keep names no longer than the maximum width of your thumbnails.  By default, that is 160 pixels.

• Your file system might allow characters that aren't allowed in XML like “Ω”.  However, I haven't had much success with those.

• The system itself is completely portable.  It will work anywhere you have a XSLT 1.0 compliant brower.  However, I currently provide batch files for Windows NT flavors such as Windows Vista.  This is because the files require CMD.exe which only comes with Windows NT 3.52 and up.  Those using Apple computers, Unix, and Linux are out of luck.  Those running Windows 95, 98, or ME are also out of luck as the CMD files require mklink.exe which only cames with Windows Vista and up.  (Older versions of NTFS only supported a less capable version of mklink.exe.)  The CMD also requires your files be a partition that is at least NTFS 4.0.

• In theory, videos can be included in galleries.  However, Firefox 8 doesn't allow you to use scripts (which would probably include videos) from file:/// urls.  So I don't bother.  All my entries are photos.  It is conceivable that HTML5 video tags might work, but otherwise, you will probably need to do without videos.

• Because all my files are photos, I didn't bother with icons for the types of images.

File description

Change these as you see fit.  I may create a gallery of custom versions of the system.

• gallery.xsl — The core of the system.  It turns the XML into XHTML for display by your browser.

• GallerySystem.xsd — The Schema file for a gallery file.  Normally, you would use the one at http://wlps-ge-stuff.ucoz.com GallerySystem.xsd.  However, if you decide to create a custom version of the format, you will want to create a custom XSD file.

• GalleryStyle.css — Plain CSS file that works with the XHTML generated by the XSL file.  Yeah, it is plain, but I personally prefer it that way.  Modify as you see fit.  Note: If you don't prefer the stock version, you will want to change line 33 (currently) in the XSL to point to your version.

• Gallery.svg — Used to mark uncategories galleries.  Looks like this ⇒ .

• Other Gallery.svg — Starter category image for galleries.  Change it or throw it away as you see fit.  I actually don't use it as I have other categories. Looks like this ⇒ .

• make gallery parent.cmd — This is how I create a gallery folder that doesn't have its own images.  The main thing it does is call mklink.exe to create the symbolic link.  Without this, Firefox 8 won't use the XSL file!  To use it, use your platform's command line to set the current directory to the root of your gallery folder struture.  Then call make gallery parent.cmd with the relative path of the gallery to add.  Be sure the subfolder exists already.  If you use another platform which has symbolic links, but doesn't have mklink.exe, you will need to either replace or modify this file.  If you use a platform that doesn't have symbolic links, you will need to copy the XSL to every single folder you use as a gallery.

• thumbnail folder.cmd — Unlike make gallery parent.cmd, this CMD file also calls ImageMagick's mogrify.exe to thumbnail all JPEG files.  See the notes inside the file regarding where mogrify.exe can be found.  To use it, use your platform's command line to set the current directory to the root of your gallery folder struture.  Then call thumbnail folder.cmd with the relative path of the gallery to add.  Be sure the subfolder exists already.  If you use another platform which has symbolic links, but doesn't have mklink, you will need to either replace or modify this file.  If you use a platform that doesn't have symbolic links, you will need to copy the XSL to every single folder you use as a gallery.  If you want to include images other than JPG files, or your photos have the extension .JPEG, you might want to modify this file to reflect that.  If you want to include videos in your galleries, you may want to supplment or replace mogrify.exe with another tool.

Struture of the gallery XML files

There are several types of possible XML files involved.  I am showing the struture in visual manner.  All files must be named index.xml unless you change line 20 of the XSL.

• page — This is the file's root and has one possible attribute: type.  The intial XSL file defines two possible values: sub-gallery (line 25) and other-gallery (line 26).  If you want to change those, go ahead.  You will also want to be aware of the xsl:choose sections on lines 170 through 202 and lines 233 through 253.  If you need more categories, you will need to modify those sections.  If you don't, the XSL will issue errors.  The file in your gallery root must have type set to “root”.  Do not use the “root” value for any other gallery.  The XSL builds the bread crumb trail in the header by stepping up through your gallery folder struture.  The root doc type helps the XSL detect the root gallery has been reached.

  • title — This element is required and has no attributes.  Please don't add extra title tags or provide duplicates of any of its contents.

    • current-page — This element is required and has no attributes.  Set it's value to the gallery name.  This doesn't have to be the same name you use in for the gallery's folder name.  Use CDATA if needed.

    • starring — This element has no attributes.  Set its value to what ever you want.  It can be omitted.  Basically, it serves as a auxillary page title and is appended to the contents of your current-page tag.

    • gallery-title —  This element has no attributes.  Set its value to what ever you want.  It can be omitted.  It also serves as a auxillary page title and is appended to the contents of your current-page tag, only surrounded by “‘” and “’”.

  • gallery — This element has no attributes and is required.  It is the counterpart of HTML's body tag.  Please don't provide more than one.

    • subgallery — Generates a link to a subgallery.  Use as few or as many as you want.  It has one required attribute, name, which should be the name of the subgallery's folder.  That name will be shown in the list and used to generate a link to the index.xml file for that subgallery.

    • gallery-entry — Generates a link to one of your images.  Use as few or as many as your want.  It has one required attribute, name, which should be the name of the image minus the filename extension.  So if the image is “my image.jpg”, use “my image”.

    You can safely mix subgallery tags with gallery-entry tags in the same gallery.  Personally, I don't have a use for it, but it will work.

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="gallery.xsl"?>

<!-- Sample root file -->

<page xmlns="http://wlps-ge-stuff.ucoz.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://wlps-ge-stuff.ucoz.com GallerySystem.xsd" type="root">
	<title>
		<current-page>
			Main
		</current-page>
	</title>

	<gallery>
		<subgallery name="Gallery 1" />
		<subgallery name="Gallery 2" />
	</gallery>
</page>

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="gallery.xsl"?>

<page xmlns="http://xslt-gallery.sourceforge.net" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xslt-gallery.sourceforge.net GallerySystem.xsd" type="sub-gallery">
	<title>
		<current-page>
			Mammals
		</current-page>
	</title>

	<gallery>
		<subgallery name="Cats" />
		<subgallery name="Prairie Dogs" />
		<subgallery name="Dogs" />
	</gallery>
</page>

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="gallery.xsl"?>

<page xmlns="http://xslt-gallery.sourceforge.net" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xslt-gallery.sourceforge.net GallerySystem.xsd" type="other-gallery">
	<title>
		<current-page>
			Bees
		</current-page>
		<starring>
			Future moths and butterflies
		</starring>
		<gallery-title>
			My title
		</gallery-title>
	</title>

	<gallery>
		<gallery-entry name="One caterpillar" />
		<gallery-entry name="Caterpillar 2" />
		<gallery-entry name="Monarch Caterpilar" />
	</gallery>
</page>

How to use

This is divided into two parts.  The first part is how to set up your folder struture and XML files.  You then need to know how to browser your galleries.

Setup

1. Copy the files in the download folder to your gallery's root folder.
2. Organize the photos (or other images) as you see fit.
3. Decide on your categories.
4. Modify the categories listed in lines 25-26, 170-202, and 233-253 of the XSL.
5. Create some category icons to replace Other Gallery.svg.
6. Replace lines 74-78 with classes that use your new icons.  The selectors should follow this pattern shown below.

   a.my-class-gallery > img

7. Reference your new CSS class(es) in the portions of the XSL that are now lines 170-202.

At this point, you are ready to begin making your XML files.  I suggest starting with the samples above until you have some you like.  Everything after this is mainly just a suggestion.  It also assumes you are able to use the CMD files.

8. If the gallery you are working on has some images, run thumbnail folder.cmd.  Otherwise, run make gallery parent.cmd.
9. If the gallery you are working on isn't the root gallery, set the type attribute.  If it is the root, be sure the value is “root”.
10. Set the title of the gallery in the current-page element.
11. If you want starring or gallery-title elements, add those.
12. Begin adding entries.  Rember, don't include the filename extensions for your filenames.
13. Test the gallery as shown below.  Note: Some thumbnails won't be present until you have your subgalleries in place.  This is because the XSL looks to the XML files for those galleries to get the thumbnails to display.

View the gallery

Simply open the XML file for your root gallery in your browser of choice.