CGI Programming by Collin Forbes
  Configuring Postcards 2.5   Updated: Thur, 20 Apr 2000  

The Configuration File
The Improbable Postcards program uses its configuration file to determine how to assemble the postcards as well as arrange its web pages. This file closely mimics the look and feel of a Windows initialization (.ini) file, with section names in square brackets, followed by name and value pairs.

With a few execptions, each section controls a postcard, you'll tell the program which postcard to use by putting the alphanumeric section name after a slash at the end of the main URL:

/cgi-bin/postcard.cgi/section_name

The [directory], [executable] and [template] sections contain directory paths and filenames which are important to the program:

[directory]
cache="/usr/tmp"

The directory where postcard.cgi will store temporary files and cached images. The program must be able to write into this directory when run by the server.

template="../postcards/tmpl"

The default directory where postcard.cgi can find its templates. These templates are discussed in detail on the postcard templates page.

netpbm="/usr/local/netpbm"

The directory where you (or your system administrator) installed the NetPBM utilities. Some systems may have them in /usr/X11R6/bin.

jpeg="/usr/local/bin"

The directory where you (or your system administrator) installed the JPEG utilities cjpeg and djpeg.

png="/usr/local/bin"

The directory where you (or your system administrator) installed the PNG conversion utilities pngtoppm and pnmtopng.

[executable]
sendmail="/usr/sbin/sendmail"

The location of the "sendmail" executable on your system. Depending on your server, it might also be /usr/lib/sendmail or /usr/opt/sendmail.

chksum="/usr/bin/chksum"

The location of the "chksum" executable on your system or another program such as md5, which reports checksums for files.

[template]
initial-template="../postcards/tmpl/initial-template.tmpl"
confirm-template="../postcards/tmpl/confirm-template.tmpl"
problem-template="../postcards/tmpl/problem-template.tmpl"
sent-template="../postcards/tmpl/sent-template.tmpl"
email-template="../postcards/tmpl/email-attachment-template.tmpl"

The filenames of the templates. These override the value of the default template directory and let you use different names than what postcard.cgi will use by default. You will see later where you can give each postcard an individual template to customize the layout further. The functions and structure of the templates is discussed in detail on the postcard templates page.

The other sections in your configuration file will be interpreted as postcards. You should have a [default] section which represents the default postcard for use by the program if it's called without a postcard identifier. In addition, other postcards can inherit values from the default postcard, saving you from typing the same values for each postcard.

[default]
image-url="/postcards/image/default-thumbnail.gif"

The URL of a representative postcard image, ideally as a thumbnail or smaller example of an already completed postcard. You can use the full-sized postcard image in a pinch.

image-filename="../postcards/image/default.gif"

The filename of the image to use as the basis of the postcard. Don't forget to leave room for the postcard message.

postcard-width="480"
postcard-height="360"

The expected height and width of the completed postcard. Use the dimensions of your full-sized postcard image.

coords="245,20,470,340"

These are the coordinates of a rectangle in the image where postcard.cgi will fit the postcard's message. This is just like the coordinates for a HTML imagemap, the first two numbers are the x,y of the top left corner and the second two numbers are the x,y of the bottom right corner. If omitted, the program will write the message over the entire image, which is probably not what you want. Also, other postcards will not inherit this value from the default postcard.

font-filename="../postcards/font/verdana-small.bdf"

The filename of the BDF font to use for this postcard. See the section on postcard fonts for more information about how to make and/or find these fonts.

coloring="black_on_white"

How the postcard text should play against the background.

black_on_white Black lettering on a solid white panel
white_on_black White lettering on a solid black panel
black_on_background Black lettering against the background of the postcard
white_on_background White lettering against the background of the postcard
opposite_background Lettering is always opposite the surrounding postcard
Try different settings with your postcards to see which you like.

return-image-type="jpeg"

Normally the program will create the postcard in the same type as the source image. Use this optional value to force the postcard image into a different type. Valid settings are "gif", "jpg", "jpeg" and "png".

recipient-name="their name"
recipient-address="their address"
sender-name="your name"
sender-address="your address"
message="default message for the postcard"

Default values for the initial postcard form. Omit them to let the corresponding form inputs appear without values.

Still confused? Here's an example configuration file from the working examples. You should be able to make minor changes to the settings for your own postcards.