how to handle photographs

• the trips folder structure
• editing an album page
• uploading photographs
• viewability: who may view the photographs
• captions.xml

This web site has a file system, and one of its folders is the trips folder.

The trips folder has a special folder structure. It is arranged at four levels:

1. trips is the top folder. It contains folders...
2. ... for years (typically 2010, 2011, 2012, etc). You can use this level in a different way if you wish (eg: family, hobby, sport).
   Each of these folders contains further folders...
3. ... for trips or events. It's assumed that you will have a collection of photos for the trips or events you made or had during the year. So, for example, these might be labelled 'Prague', 'Sams stag night', 'Daves visit 23May', and so on. Each of these folders contains...
4. ... sub-folders (typically labelled with the date). So, if you went on holiday, you could put each day's pictures into a separate folder. These are labelled with their date (in ISO format so that they sort correctly). So, they might be 20110521 (for 21 May 2011), 20110522 (for 22 May 2011), and so on. These folders contain your picture files.
   As well as the date in ISO format, you can add a title to the folder name. There is no need for a comma between the date and title.
5. For each one of these day folders, there are two parallel folders to store the resized pictures needed. Photos are usually very large files, and are displayed on a computer screen at lower reslution than that of the picture. If we were to download a full-sized photo image every time you viewed it, you would consume much more bandwidth (and cost possibly) than necessary. So, we resize the images to the size at which they are going to be viewed. These re-sized images are held in folders named (for example) 20110521Sized and 20110521Thumb.

So, you might have something like this.

The trips folders are special in another way. They contain special files (generally named captions.xml which are used to store the data that you can input as descriptions and captions for your pictures. As they are part of the pictures their data goes with them. You can edit these data if you are appropriately logged in (as a site administrator).

Notwithstanding the special folder structure of the trips folder, if you break the structure, the software tries to accommodate you. So, if you have fewer levels, it will try and show your pictures by skipping levels. The main point to note here is that if a folder (or sub-folder) contains folders, it is assumed not to contain pictures; it will be treated as a part of the path and any pictures it contains will not be displayed.

editing an album page

You can add text to an album page if you have 'administrator' rights on the web site. If it's your web site, you almost certainly will have. If it's not, you'll have to ask the owner to give them to you.

If you are logged in and have admin rights, when you view a trips page, you will see a number of widgets and buttons that normal users don't see. At the bottom of the photographs is 'edit captions'. Press this, and you see a new page. This enables you to select a picture to edit, and text boxes in which you can type a 'caption', a 'description', and a date for each picture.

• The 'caption' is the title above the picture (best kept to a few words).
• The 'description' is intended for longer descriptions; it is usually shown below the picture.
• If you don't enter a date, the picture date will be picked up from the picture (if it has a date). But, if you have edited the picture (eg: if you've cropped it), then the date associated with the picture is likely to be the edit date. In this case, you might want to add your own date in the text box.
• There is also a 'save the edit' button. You need to save for each image.

uploading photographs

You can create new folders and add photographs if you have 'administrator' rights on the web site. If it's your web site, you almost certainly will have. If it's not, you'll have to ask the owner to give them to you.

If you want to create folders and upload, you need to go to files and folders on the menu or click here. There you can navigate about the folder structure and create new folders as you need. You can add new files or replace existing ones.

You can bulk upload from a folder on your computer to a folder on your web site. If you have a lot of files to upload, this is the way to do it. There is an explanation under files and folders (see 'upload a folder') of how to use FTP to do this. If doing this, it is best to set up the appropriate folder structure and files on your computer and use the bulk upload. There is no need to create the xxxxxxxxSized and xxxxxxxxThumb folders. They are created automatically.

When you have uploaded new files, the web site should detect new files and bring them into view automatically.

viewability: who may view the photographs

The photographs are held in a hierarchy of computer folders. Who can view what is determined by the viewability policies that you have set up. 'Viewability' is described in the system notes, but the following is a briefer description.

You can set the viewability of your folders at any level in the folders. If the viewability of a folder is not defined, it takes its viewability from its parent, and so on up the tree. So, for example, if you set the viewability of the trips folder and do nothing more, all the folders (and their sub-folders) belonging to trips will have the same viewability (ie: that of trips).

The 'viewability' mechanism, uses the idea of 'groups' and 'members' of groups. So, in the limit, you can restrict the viewability of a single folder to a single person if you want to. Or, you can create a group and give that group the viewability permissions that you choose.

For convenience, there are two overall groups which you can use. The 'loggedin' group includes anyone who is logged in. The 'all' group includes anyone who views the web site (whether logged in or not).

If you want to set or change the viewability of a folder, you use the menu: site management > manage viewability.

captions.xml

The data describing the pictures is held in a set of files each named 'captions.xml'. These files are held in the folders to which they relate, so that copying the picture folders takes the folder data with them. The relevant data is different for the various levels of folder, broadly as follows.

1. trips folder
   lists the data for the selector of the contained 'year' folders
2. the 'year' folder
   lists the data for the selector of the contained 'album' folders
3. the 'album' folder
   lists the data for the selector of the contained 'day' folders
4. the 'day' folder
   lists the data for the pictures for the day

As may be deduced from the file extension, captions.xml is an xml file.

The top three levels of folder simply enable the selector to show a name for each folder being listed. So instead of showing 'trips/2008/Cevennes', it would be possible to display 'Cevennes trip - June 2008'. So for example, the captions.xml file in the trips/2008 folder might read as follows:

	<?xml version="1.0"?>
	<!DOCTYPE gk [<!ENTITY nbsp " ">]>
	<gkCreateDOM>
	<selector name="trips/2008">
		<folderName>trips/2008/Cevennes</folderName>
		<nameAsSeen>Cevennes trip - June 2008</nameAsSeen>
		<folderName>trips/2008/Dolomites</folderName>
		<nameAsSeen>Dolomites trip</nameAsSeen>
	</selector>
	</gkCreateDOM>
	

The lowest level folder lists the data for each picture in the folder. So, for each picture, the captions.xml file contains:

	<?xml version="1.0"?>
	<!DOCTYPE gk [<!ENTITY nbsp " ">]>
	<gkCreateDOM>
	<picture name="file name">
		<caption>here is caption text</caption>
		<description>here is the longer description</description>
		<creationDate>date in unix time format</creationDate>
		<pictureDate use="T" or "F">date in unix time format</pictureDate>
	</picture>
	...more pictures as required...
	</gkCreateDOM>