Index page for 2014

With Pictools, the browsing user see pictures grouped in primary directories each containing segments. A primary is a major collection of picture. For PhysPics each primary has all the pictures for one year; the segments within it are the trips, occasions, and topics that occurred. Each primary directory has an index.php page with links to its segment directories. For 2014 in PhysPics, the primary index page--shown to the right--has segments for BestPix, MomAt99, Hawaii, Netherlands, and others. The index.php page for each segment shows thumbnails of the segment's pictures. From there the user can visit one picture, see a slideshow, or view the pictures in sequence.

To construct a primary directory, the site manager creates its index.php and a single captions file, which we will call all.cap. The .cap file is the basis for generating all segment directories, their index.php files, and all views of pictures. Only the segment index files exist on the server; all views of pictures are generated as needed.

The pictures themselves are part of the source tree, but they reside in a separate pictures directory. It can be organized at the whim of the site manager, though there are some advantages to mirroring the division into primaries and segments. PhysPics has one pictures directory for each year, just as there is one primary directory per year. One advantage of splitting the pictures tree from the pages tree is that a single picture can appear in more than one segment. For 2014, each picture in the BestPix segment is also in some other segment for that year.

Subsequent paragraphs detail the steps to create a primary and all its segments.

Organize your pictures

Your goal in this step is to winnow your pictures to those you wish to inflict upon your viewers. At one time my estimate was that 10% were worthy. I've gotten more selective, though I still select more than one in a hundred. I start by copying all pictures from my camera to OriginalPictures/year. These pictures never move and are never renamed. By keepi ng names as given by the camera, I can reach back to the original for any picture. As I revise and select pictures, I copy them to DigestedPictures/year. DigestedPictures is the directory named by property PICTURESROOT. All of the pictures in this subdirectory will be uploaded to the server, although they get displayed on;y if mentioned in the captions file.

Pictools has several tools that that I created to help manage my pictures: cdentries.sh, filepix.csh, genmontage.csh, getdates.sh, maybes.csh, redub.csh. Of these redub.csh is the most likely to be helpful. I use it after re-exporting a few pictures. When Picasa exports a second copy of a picture it names it with "-0001" just before the extension. The redub tool can remove the -0001 from multiple pictures simultaneously:

redub.csh "-0001" "" *-0001.JPG

Create primary directory

Create a subdirectory of SRCROOT to be the primary directory for the new pictures. This directory is the location of everything for the primary other than the pictures themselves. In PhysPics the per year primary directories are members of the /annals directory.

The primary directory may have several files. It needs at least the first three of these:

index.php

This file should be an instance of template PhyspicsMain or whatever template you have devised for your site. It is displayed when the user browses to the primary directory. It should have links to all the segments  Although most PhysPics primary pages have ad hoc links, the links can be made by php-including all-titles.txt, which is generated from all.capswhen MakeTargets invokes gendirs. All-titles.txt is a series of <li> lines, so the inclusion in index.php looks like this

<ul>
    <?php include "all-titles.txt"; ?>
</ul>

Makefile

The minimal Makefile suffices:

 include $(PICTOOLS)/MakeVars
 include $(PICTOOLS)/MakeTargets

all.cap

All picture display code is derived from this, the "captions file". See that document for details on the content format. The next two sections below describe one way to construct it.

Pictools.properties

Needed if properties are to be specialized for this directory; see below. Can be an empty file. In any case unless overridden, properties from parent directories will be incorporated automatically, including the properties from the top-level Pictools.properties.

logo.png

(optional, but classy) An image to be displayed on the right of the title line for each page in the group. To incorporate the logo the property page.mainlogo must be set in the local Pictools.properties. A sample is this

page.mainlogo = <img src="logo.png" 
       width="www" height="hhh" 
       class="maintitlelogo" />

Where www and hhh are the size of logo.png.

page.bartitle: 2012
page.maintitle: Annals of Zweibieren, 2012
page.mainlogo: <img src="/annals/2012/GCtree.png" \
    alt="Grand Canyon thru ancient tree" \
    width="131" height="82" />
page.mainlogo.link: /annals/2012

Properties you may want to set in the group's Pictools.properties are in the sections Page layout properties, Picture pages and picture thumbs pages, Parameters for gendirs/genhtml. Some you might consider:

page.bartitle

Word (or short phrase) to appear for this directory in the directory list just below the title.Default is the directory name. String must not contain HTML tags.  Should be preceded by "#! private" so value is not inherited by descendant directories.

page.mainlogo

Logo to appear at the right of titleandlogo.php; an HTML snippet, nominally an <img/>; default is an empty image.

page.mainlogo.link

URL destination for a click on page.mainlogo. Default: none.

tree.logo

Alternate logo to display if there is no page.mainlogo. If this logo is to be a link, that link has to be part of the value of this property.

Run gencaps

The format of all.caps is detailed in captionFiles; it is a sequence of segments each consisting of a header and picture lines. A segment header line starts with "file:"

file: segment-name title-for-the-segment

A caption line has the picture file name in brackets followed by a caption for that picture:

[picturefilename] caption-words

Several other kinds of lines may appear. Most salient for now are the "picturesdir: directoryname" lines. After one of these, all subsequent pictures are from directoryname, where directoryname is relative to PICTURESROOT. Lines for picturesdir: and file: may intermix as needed. There may be multiple picturesdir: lines for each file: line or multiple file:s for each picturesdir:.

To get started toward all.cap, The tool gencaps may be run in a pictures directory to produce a rudimentary captions file. The segname for this segment is taken to be the last word in the directory name. The file generated by gencaps in directory PICTURESROOT/2105/Isley is named Isley.cap and looks like this:

file: Isley Pictures for Isley
picturesdir: /pictures/2015/Isley
[IMG_2473.jpg]
[IMG_2480.jpg]
[IMG_2497.jpg]
[IMG_2504.jpg] 

Note that the segname appears as the segment name in the header line, as part of the generated title for that segment, and as the final part of the picturesdir value. If a picture has a caption from Picasa or some other picture manager, that caption will follow that picture's file name.

Move the .cap file from the pictures directory to the directory for the new primary. When all segments are done, concatenate them to produce all.cap:

cat *.cap all.cap

(Then you must move or delete all .cap files other than all.cap. The Makefile insists there be only one .cap file.)

Adapt the all.cap file

You can now run 'make upload' in the primary directory. When you browse to that directory, the pictures will be visible and the slideshow will run. The segments will be organized in the same manner as the pictures in the pictures source directory. You can change that organization and make other improvements by editing all.caps. Here are some ideas for changes.

• Write or revise the captions. If your spouse has taken some pictures, he or she can be asked to edit captions; it is just editing text.
• Rearrange the pictures by reordering the captions lines. Sometimes I arrange the pictures in Picasa and then reorder the caption lines to match. Sometimes I order pictures chronologically, sometimes by color, shape, topic, or whim.
• Add, modify, or delete segment header lines. The values after file: are the sole determinant of what segments appear to the browser.  Thus the segments need have no relation to the directory structure in the pictures tree. If the primary index.php file is not using all-titles.txt, to make links to segments, you will have to revise the index.php file.
• Be careful that each picture follows the correct picturedir: line; you may intersperse multiple picturedir: lines, as needed. For a complex rearrangement I mlght resort to a spreadsheet. On each spreadaheet row I would have both the picturesdir value and the picture name/caption. After rearranging the rows I could internate picturedirs and name/captions or prune the unneeded picturesdir: lines.
• Delete some caption lines. Unless you are extraordinary (although who isn't?) you have selected too many pictures.
• Insert subtitle header lines (subtitle: ...) to break up the rows of thumbnails. The subtitle is displayed in green between the rows and also appears in the title area of individual pictures.
  
  Las Vegas, 2012
• Change the number of pictures per row. Ths requires only adding a parameter assignment between rows:

  thumbscol = 4

• Insert arbitrary text. Lines of text between picture lines are copied into the pictures page. I suggest this for comments longer than a caption and shorter than a blog entry. See, for instance, /annals/2012/LasVegas/. HTML tags may appear in this text; however, an opening tag and all its attributes must all be on the same line.

Example: DemoPics

The distribution, when installed, has a sample set of pictures and a sample captions file. During installation the Makefile in /pictools/doc/ copies the images from /pictools/doc/DemoPics to $PICTURESROOT/DemoPics. (This is strictly for the demo; you should manually install pictures into PICTURESROOT.) Later the DemoPics.cap file in /pictools/doc means that subdirectory /pictools/doc/Demo will be created. Visiting that directory will show the thumbs page for the demopictures.

Upload

When all the work above is done, uploading the pages is a single step. Open a shell window, change its directory to the group directory, and type the command

 make upload

This will parse the all.cap file, create subdirectories on the server for each segment, upload the contents for the group directory and segment directories, and finally, ensure that all the pictures directories mentioned in all.cap are scaled and uploaded to the pictures directory named by property PICTREESUBPATH.

Review

Now review the actual website. The group's index.php page should have links to all the thumbnail pages. Clicking one of those takes you to that thumbnail page. Prev and Next arrows atop the page traverse the chain of thumbnails. Clicking a thumbnail takes you to that full picture. Now the Prev and Next arrows take you to other pictures in that set of thumbnails. Clicking the UP buttom returns you to the thumbnails page. Tryrhe Slideshow button and see the images slide by. Return to the group's index.php. Check that all its links go where you intended. Enjoy!