XML Photo Album

XML Database Format

For those advanced users or non-Windows users who wish to edit or create displayable XML databases without using the Album Generator, here is an explanation of the setup that we use. Each album directory contains the album.xml file which contains the data, the index.xml file which is the start page, the subdirectory 'files' which contains all the other display files (.css, .xml, .xsl, .html), and the 'images' subdirectory which contains the photo image files. The album.xml database which contains all the data is in the following format.

<album title="Sample Album" numPhotos="6" useIsoDates="true" dateDisplay="MMM d, yyyy" thumbs="images" images="images" copyLocal="false" storeAddDate="true" theme="default-es" themeVersion="1.7.0" downsampleResolution="1152,864,65" xmlns="http://xmlalbum.sourceforge.net/xmlalbum.xsd">

The top-level node of each XML album is called 'album,' with the required attributes 'title' and 'numPhotos', and optional attributes 'dateDisplay' 'images', 'thumbs', 'storeAddDate', 'useIsoDates', 'copyLocal', 'theme', 'themeVersion', and 'downsampleResolution'. The XML namespace declaration is also required, but must be last or else Opera bugs out.

• The album title is displayed on the album index page.
• The 'numPhotos' attribute tells the display program how many photos are in the database.

• The 'useIsoDates' attribute tells the generator GUI whether this album stores dates in ISO-8601 format. If it is absent or is set to "true", ISO dates will be used in the XML. Otherwise, the local date format will be used.
• The 'dateDisplay' attribute is a format specifier for the display date (applied only to dates stored in ISO format). If this attribute is not present, dates will be displayed in the viewer's local date format.
• The 'thumbs' attribute tells the index page where to look for the thumbnails. If not present, the images folder is used.
• The 'images' tag sets the images folder. If not present the default is set to "images".

The following options store settings used by the Album Generator GUI and do not affect the display:

• The 'copyLocal' attribute tells the generator GUI whether newly-added images should be copied to the images folder (value of "true" or absent) or should be referenced at their original locations (value of "false").
• The 'storeAddDate' attribute tells the generator GUI whether to record the the <addDate> tag for new items added to this album (see below). If it is missing or set to "false" this option is turned off.
• The 'theme' attribute tells the generator GUI which web display theme is being used for this album. If absent, the display theme "default" is being used.
• The 'themeVersion' attribute tells the generator the version number for the display theme, so that the generator can determine whether the display files need to be updated. If absent, the generator will assume that an update is necessary.
• The 'downsampleResolution' attribute stores the three numbers used by the downsampling option in the GUI: maximum image width, maximum image height, and JPEG compression quality. If absent or blank, no downsampling will be applied.

<photo id="1">

Each photograph is represented by a second-level node called 'photo' with the attribute 'id.' The id determines the order in which the photos will be shown. Photos should appear in the XML database in the order that they should be shown, with sequential id numbers. The data for each photograph is represented by the following third-level nodes.

<title>Blackcomb Mountain from <i xmlns="http://www.w3.org/1999/xhtml">Whistler Mountain</i></title>

The title of the photograph; identifies the photo on the index page and navigation bar, appears above the photo in display. This field may contain any XHTML (that is legally contained in a <p> block). The xmlns attribute is mandatory on such tags. Only <b>, <i>, and <em> tags are supported by the album generator.

<image ref="../movies/P1000354.mov" height="1200" width="1600">P1000354.JPG</image>

or

<image height="1200" width="1600" thumb="P1000354.JPG">../bestPhotos/P1000354.JPG</image>

The path to the image file, relative to the images folder (if it is in the image folder, as is usually the case, this string will simply be the filename). The 'ref' attribute is optional. If present it is a link (executed from the '/files' folder) for the image to point to. This is useful if you want to include movies in the album. The 'height' and 'width' attributes, also optional, are used by the XSL to determine whether an image needs to be resized to fit in the browser window. If both attributes are present then the display files check the aspect ratio, and if it is too wide limits the width of the image instead of the height, since horizontal scrollbars are evil. The optional 'thumb' attribute gives the name of the corresponding thumbnail file, should it differ from the name given in the value of the image node. This generally happens only when the image is stored somewhere other than the images folder, and thus has some relative path stored in the image node in addition to the filename.

<caption>It's a beautiful day to be skiing...</caption>

The caption, which appears at the bottom left of the photo in display. Like the title element, the caption may also contain XHTML tags with the namespace declaration included. Only <b>, <i>, <em>, and <br /> tags are supported by the album generator.

<location>Whistler, British Columbia</location>

The location, which appears at the bottom right of the photo in display.

<date format="iso-8601">2004-12-27 17:35:22</date>

or

<date format="custom">December 2004</date>

or

<date>December 27, 2004</date>

The date the photo was taken; displays at the bottom right of the image under the location. By default this is stored in the ISO-8601 YYYY-MM-DD hh:mm:ss format (time included for better chronological sorting), with the 'format' attribute set to 'iso-8601'. The display files automatically convert the ISO date to the format specified in the dateDisplay attribute on the album node, or to the viewer's local date format if no dateDisplay attribute is specified. If the exact date was unknown or the user wanted to enter a date in some other format for some other reason, the date node will have the format="custom" attribute. If ISO date format is turned off, the date will be stored in the OS-local time format by the Album Generator, and there will be no attribute present. Except for the ISO case, the date will be rendered exactly as written in the XML.

<photographer>Adam Azarchs</photographer>

The photographer's name; appears at the bottom right of the image below the date.

<addDate>11/07/2005</addDate>

This tag stores the date when the an item was added to the album. This information is not recorded unless the Album Generator is set to do so (off by default). Note that this information is not displayed anywhere unless you make modifications to the XSL.

Any of these fields may, of course, be left blank if the information is unknown. For use by other programs, we also provide a machine-readable schema definition. To see how it all fits together, view the XML file which contains the data for the Sample Album. To change the data content, only this XML file needs to be changed; all the other files which generate the display are static and simply reference the album.xml file.