Web Page Generator Documentation
================================

Theory of Operation
-------------------

The web page generator in CompuPic has almost unlimited flexibility because
of it's design.  Template files determine the entire layout and content of
the web pages, with few exceptions.  This amazing flexibility is accomplished
using unlimited variable expansion, defined in each template.  Each variable
has a standard type and is grouped into sets which are determined by the user
at runtime.  As the template is parsed, special HTML tags ("<thumbnail...>",
"<replicate...>" and "<rowarray ...>") are evaluated in sections first, and
their contents are logically iterated and removed based on their contents.
As sections are identified, variables are replaced and conditional sections
("<#if ...>", "<#else>", and "<#endif>") are processed.

Reserved variable names are used to maintain information about variables
which are based on the set of images chosen, the current image and the
structure imposed by the process of creating iterative web pages from
templates.  For example, the current image number and current page number
both change for each image page and thumbnail page emitted, so these
variables must be maintained by CompuPic during the process.  All other
information (the only user changeable options) are derived from the
<photodex_template> section.


Template Definition
-------------------

Every CompuPic web page template file must contain a <photodex_template>
section, delimited with a starting template tag ("<photodex_template") and a
terminator ("</photodex_template>").  Everything within these tags including
these tags is omitted in the final output.

The <photodex_template> tag itself must contain the type of template
("type=thumbnail" or "type=image") and the name of the template to be
presented to the user in the user interface (title="<template title>").

The simplest template section is as follows:

<photodex_template title="Sample Template" type=thumbnail>
</photodex_template>

Two templates are possible for thumbnail web page generation.  The first is
the template used for creation of the thumbnail pages ("type=thumbnail").
The second is optional, and is used to create the web pages for each image.
If the image page template is not specified, then links to the actual images
are used instead (the variable {{imagePageURL}} is the same as {{imageURL}}.)

Variable group definitions are specified within the photodex_template section.
There is no limit to the number of groups or variables, but each group is
intended to be able to fit in the user interface.  Variables are defined in
groups designed to be presented to the user in the user interface as one
related group of options.  Each variable group is defined using the following
syntax:

<group title="group title" [variable list...] >

The title is a string which is appended to either "Thumbnail Page" or "Image
Page" in the user interface, probably a combo-box.  A sample of the options
in a combo-box in a user interface might look like is below.  The first
option, "Templates & Folders", is there to allow the user to choose which
templates and global options they want:

   Templates & Overall Configuration
   Headings  (Thumb Pages)
   Home Link  (Thumb Pages)
   Navigation  (Thumb Pages)
   Background  (Thumb Pages)
   Thumbnails  (Thumb Pages)
     Headings  (Image Pages)
     Home Link  (Image Pages)
     Navigation  (Image Pages)
     Background  (Image Pages)
     Thumbnails  (Image Pages)

The "[variable list...]" is a list of variable definitions using this
syntax:

variableName=<type>(<label>,<default>[,<minimum>,<maximum>])

The variable name can be anything except spaces and punctuation, except that
the first character must not be a number.  The type is always one of the
following:

   file        file specification
   checkbox    checkbox (either "0" or "1")
   color       color picker (represented with hex color)
   line        single line text
   radio       radio button (either "0" or "1")
   scroll      scrollbar (like value, approx. +/- 2^31)
   text        free-form text (can contain newlines)
   value       numeric value (approx. +/- 2^31)

A simple single line heading text definition with a blank default value would
look like this:

   pageHeading=line("Page Heading","")

A simple checkbox which defaults to "on" would look like this:

   includeHeading=checkbox("Make Heading Visible",1)

For scrollbars and values, the minimum and maximum value must be specified.
For example, we could specify a variable called "thisVariable" which has a
default value of 12, and can be between 1 and 25:

   thisVariable=value("Sample Value",12,1,25)

Or similarly, a scrollbar with a default value of 50 which can be between
10 and 100 would be specified as follows:

   thisVariable=scroll("Sample Scrollbar",50,10,100)

For radio buttons, the variable name must end in a colon {':') followed by
a single letter which is used to determine which group of radio buttons it is
associated with (for example, "sampleObject:a" and "anotherSample:b" would be
in two separate radio button groups because of the ':a' and ':b' after their
names.)  Here is an example of a group definition with five radio buttons in
two groups:

   <group title="Radio Example"  radioButtonA:a=radio("Radio Button A",1)
                                 radioButtonB:a=radio("Radio Button B",0)
                                 radioButtonC:a=radio("Radio Button C",0)

                                 radioButton1:b=radio("Radio Button 1",1)
                                 radioButton2:b=radio("Radio Button 2",0)  >

Make sure to have one (and only one) of each radio button group defaulting to
"1", with the rest of the radio buttons in that group defaulting to "0".  If
you fail to do this, the default condition of your user interface will be
confusing and unprofessional.  (Don't be a web slob!)

Available templates are listed by their title only, and not their file name.
When the user wants to use a template file which is not listed, the user can
browse the file system to find the template file.  Thumbnail web page
templates are usually stored with the extension ".ttp" and image web page
templates are stored with the extension ".itp" to make the process of finding
these files easier, although the names of the files does not matter.
(CompuPic tests whether or not a given template file is valid by checking for
a valid <photodex_template> section containing all of the necessary
components.)  Once CompuPic loads a valid template file at the users request,
it is added to the list of known template files, which is stored in
"./web/template.lst" off of the CompuPic installation directory.  If CompuPic
ever tries to load a template file which is not valid, that template is
removed from the list of known templates automatically.

When CompuPic looks for the "template.lst" file, it first looks in CompuPic's
default data directory.  If the file is not there, then it looks in "./web".
CompuPic always writes new "template.lst" files to the data directory.  This
is necessary because CompuPic can run from a read-only device, so it will be
unable to write to the device to update the "template.lst" file.

The entire <photodex_template> section is removed for final output.


Saving and Loading Configurations/Contexts
------------------------------------------

CompuPic can save the state of all of the variables and which templates are
used in .cfg files in the ./web directory.  This allows the user to store
and reload specific configurations.  In the future, it will probably be
possible to bind a configuration with a hot-key so the user can quickly
bring up the user interface with commonly used configurations with one key-
stroke.

Whenever CompuPic closes the user interface for generating thumbnail web
pages, it writes a file called "default.cfg" in the web directory under the
root of the CompuPic installation.  This directory stores all of the
variables which comprise the current context of creating web pages.

The .cfg files are plain text, and the format is as follows:

----beginning of .cfg file----
CompuPic web page generator .cfg file
Thumbnail <full path/filename>
Image <full path/filename or blank for none>
<number of variables>
<variableName>=<value>
...
----end of .cfg file----

The first line is text which always reads "CompuPic web page generator .cfg
file".

Because the user interface is unlimited, there can be zero or more variables
defined by the .cfg file.  When CompuPic saves the values, it simple outputs
the text of this file.  When the file is reloaded, CompuPic first loads the templates
and creates all of the variables with their default values, then replaces the
variables which are listed in the .cfg file.

In the default installation, CompuPic Pro comes with several templates


Reserved Macro Variable Names
-----------------------------

Many macros are maintained by CompuPic and cannot be modified using the
template definitions.  If you try to use these names for dynamically specified
variables in the <photodex_template> section, they will not work.  All of
these reserved variables are replaced in the template with plain text
representing their contents.

{{currentImage}} - 1 or 0 depending on whether or not {{imageNum}} and {{imageNum0}} refer to the current image.
{{currentPage}} - 1 or 0 depending on whether or not {{pageNum}} and {{pageNum0}} refer to the current page.
{{firstImage}} - 1 or 0 depending on whether or not the current image is the first image.
{{firstImageURL}} - URL of first image.
{{firstImagePageURL}} - URL of first image page.
{{firstInRange}} - 1 or 0 depending on if the current image or page is the first replicated iteration.
{{firstPage}} - 1 or 0 depending on whether or not the current page is the first page.
{{firstPageURL}} - URL of first thumbnail page.
{{imageAMPM}} - 'am' or 'pm' of image time.
{{imageExt}} - File extension of current image.
{{imageBitDepth}} - Bit depth of current image.
{{imageColors}} - Number of colors in current image.
{{imageDate}} - Image date: "mm/dd/yyyy"
{{imageDateLong}} - Image date: "Month dd, yyyy"
{{imageDateLong2}} - Image date: "Mon. dd, yyyy"
{{imageDayNum}} - Image day of the month.
{{imageFormat}} - File format of current image (GIF, JPEG, etc.)
{{imageHeight}} - Vertical resolution of current image. (Same as imageVertRes.)
{{imageHorzRes}} - Horizontal resolution of current image. (Same as imageWidth.)
{{imageHours}} - Hour of image date (0-11).
{{imageHours24}} - Hour of image date in (0-23).
{{imageMinutes}} - Minute of image date (two digits).
{{imageMonth}} - Image date month (long form).
{{imageMonth2}} - Image date month (three characters).
{{imageMonthNum}} - Image date month.
{{imageName}} - Name of current image.
{{imageNum}} - Current image number (starting at 1).
{{imageNum0}} - Current image number (starting at 0).
{{imagePageURL}} - Current image URL.
{{images}} - Total number of images.
{{imageSeconds}} - Second of image date (two digits).
{{imageSize}} - File size of current image.
{{imageSizeComma}} - File size of current image with commas.
{{imageSizeK}} - File size of current in K (1024 bytes).
{{imageSizeKComma}} - File size of current in K (1024 bytes) with commas.
{{imageSizeMB}} - File size of current in MB (megabytes, 1048576 bytes).
{{imageSizeMBComma}} - File size of current in MB (megabytes, 1048576 bytes) with commas.
{{imageURL}} - URL of current image file.
{{imageValid}} - 1 or 0 depending on if the next image used with a <thumbnail> tag is valid.
{{imageWidth}} - Horizontal resolution of current image. (Same as imageHorzRes.)
{{imageVertRes}} - Vertical resolution of current image. (Same as imageHeight.)
{{imageYear}} - Image year.
{{lastImage}} - 1 or 0 depending on whether or not the current image is the last image.
{{lastImageURL}} - URL of last image.
{{lastImagePageURL}} - URL of last image page.
{{lastInRange}} - 1 or 0 depending on if the current image or page is the last replicated iteration.
{{lastPage}} - 1 or 0 depending on whether or not the current page is the last page.
{{lastPageURL}} - URL of last thumbnail page.
{{nextImageURL}} - URL of next image.
{{nextImagePageURL}} - URL of next image page.
{{nextPageURL}} - URL of next thumbnail page.
{{pageNum}} - Current page number.
{{pageNum0}} - Current page number.
{{pages}} - Total number of pages.
{{pageURL}} - Current page URL.
{{prevImageURL}} - URL of previous image.
{{prevImagePageURL}} - URL of previous image page.
{{prevPageURL}} - URL of previous thumbnail page.
{{thumbHeight}} - Height of current thumbnail image (actual generated size, not necessarily frame size given in <thumbnail> tag).
{{thumbWidth}} - Width of current thumbnail image (actual generated size, not necessarily frame size given in <thumbnail> tag).
{{thumbURL}} - URL of current thumbnail file.


Conditionals
------------

The tags "<#if ...>", "<#else>", and "<#endif>" are used for conditional
inclusion of sections of HTML.  The "<#if ...>" tag is designed to be used
with any variable (reserved or dynamic) which resolves to a "1" or "0".  If
an "<#if ...>" tag is used with a variable which resolves to text, then the
evaluation is true if the text is not blank and not "0".

Here is an example of using conditionals to emit a hyperlinked thumbnail only
if the image associated with it is valid, and explanatory text if the image is
not valid:

<#if {{imageValid}}>
   <thumbnail><img src={{thumbURL}}></thumbnail>
<#else>
   No Image
<#endif>

An example when {{imageValid}} == "1":

   <img src=tn_image1.jpg>

An example when {{imageValid}} == "0":

	No Image


Special HTML Tags
-----------------

<thumbnail width=# height=# [pad=<color>] [crop] [othertags] ></thumbnail>

           Sets up the context for an individula thumbnail/image combination.
           If the image is not valid (beyond the end of the thumbnail list)
           the information between the <thumbnail...> tag and the </thumbnail>
           tag is removed.  If 'pad' is specified, then the image is padded to
           be exactly the frame size with the color specified.  If crop is
           specified, then the image is sized to the exact frame size by
           cropping whatever doesn't fit.  Using pad and crop in the same
           thumbnail definition is illegal and may cause unpredictable
           results.  Examples of "pad=<color>" and "crop":

                                                    Cropped
                                                    Portrait
                          Default      Padded      Thumbnail
              Target     Portrait     Portrait    +----------+
            Frame Size   Thumbnail    Thumbnail   |XXXXXXXXXX|
           +----------+  +------+   +-+------+-+  +----------+
           |          |  |      |   | :      : |  |          | The areas
           |          |  |      |   | :      : |  |          | filled with
           |          |  |      |   | :      : |  |          | 'X's have
           |          |  |      |   | :      : |  |          | been removed.
           +----------+  +------+   +-+------+-+  +----------+
             100x100      60x100      100x100     |XXXXXXXXXX|
                                                  +----------+
                                                    100x100

           The dimensions below each illustration are the values of
           {{thumbWidth}} and {{thumbHeight}} inside of a <thumbnail> tag
           pair.

           If the target frame size (width and height) are not specified, the
           default frame size of 96 x 72 is used.

     ie:   This is the simplest use of the thumbnail tag:

           <thumbnail>
              <img src={{thumbURL}}>
           </thumbnail>

     result:
           <img src=tn_image1.jpg>


     ie:   This example outputs a single thumbnail, but is nicely behaved to
           output width and height information to help the web browser more
           easily format the page while loading:

           <thumbnail width={{thumbnailFrameWidth}} height={{thumbnailFrameHeight}}>
              <a href={{imagePageURL}}>
                 <img width={{thumbWidth}} height={{thumbHeight}} src={{thumbURL}}>
              </a>
           </thumbnail>

     result:
           <a href=image1.html>
              <img width=96 height=72 src=tn_image1.jpg>
           </a>


     ie:   This example outputs a single thumbnail, but if the intended
           image is beyond the end of the list, it outputs informative text
           instead:

           <#if {{imageValid}}>
              <thumbnail width={{thumbnailFrameWidth}} height={{thumbnailFrameHeight}}>
                 <a href={{imagePageURL}}>
                    <img width={{thumbWidth}} height={{thumbHeight}} src={{thumbURL}}>
                 </a>
              </thumbnail>
           <#else>
              No Image
           <#endif>

     result with a valid image:
           <a href=image1.html>
              <img width=96 height=72 src=tn_image1.jpg>
           </a>

     result with an invalid image:
           No Image


<replicate #>
           Replicates contents of <replicate> tag pair "#" number of times.

           The "<replicate>" tag replicates it's contents for each iteration,
           exactly "#" times.  Use the "<#if ...>", "<#else>" and "<#endif>"
           with {{imageValid}} to handle special output for empty cells.

     ie:   This example generates a linear list of thumbnails:

           <replicate 5>
              <thumbnail>
                 <img src={{thumbURL}}>
              </thumbnail>
           </replicate>

     result (assuming three images {{images}}=3).  (Note that the number of
           iterations is five, but the last two iterations were removed
           because the images were not valid):

           <img src=tn_image1.jpg>
           <img src=tn_image2.jpg>
           <img src=tn_image3.jpg>

           To apply hyperlinks to the associated images, include the anchor
           tags inside the <replicate> section:

     ie:   This example generates a linear list of thumbnails which are
           hyperlinked to their associated image pages:

           <replicate num=5>
              <a href={{imagePageURL}}>
                 <thumbnail>
                    <img src={{thumbURL}}>
                 </thumbnail>
              </a><br>
           </replicate>

     result (assuming three thumbnails):

           <a href=image1.html>
              <img src=tn_image1.jpg>
           </a><br>
           <a href=image2.html>
              <img src=tn_image2.jpg>
           </a><br>
           <a href=image3.html>
              <img src=tn_image3.jpg>
           </a><br>

           Of course, to properly give web browsers enough information to be
           intelligent about the layout, it is always a good idea to give the
           actual dimensions of a given graphic in a web page in the "width="
           and "height=" fields in an <img> tag, so:

     ie:   This example generates a linear list of thumbnails which are
           hyperlinked to their associated image pages and also web browser
           friendly:

           <replicate num=5>
              <thumbnail>
                 <a href={{imagePageURL}}>
                    <img width={{thumbWidth}} height={{thumbHeight}} src={{thumbURL}}>
                 </a><br>
              </thumbnail>
           </replicate>

     result (assuming three thumbnails):

           <a href=image1.html>
              <img width=90 height=42 src=tn_image1.jpg>
           </a><br>
           <a href=image2.html>
              <img width=80 height=72 src=tn_image2.jpg>
           </a><br>
           <a href=image3.html>
              <img width=96 height=72 src=tn_image3.jpg>
           </a><br>

     ie:   This example generates the same list as above, but emits text if
           there is no valid image:

           <replicate num=5>
              <#if {{imageValid}}>
                 <thumbnail>
                    <a href={{imagePageURL}}>
                       <img width={{thumbWidth}} height={{thumbHeight}} src={{thumbURL}}>
                    </a><br>
                 </thumbnail>
              <#else>
                 No Image<br>
              <#endif>
           </replicate>

     result (assuming three thumbnails):

           <a href=image1.html>
              <img width=90 height=42 src=tn_image1.jpg>
           </a><br>
           <a href=image2.html>
              <img width=80 height=72 src=tn_image2.jpg>
           </a><br>
           <a href=image3.html>
              <img width=96 height=72 src=tn_image3.jpg>
           </a><br>
           No Image<br>
           No Image<br>


<replicateimages #> / <replicatepages #>
           Replicates contents of <replicateimages> or <replicatepages> tag
           pair for each image or page, changing the contents of {{imageNum}},
           {{imageNum0}} and {{currentImage}} or {{pageNum}}, {{pageNum0}} and
           {{currentPage}} appropriately.  These tags are designed to be used
           for image and page navigation, similiarly to how internet search
           engines give access to ranges of pages.

           If the number of images or pages exceeds the "#" parameter,
           then the image and page numbers will be centered around the
           current image or page (see the example below.)

     ie:   This example generates a simple list of all image numbers:

           <replicateimages>{{imageNum}} </replicateimages>

     result (assuming images==10):
           1 2 3 4 5 6 7 8 9 10

     ie:   This example shows limited replication when the maximum number of
           replications is smaller than the total number of pages:

           <replicatepages 10>{{pageNum}} </replicatepages>

     result (assuming pages==100 and currentPage==50):
           46 47 48 49 50 51 52 53 54 55

     ie:   This example shows the use of conditionals to prevent hyperlinking
           of the current page in the above situation:

           <replicatepages 10>
              <#if {{currentPage}}>
                 {{pageNum}}
              <#else>
                 <a href="{{pageURL}}">{{pageNum}}</a>
              <#endif>
           </replicatepages>

     result (assuming pages==100 and pageNum==50):
           <a href="page46.html">46</a>
           <a href="page47.html">47</a>
           <a href="page48.html">48</a>
           <a href="page49.html">49</a>
           50
           <a href="page51.html">51</a>
           <a href="page52.html">52</a>
           <a href="page53.html">53</a>
           <a href="page54.html">54</a>
           <a href="page55.html">55</a>




