The first time you run cphoto the cPhotoConfig.xml configuration file and templates directory are created in your HOME directory. On Windows this is usually something like c:\Documents and Settings\name\.cphoto. On Unix this is your ~home directory.

cphoto configuration file

The cPhotoConfig.xml file is one of the files you can edit to change options used to generate the photos and HTML. I'm still working on the format of the configuration file so some of the things in it shouldn't really be there since you aren't likely to change them. Nevertheless here's a list of the sort of things you can modify by editing the configuration file:

  • Number of rows|columns that appear on an album page.
  • Number and size of smaller photos created for each album.
  • Specify a list of images to ignore.
  • Specify the default thumbnail width and height.
  • Specify the sort order of photos and albums.
  • Specify the default thumbnail width and height.
  • Change the copyright text shown at the bottom of pages.
  • More details on these options can be found config.

template files

Several template files are used to generate the HTML. These templates are found in your HOME/templates directory. The template files consist of XML pairs for each part of the page. For example, the <albumHeader> tag is used to generate the header for albums. Use the CDATA section to embed HTML - see the template files for examples.

The ten template files are:
  • album.xml - used to generate album pages
  • cal.xml - used to generate the "photos by year" page. Like the index.html for the year view.
  • image.xml - used to generate the individual image pages
  • image.xml - used to generate the individual image pages
  • imageYear.xml - used to generate the individual image pages used by the year view
  • prettyCalendar.xml - used to generate the year calendar
  • shared.xml - templates which are commonly used by more than one of the above files, via the {foo} template include mechanism. They typically contain HTML page headers, the HTML for navigation icons, etc.
  • tree.xml - used to generate the "tree" page
  • whatsnew.xml - used to generate the "WhatsNew" page
  • yearAlbum.xml - used to generate the list of photos for a year

In the first three of these files, text to be replaced appears inside brackets, [ and ], and should be upper-case. For example, in image.xml, the text [TITLE] will be replaced with the title of the image for which the page is being generated.

Templates may recursively include other templates using curly braces. For example, a template foo may include within itself the contents of a template bar by referencing it as {bar}.

The best thing to do to get a feel for the template files is to take a look at them yourself.

The configuration file contains three basic sections: imageCategories, options and photofields:


cphoto creates smaller versions of each of the photos that you want to appear in your albums. By default, it creates a small image of 320x200 pixels, and a medium image of 640x480 pixels. If most of your images are very small (or maybe very large) you may want to tweak these sizes a bit, or even introduce some new sizes altogether.

Each image category has six attributes:
  • type - the internal name of the image category.
  • label - the short label (used by the [LINKS] template).
  • longlabel - the long label (used by the [LONGLINKS] template)
  • width - the width of the image to be created.
  • height - the height of the image to be created.
  • quality - the image quality for Jpeg images (ranging from 0-100, with a default value of 75).


drop_index - When creating a link to an album, should the link to the album be my/album or my/album/index.html The former makes for cleaner links, but will only work if your images are being viewed from a webserver. If you're looking at the albums on your local machine you will probably need the index.html generated. Default: yes

table_columns - The number of columns of thumbnails you want to appear on each album page. Default: 6

table_rows - The number of columns of thumbnails you want to appear on each album page. Default: 4

thumb_width or thumb_height - The [width | height] (in pixels) of each thumbnail on an album page. Default: 100

photoFields - Here you can name the fields that you want to be valid for the image meta-data. The defaults are probably enough for most people but you can add arbitrary strings here.

album and photo metadata

You can associate meta-data with any album or photo. This is how you can specify a custom title or description. The meta-data is stored in your HOME/.settings/[photo_root]/albums.xml | photos.xml file. You can edit these files be hand or use the UI to modify them.