Postcard Direct Documentation

Contents


How does it work?

Postcard Direct works by MIME encoding any images, midi, flash etc. This means everything that is needed to display the postcard is contained in the mail body.

PD also works with two other modes:

  1. Web mail - Most web mail sites can't/won't handle embedded images in the email, so this mode references the images from the website the postcard was sent.
  2. Traditional mode - Works like all other postcard programs, ie: stores the card on your webserver and mails out a ticket to the recipient.


Operational Requirements

Before installing you must make sure that you have:

Note: You do not need to install any additional modules to run PD. All required modules are included.


Quick Install Guide

For experienced or impatient people only.

After uploading the files, make sure the permissions are set correctly.


Definitions

The following definitions are a used to clarify terms used in the documentation.

Full URL

The complete URL for your site, comprising the server name and the file path, eg: http://www.ginini.com.au/pd/images/bird.gif/

Short URL

A file path portion of the full URL. For example, for the full URL http://www.ginini.com.au/pd/images/bird.gif the short URL would be /pd/images/bird.gif

Full directory path

When you specify a URL of a file, the web server it is coming from will know the full directory path on the Operating System where to retrieve the file from. For example, if I have a short URL of /pd/midi the real location (full directory path) could be something like /home/ginini/htdocs/postcard-direct/midi
The actual path will vary from webserver to webserver.

The full directory path is displayed in the diagnostics section if an error occurs.


Installing

Auto Installer

You can try the auto-installer service, if you don't want to manually install the files.

Extracting

The source is contained in a gzip tar file or ZIP file.

To unpack the gzip tar file, type:

gzip -dc postcard-direct.tar.gz | tar xvf -

To unzip the ZIP file, type:

unzip postcard-direct.zip

or use best to WinZIP.

This will create two top level directories:
pd - where the images, midi and html files exist.
cgi-bin/pd - where the scripts, admin and configuration files exist.

Copy the pd directory to the directory where your web documents exist.
Copy the pd directory from cgi-bin/pd to the directory where your CGI scripts exist. In most cases this will be your cgi-bin directory. Other locations maybe cgi-local or scripts.

IMPORTANT - When you FTP the files to your web server, make sure that only the graphics and midi files are transfered in binary mode, all other files should be transfered in ASCII mode. If you fail to do this, it will most likely cause the script to fail. Also note that the Auto setting on FTP clients such as WS-FTP is not always reliable.

Permissions

There are two sets of permissions that need to be set depending on how you are going to manage PD.

If you are going to administer PD via the pdadmin menu interface, you will need to set the following permissions:

/cgi-bin/pd (755)

/cgi-bin/pd/admin (777)
/cgi-bin/pd/admin/* (666)

/cgi-bin/pd/logs (777)
/cgi-bin/pd/cache (777)

/cgi-bin/pd/configs (777)
/cgi-bin/pd/configs/* (666)

/cgi-bin/pd/modules (755)
/cgi-bin/pd/modules/* (644)

/cgi-bin/pd/stylesheets (777)
/cgi-bin/pd/stylesheets/* (666)

/cgi-bin/pd/designs (777)
/cgi-bin/pd/designs/* (777)
/cgi-bin/pd/designs/*/* (666)

/cgi-bin/pd/lists (777)
/cgi-bin/pd/lists/* (777)
/cgi-bin/pd/lists/*/* (666)

/cgi-bin/pd/templates (777)
/cgi-bin/pd/templates/* (777)
/cgi-bin/pd/templates/*/* (666)

/cgi-bin/pd/pdglobal.txt (644)
/cgi-bin/pd/pdadmin.cgi (755)
/cgi-bin/pd/pd.cgi (755)
/cgi-bin/pd/pdedit.cgi (755)

/pd (755)
/pd/help (755)
/pd/midi (755)
/pd/midi/* (644)
/pd/images (755)
/pd/images/* (644)
/pd/postcards (777)

If you are going to administer PD by FTPing the files to and from your PC, then you can use the following (more restrictive) permissions:

/cgi-bin/pd (755)

/cgi-bin/pd/admin (755)
/cgi-bin/pd/admin/* (644)

/cgi-bin/pd/logs (777)
/cgi-bin/pd/cache (777)

/cgi-bin/pd/configs (755)
/cgi-bin/pd/configs/* (644)

/cgi-bin/pd/modules (755)
/cgi-bin/pd/modules/* (644)

/cgi-bin/pd/stylesheets (755)
/cgi-bin/pd/stylesheets/* (644)

/cgi-bin/pd/designs (755)
/cgi-bin/pd/designs/* (755)
/cgi-bin/pd/designs/*/* (644)

/cgi-bin/pd/lists (755)
/cgi-bin/pd/lists/* (755)
/cgi-bin/pd/lists/*/* (644)

/cgi-bin/pd/templates (755)
/cgi-bin/pd/templates/* (755)
/cgi-bin/pd/templates/*/* (644)

/cgi-bin/pd/pdglobal.txt (644)
/cgi-bin/pd/pdadmin.cgi (755)
/cgi-bin/pd/pd.cgi (755)
/cgi-bin/pd/pdedit.cgi (755)

/pd (755)
/pd/help (755)
/pd/midi (755)
/pd/midi/* (644)
/pd/images (755)
/pd/images/* (644)
/pd/postcards (777)

If you are not familar with what the numbers mean, the following table will help:

ModePermissionDescription
777rwxrwxrwxRead/Write/Execute for owner, group and other.
755rwxr-xr-xRead/Write/Execute for owner. Read/Execute for group and other.
666rw-rw-rw-Read/Write for owner, group and other.
644rw-r--r--Read/Write for owner. Read for group and other.

Where a * is specified, it means all files in that directory.

For Windows servers, 777 or 666 is roughly equivalent to read/write access for everyone, 755 is not applicable and 644 is roughly equivalent to write permission for the owner and read for everyone. Usually, only your ISP can change Windows permissions for you unless you have some type of Windows/Webserver admin interface.

Perl Locations

If your location of perl is not /usr/bin/perl then edit /cgi-bin/pd/pd.cgi, /cgi-bin/pd/pdadmin.cgi and /cgi-bin/pd/pdedit.cgi to make sure the first line is the correct path for your perl location.

If you are installing on a Win/NT system, it depends which web server you are running as to whether the perl path is recognised. If you are running an Apache server, the path would be set to something like C:\perl\bin\perl.exe

On Microsoft ISS servers, CGI scripts are usually recognised by their extention. Generally this is set to be .cgi or .pl.

Global Configuration File

The only file that needs to be manually configured (ie: can't be set through the admin interface), is /cgi-bin/pd/pdglobal.txt. You will need to define the following settings:

$pdroot - This should be set the the Full Directory Path of where the PD HTML, images and midi files exist. Generally this is in the /pd directory where your web documents exist.

$pdurl - This is the short URL to the above path. Unless you are using non standard or an unusual location, this will always be /pd

$expire - By default, the admin login cookie will last for your browser session. If you want to put a time limit on it, uncomment this setting. +1h means expire after 1 hour.

$DisableUploads - If you want to allow image uploads, then you will have to set the value to 0 and increase the upload limit in $maxpost to the desired size.


Configuration

Configuration File

Once all the files have been installed, you should try to access the admin interface, eg: http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi. The first time you access this, you will be required to set a username/password. The default username is pdadmin, but you can set this to be anything you like.

Once you are at the main menu, choose the "Edit configuration" option to set the following settings:

The Postcard Direct configuration is split into essential and optional configuration sections. Once you have correctly defined the settings in the essential section, you should have an operational system.

Essential Configuration Section

$WebRoot - Set this to the full URL for your site. Don't add any filenames to the path.

$TopLevel - Set this the full directory path to the top level of your web documents. This directory path is where your home page would exist.

$URLAlias - You only need to add this setting if your URL contains a ~, eg: http://www.yoursite.com/~peter

Mail Options

$Subject - Set to a default subject line if none is specified/required.

$Sendmail - Uncomment this line if you want the mail to be sent by sendmail. The path for sendmail is automatically determined by the pd.cgi script

$SendmailQueue - You can speed up the operation of the script by using the sendmail mail queue. This is also a more reliable way to send mail as the mail will stay in a queue if there are any transient delivery problems or sendmail isn't running. The only tradeoff is that the mail will take longer to be delivered as it will sit in the queue until sendmail processes it at whatever interval is defined, usually 15 mins.

$MailServer - If you don't have sendmail on your server, set this to the Hostname of your SMTP mailserver. Leave set to localhost if the server you run the script on handles mail, otherwise set to the full hostname of the server that handles your mail (generally your ISP mail server)

The following settings are all optional and are generally not required to get the postcards running successfully.

Anti-Leech Section

This section allows you to restrict where the postcard script can be called from. $AntiLeech - Set to 1 to turn anti-leech functions on, 0 to turn off.

$RefererList - Set this to a comma separated list of all the domain names that can call the pd.cgi script. You should also include the IP address/es if you find the domain names are recognised.

Mail Sender Section

If you have SMTP mail options set, some mail servers are configured to only allow the sender to be someone from your domain, in which case you would need to set the SenderEmail to address within your domain.

$SenderEmail - Set to the email address that the postcard will come from.

$SenderName - Set to the sender name of the postcard.

$ReplyTo - Set to an address if you want all replies to go to a single address.

Requires Section

The Requires Section give you the ability to turn on/off various features. A 1 means the option is on, a 0 means the option is off.

$RequireSenderName - Require the sender of the postcard to fill out their name.

$RequireReceiverName - Require the name of the recipient to be filled out.

$RequireMessage - Require the postcard message to be filled out.

$StrictEmailCheck - If this option is turned on additional checks are performed on the validity of the email address. If it is turned off, then the email address just has to be in a valid format.

$Checkdomain - This checks that the email address has a valid domain, eg: .com, .org, .au, .nz etc.

$AllowHtml - If this option is turned on, HTML will be allowed to be used in the postcard messages. By default HTML tags are stripped from the message.

$CheckBadUsers - If this option is turned on, the email addresses of the sender and/or recipient are looked up in the badusers.txt file to see if they should be banned. This option is useful if you have a user is complaining of unwanted postcards.

$CheckBadWords - If this option is turned on, the postcard message is checked against the list of banned words in the badwords.txt file.

$Diag - If this option is turned on, diagnostic messages will be displayed on the error page.

Language Options

English is the default language. To change this, set $Lang to the country code of one of the supported languages.

$Title - This is the default page title that is used if none is specified.

Directory Locations

There should be almost no reason to change any of the settings in this section.

Message Options

$WrapText - Set to the maximum width of the line in the message before it is wrapped onto a new line. This option will only be used if the message contains no new lines. This will occur when either the TEXTAREA tag does not have a WRAP=HARD specification, and/or the user has not pressed the enter key between lines.

$MaxMessage - Set to the maximum allowable size of the message. This is to prevent people abusing the script by trying to send out huge postcards.

$MessageDB - Location of the message database. This would not normally be changed.

Logging Options

$LogFile - Set to a location where the log file will be written to.

$EnableLogging - Set to 1 to enable logging or 0 to disable logging.

Remote Images Section

$RemoteSites - Set this to the file that contains a list of all sites that you can specify a remote postcard image from.

$CacheExpiry - Set this to the number of days that an image can exist in the cache before a new version is retrieved from the remote site.

Mode Options

$Mode - This can be set to direct or traditional. If set to traditional, PD will operate like standard postcard systems, ie: send a ticket for the recipient to pick up their card. The following options are only used in traditional mode.

$PostcardDir - Location of where the postcards will be stored. By default, this is in the postcards directory where the PD HTML files exist.

$PostcardAge - This is the maximum age in days to store a postcard on the server before it is deleted.

Upload Section

$UploadDir - This is the directory to store uploaded images. Note that this directory needs to be writable by the webserver owner.

$UploadAge - Age in days, that old uploaded images get deleted.

List Files Section

You would not normally need to change anything in this section.

Templates Section

$Form - Template for the input form.

$UploadForm - Template for the image upload form.

$Sent - Template for the confirmation page when the postcard is being sent.

$Error - Template for any general error messages like missing cnofiguration files.

$InputError - Template for any invalid data entered in the postcard form.

$Stylesheet - Default Stylesheet (CSS) to use for postcards.


Templates

There are templates to control the entire output of Postcard Direct. This means that no perl code needs to be changed in order to customise the web pages.

The templates consist of HTML code with special tags embedded in them. The special tags have a <pd_ prefix. You can also use special variables that a surrounded by percent signs %, for example:

%TITLE%

or

<pd_title>

These variables/tags are expanded to their appropriate value when the pd.cgi reads the template.

The reason that two methods are given is:

  1. Personal preference. You may decide that using special tags is easier to type and read, or visa-versa.
  2. Some HTML editors don't like %VARIABLES% or will change the formatting of them, in which case, using the special tags may help.

NOTE - You can mix both types of variables/tags if you desire.

Forms

There are a number of form templates which control the look of the postcard form where the user enters their message and who they are sending the postcard to. The following form templates are pre-defined:

Form name Description
form.html This is the default form template and has the image above the input fields.
form-basic.html This template is the same as the default template, but has the postcard design and music options removed.
form-side.html This template places the image to the side of the form. It is best suited to images that aren't too large.
form-bcc.html Same as the default template, but has a Bcc option for multiple recipients.
form-date.html Same as the default template, but has a date option to allow the user to send the postcard at a later date.
form-fields.html This template shows an example of using additional form fields.
form-colours.html This template shows an example of using additional form fields to allow colour selections.
form-java.html This template shows how to integrate a java applet.
form-traditional.html This template is the same as the default template, but it uses the "traditional" method of sending the postcard.

The following special tags/variables can be used:

Variable Special Tag Description
%CGI% <pd_cgi> URL of the postcard CGI. Do not change this.
%IMAGE% <pd_image> URL of the postcard image
%OBJECT% <pd_object> URL of the postcard object
%WIDTH% <pd_width> Width of the postcard image
%HEIGHT% <pd_height> Height of the postcard image
%TITLE% <pd_title> Title of the image
%DESIGNS% <pd_designs> Select list of postcard designs.
Uses the default design if not specified.
%MIDI% <pd_midi> Select list of midi files.
%OBJECTS% <pd_objects> Select list of the object files.
%DATE% <pd_date> Date selection fields
%HELP% <pd_help> URL for the Postcard Direct Help file
%PDICON% <pd_icon> URL for the Postcard Direct Icon.
%STYLESHEET% <pd_stylesheet> Inserts a stylesheet. Uses pd.css by default.
%FIELD1% <pd_field1> Free form field that can be used for any purpose
%FIELD2% <pd_field2> Free form field that can be used for any purpose
%FIELD3% <pd_field3> Free form field that can be used for any purpose
%FIELD4% <pd_field4> Free form field that can be used for any purpose
%FIELD5% <pd_field5> Free form field that can be used for any purpose
%FIELD6% <pd_field6> Free form field that can be used for any purpose

You can change or remove input fields by using HIDDEN fields. For example, if you want every postcard to have a midi file with it, edit the form template and:

Remove lines:

<tr>
<td><b>Music:<b>lt;td>
<td>
 <select name="midi">
  <pd_midi>
 <select>
<td>
<tr>
and add the following line in the section where all the other hidden fields are:

<input type="hidden" name="midi" value="favourite_song.mid">

If you want to change which postcard design the form template uses, change the line:

<input type="hidden" name="design" value=default.txt">

to be which ever postcard design you want it to use.

If you only have a single postcard design per form, then you can remove the design select list, by removing the lines:

<tr>
<td><b>Postcard Design:<b>lt;td>
<td>
 <select name="design">
  <pd_designs>
 <select>
<td>
<tr>

error.html

This template is for any general Postcard Direct error messages like configuration problems.

The following variables/tags are available:

Variable Special Tag Description
%ERROR% <pd_error> Error message.
%SUGGESTION% <pd_suggestion> Suggestion message.
%DIAGNOSTIC% <pd_diagnostic> Additional diagnostic error messages.
%PERLVER% <pd_perlver> Perl version.
%SERVER% <pd_server> Web Server details.

inputerror.html

This template is for displaying any input errors such as invalid email addresses, fields not filled out, etc.

You can use the following variables (variables in bold are compulsary):

Variable Special Tag Description
%MESSAGE% <pd_error> Error message.
%BACK% <pd_back> Displays a "Back to Form" button.
%STYLESHEET% <pd_stylesheet> Inserts a stylesheet. Uses pd.css by default.

sent.html

This template is used for displaying the confirmation screen when the postcard is being sent.

You can use the following variables/tags:

Variable Special Tag Description
%IMAGE% <pd_image> URL of the postcard image
%OBJECT% <pd_object> URL of the postcard object
%RECIPIENT% <pd_recipient> Name of the recipient
%RECIPIENT_EMAIL% <pd_recipient_email> Email address of the recipient
%SENDER% <pd_sender> Name of the sender
%SENDER_EMAIL% <pd_sender_email> Email address of the sender
%SUBJECT% <pd_subject> Subject of the postcard/email
%MESSAGE% <pd_message> Postcard message
%STYLESHEET% <pd_stylesheet> Inserts a stylesheet. Uses pd.css by default.
%SENT% <pd_sent> When the postcard will be sent.


Design Files

Design files are just like the template files, but they are for the layout of your postcard. You can use any HTML code you like.

To add more postcard designs, create the new design template and add its name to the designlist.txt file.

You can use the following variables/tags. Note that you need to have either %IMAGE% or %OBJECT% defined:

Variable Special Tag Description
%TITLE% <pd_title> Title of the image
%IMAGE% <pd_image> URL of the postcard image
%WIDTH% <pd_width> Width of the postcard image
%HEIGHT% <pd_height> Height of the postcard image
%OBJECT% <pd_object> Embeds an object file in the postcard
%FIELD1% <pd_field1> Free form field that can be used for any purpose
%FIELD2% <pd_field2> Free form field that can be used for any purpose
%FIELD3% <pd_field3> Free form field that can be used for any purpose
%FIELD4% <pd_field4> Free form field that can be used for any purpose
%RECIPIENT% <pd_recipient> Name of the recipient
%RECIPIENT_EMAIL% <pd_recipient_email> Email address of the recipient
%SENDER% <pd_sender> Name of the sender
%SENDER_EMAIL% <pd_sender_email> Email address of the sender
%SUBJECT% <pd_subject> Subject of the postcard/email
%MESSAGE% <pd_message> Postcard message
%MIDI% <pd_midi> Embeds a midi file in the postcard
%STYLESHEET% <pd_stylesheet> Inserts a stylesheet. Uses pd.css by default.
%BACK% <pd_back> put a "Return to Form" button on the page when preview is selected
%SEND% <pd_send> put a "Send Postcard" button on the page when preview is selected


Multi-Lingual Support

PD is designed to easily support multiple languages. See list of currently supported languages.

English is the default language, although this can be changed in the configuration file.

You specify a non default language by using the lang parameter. For example:

pd.cgi?lang=br&image=/pd/images/photo.jpg

Each language is represented by its two letter ISO639 code. If no specific ISO639 code exists for a language, use the appropriate two letter country code.

To add support for a new language, you need to edit/create the following:

/cgi-bin/pd/admin/messages.txt This file contains a list of all the messages generated by the script. Add a translation for each message type.
/cgi-bin/pd/admin/languages.txt This file contains a list of all supported languages. Add the two letter language code and description to the file.
/cgi-bin/pd/modules/pddates.pm This file contains a list of the short month names. It is used in the form-dates.html template
/cgi-bin/pd/modules/charsets.pm This file contains any charsets required for a particular language. The default is ISO-8859-1.
/cgi-bin/pd/templates/language Create a new directory for the HTML templates and copy/translate existing templates.
/cgi-bin/pd/lists/language Create a new directory for the lists and copy/translate existing lists.
/cgi-bin/pd/designs/language Create a new directory for the postcard designs and either create new postcard designs or copy in existing designs.
/pd/help/language/help.html Create a new directory and translate an existing help file.


Log File

Postcard Direct writes an entry in a log file everytime a postcard is sent out (if logging is enabled). The Admin Menu has an option to view a summary of the log entries.

The format of the logfile is:

Field Description
Date Date in YYYY-MM-DD format. Y2K complient
Time Time the postcard was sent in HH:MM format
Method Sending method. Either html, web or plain
Design The postcard design that was used
Image URL Postcard image
MIDI Name of midi file
Object Name of the object file
Remote Host Hostname where the request came from
Subject Postcard subject
Sender email Email address of the sender
Sender name Name of the sender
Recipient email Email address of the recipient
Recipient name Name of the recipient
Message Postcard message


Testing

If you have a command line access on your web server, you can check that the syntax of the scripts is correct by typing:

perl -c pd.cgi

If no errors are reported, try running the script using:

./pd.cgi

If everything is correct, it will spit out some HTML code saying it requires an image URL.

Once you reach this point, try invoking it from your web browser using the sample image, eg:

http://www.yoursite.com/cgi-bin/pd/pd.cgi?image=/pd/images/photo.jpg


Modes of Operation

General

You can use images that are stored anywhere on your webserver. They do not need to be in any particular directory. The most common form of operation is to just specify the path to the image for the postcard. For example:

/cgi-bin/pd/pd.cgi?image=/pd/images/photo.jpg

If you are using an media type like, flash, quicktime etc, you should use the object parameter, for example:

/cgi-bin/pd/pd.cgi?object=/objects/movie.swf

You can specify a remote image (so long as your cache directory and remotesites.txt file are set correctly), for example:

/cgi-bin/pd/pd.cgi?image=http://www.somewhere.com/images/photo.jpg

You can specify the optional title parameter if you want to use titles for your postcards, for example:

/cgi-bin/pd/pd.cgi?image=/pd/images/photo.jpg&title=This+is+the+title+for+the+postcard

Note that spaces should be encoded with a +

You can specify which form to use (defaults to form.html), with the form parameter, for example:

/cgi-bin/pd/pd.cgi?image=/pd/images/photo.jpg&form=myform.html

If you have multiple configuration files (defaults to default.txt), you can specify then with the config parameter, for example:

/cgi-bin/pd/pd.cgi?image=/images.photo.jpg&config=myconfig.txt

Or you can combine as many parameters as you like, for example:

/cgi-bin/pd/pd.cgi?image=/images.photo.jpg&config=myconfig.txt&title=My+Title&form=myform.html

Make sure that when you specify the URL for the postcard image you use the full document path from your web root ie: has a leading /. For example, use a path like /postcards/images/photo.jpg rather than ../images/photo.jpg

Parameters

The full list of parameters available are:

Parameter Description Example
image URL to a postcard image. image=/pd/images/photo.jpg
object URL to a postcard object. object=/objects/cartoon.swf
title Title of the postcard. Uses the default if none specified. title=Some+Postcard+Title
config Name of alternative configuration file. Uses the default if none specified. config=myconfig
form Name of postcard form to display. Uses the default if none specified. form=form-java.html
stylename Name of stylesheet to use. Uses the default if none specified. stylename=newstyle.css
lang Language to use. Uses the default if none specified. lang=de
upload Invoke the image upload form. upload=yes

Thumbnails

The most common way of setting up a Postcard site is to have a page of thumbnail images, with the postcard using the full sized image. For example, assume the following directories:

/postcards/large (Directory for full sized images)
/postcards/th    (Directory for thumbnail images)
/postcards/index.html (Postcard index page)
then in you index.html page, you would use a link like:

<a href="/cgi-bin/pd/pd.cgi?image=/postcards/large/photo.jpg"><img src="/postcards/th/photo.jpg" border="0" alt="Click to send as a postcard"></a>

Flash Postcards

When specifying a flash object, use the object parameter, and specify the form template for flash postcards, for example:

/cgi-bin/pd/pd.cgi?object=/objects/movie.swf&form=form-flash.html

By default, the form-flash.html template will use the flash.txt design template. If you want to change this, edit the form template, and change the line:

<input type="hidden" name="design" value="flash.txt">

To point to the desired design template. Note that the sending method is set to traditional via a hidden field. Embedded flash objects in a email is unreliable as lot of mail clients don't support it, or their security restrictions prevent viewing it.

Java Postcards

To specify a java postcard, specify the java form template, for example:

/cgi-bin/pd/pd.cgi?image=/images/photo.jpg&form=form-java.html

You will need to edit the form template and the java design template (defaults to java.txt) to insert whatever java applet you want to run.

Note that the Java form template has no sending options. It defaults to the web method. This is because you can't embed a java applet in an email message.

Multi-Lingual Postcards

If you want to set up postcards for different languages, use the lang parameter. For example:

/cgi-bin/pd/pd.cgi?image=/images/photo.jpg&lang=de

This example would use the German templates and German messages.

The default language is English, although this can be changed in the configuration file.

Also, see the example multi-lingual page to see how to use Javascript and a select list to choose the language.

Traditional Postcards

If you want to offer a Postcard service that operates like all other postcard sites (ie: mails a ticket to the recipient for them to pick up their postcard), use the traditional form template. For example:

/cgi-bin/pd/pd.cgi?image=/images/photo.jpg&form=form-traditional.html

You can edit the traditional.txt design template to modify the message sent to the recipient. You can make the traditional mode the default method by setting $Mode='traditional' in the configuration file.


Image Uploads

If you want to allow users to upload their own images to use as postcards, you will need to change the following default settings:

In /cgi-bin/pd/pdglobal.txt, set $DisableUploads=1; and $maxsize to the largest size image you want to accept.

To invoke the upload form, use /cgi-bin/pd/pd.cgi?upload=yes

The image will be uploaded to whatever $UploadDir directory (default /pd/postcards) is set to, and will automatically be deleted after the number of days set in $UploadAge.


Administration Interface

Most operations such as editing templates and configuration files can be done through the administration interface. The administration interface is accessed through pdadmin.cgi. For example:

http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi

If you forget your password, you can reset it by editing the /cgi-bin/pd/admin/auth file and deleting the second field, eg:

pdadmin:


Upgrading

Upgrading from older versions of PD (4.5.1 and lower) should not be too difficult as all the templates will be compatible.

The first step is to get the current version installed and working by following the installation instructions in this document. As the new version of PD has a different directory structure to the older versions, there is no problem of overwriting or clashing files.

Once the new version is successfully running, you should copy the templates you want to keep from the old version. The locations and extentions for the templates have changed. The following table summarises the differences:

Old Location/Name New Location/Name
/postcard-direct/templates/form.html /cgi-bin/pd/templates/en/form.html
/postcard-direct/default.design /cgi-bin/pd/designs/en/default.txt
/postcard-direct/plain.design /cgi-bin/pd/designs/en/plain.txt
/postcard-direct/midilist.txt /cgi-bin/pd/lists/en/midilist.txt
/postcard-direct/designs.txt /cgi-bin/pd/lists/en/designlist.txt
/postcard-direct/objectlist.txt /cgi-bin/pd/lists/en/objectlist.txt
/postcard-direct/badwords.txt /cgi-bin/pd/lists/en/badwords.txt
/postcard-direct/remotesites.txt /cgi-bin/pd/admin/remotesites.txt
/postcard-direct/badusers.txt /cgi-bin/pd/admin/badusers.txt
/postcard-direct/mimetypes.txt /cgi-bin/pd/admin/mimetypes.txt
/postcard-direct/help.html /pd/help/en/help.html

You will then need to update all your links to the new path, for example:

Instead of /cgi-bin/postcard.cgi?image=/images/photo.jpg

use /cgi-bin/pd/pd.cgi?image=/images/photo.jpg


Win/NT Notes

If you are running Postcard Direct on Win/NT systems, please note the following:


Limitations

There are a some limitations using the Postcard Direct method of sending the postcard to the user via email as there is no set standard for handling HTML formatted mail. There shouldn't be a problem if the recipients mail client handles MIME correctly.

The following limitations are known about:


FAQ/Support

The FAQ is contained in this document.

Support issues can be found on the Support Forums.


Return to main page