PD also works with two other modes:
Note: You do not need to install any additional modules to run PD. All required modules are included.
If you used the Auto-installer, you should have an operational postcard system ready to go.
If you have done a manual install, make sure the permissions are set correctly.
Once you have verfied that you have a working system by sending a test card from the PD example page, ie: http://www.yoursite.com/pd/postcards.html, you would then do:
http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi and set an initial username/password.http://www.ginini.com.au/pd/images/bird.gif/
http://www.ginini.com.au/pd/images/bird.gif the short URL would be /pd/images/bird.gif
/pd/midi the real location (full
directory path) could be something like /home/ginini/htdocs/postcard-direct/midiThe full directory path is displayed in the diagnostics section if an error occurs.
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. Note that WinZip will handle both tar.gz and zip files.
This will create two top level directories:
pd - where the images, midi and html files exist.
cgi-bin/pd - where the scripts, admin, configuration and template 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.
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/cache (777) /cgi-bin/pd/cards (777) /cgi-bin/pd/includes (755) /cgi-bin/pd/includes/* (644) /cgi-bin/pd/logs (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/pdadmin.cgi (755) /cgi-bin/pd/pd.cgi (755) /cgi-bin/pd/pdedit.cgi (755) /cgi-bin/pd/pdview.cgi (755)
/pd (755) /pd/help (755) /pd/midi (755) /pd/midi/* (644) /pd/images (755) /pd/images/* (644) /pd/uploads (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/cache (777) /cgi-bin/pd/cards (777) /cgi-bin/pd/includes (755) /cgi-bin/pd/includes/* (644) /cgi-bin/pd/logs (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/pdadmin.cgi (755) /cgi-bin/pd/pd.cgi (755) /cgi-bin/pd/pdedit.cgi (755) /cgi-bin/pd/pdview.cgi (755)
/pd (755) /pd/help (755) /pd/midi (755) /pd/midi/* (644) /pd/images (755) /pd/images/* (644) /pd/uploads (777)
If you are not familar with what the numbers mean, the following table will help:
| Mode | Permission | Description |
| 777 | rwxrwxrwx | Read/Write/Execute for owner, group and other. |
| 755 | rwxr-xr-x | Read/Write/Execute for owner. Read/Execute for group and other. |
| 666 | rw-rw-rw- | Read/Write for owner, group and other. |
| 644 | rw-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.
/usr/bin/perl then edit /cgi-bin/pd/pd.cgi, /cgi-bin/pd/pdadmin.cgi, /cgi-bin/pd/pdedit.cgi and /cgi-bin/pd/pdview.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 IIS servers, CGI scripts are usually recognised by their extension. Generally this is set to be .cgi or .pl. If it is not set to .cgi you will need to rename the scripts to have the approprate extension.
Under /cgi-bin/pd the following directories exist:
| admin | Contains admin type files, eg: message database, admin password file etc. |
| cache | Contains a cache of any remote images/objects. |
| cards | Contains any cards that are due to be picked up and any cards stored to be sent at a later date. |
| configs | Contains the PD configuration file/s. |
| designs | Contains the design templates. |
| includes | Contains any include files for the postcard message. |
| lists | Contains list files, eg: badword list, midi list etc. |
| logs | Contains log file/s of postcards sent. |
| modules | Contains Perl modules |
| stylesheets | Contains CSS files |
| templates | Contains the various form and other templates. |
Under /pd the following directories exist:
| help | Contains the help files. |
| images | Contains sample images and icons. |
| midi | Contains midi files. |
| uploads | Contains any uploaded images/objects. |
In most cases, PD should work without any configuration changes. If you need to correct any paths or change any options, you can either edit the configuration via the admin interface, eg: http://www.yoursite.com/cgi-bin/pd/pdadmin.cgi or transfer the pdconfig.txt file to your PC, make the changes, and then transfer back to the webserver.
The Postcard Direct configuration is split into main and optional configuration sections. The main section contains the most common settings you would need to change.
| Main Configuration Section | |
$site_url | Set this to the full URL for your site. Don't add any filenames to the path. You only need to set this if PD can't automatically determine your website name. |
$document_root | If your web document root is not automatically determined, uncomment and set this the full directory path to the top level of your web documents. This directory path is where your home page would exist. |
$url_alias | You only need to add this setting if your URL contains a ~, eg: http://www.yoursite.com/~peter |
$pdurl | This is the short URL to where the PD images, help and midi files exist. Unless you are using non standard or an unusual location, this will always be /pd |
$pdroot | This is the full path to $pdurl. There should be no need to change this setting. |
$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. |
$disable_uploads | 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. |
| 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, or overridden if you set $sendmail_path |
$sendmail_queue | 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. |
$sendmail_path | If your webserver has sendmail in an unusual location or if it uses a sendmail alternative like qmail, uncomment and set this path. This will override the automatic check for the sendmail path. |
$smtp_server | 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). If your webserver is running on a Windows server, this is you will need to use this setting. |
| Admin Interface Section | |
$admin_referers | Set this to a comma separated list of all the domain names that can call the pdadmin.cgi script. You should also include the IP address/es if you find the domain names are recognised. This means you will need to create a page on your website with a link to pdadmin.cgi in order to have the correct referer set. In most instances you probably don't want to do this. |
$expire | Uncomment this setting if you want to have an expiry time on the admin login/session. If it is commented the admin session last until the browser is exited. |
| Anti-Leech Section | |
$AntiLeech | Set to 1 to turn anti-leech functions on, 0 to turn off. |
$referers | 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 | |
$sender_email | Set to the email address that the postcard will come from. |
$sender_name | Set to the sender name of the postcard. |
$reply_to | Set to an address if you want all replies to go to a single address. |
$max_recipients | Set to the maximum number of recipients. |
| Requires Section | |
$require_sender_name | Require the sender of the postcard to fill out their name. |
$require_receiver_name | Require the name of the recipient to be filled out. |
$require_message | Require the postcard message to be filled out. |
$strict_email_check | 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. |
$check_domain | This checks that the email address has a valid top level domain, eg: .com, .org, .au, .nz etc. |
$allow_html | 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. |
$check_bad_users | 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. |
$check_bad_words | 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. |
$add_message_id | Your mail server will generate a Message ID, but in some circumstances, it may not generate one that complies to the suggested Internet standard. Setting the following option will make PD generate its own Message ID. |
| Language Options | |
$lang | Default language to use. |
$title | This is the default page title that is used if none is specified. |
| Message Options | |
$max_message | Set to the maximum allowable size of the message. This is to prevent people abusing the script by trying to send out huge postcards. |
$message_db | Location of the message database. This would not normally be changed. |
| Logging Options | |
$log_file | Set to a location where the log file will be written to. |
$enable_logging | Set to 1 to enable logging or 0 to disable logging. |
| Remote Images Section | |
$remote_sites | Set this to the file that contains a list of all sites that you can specify a remote postcard image from. |
$cache_expiry | 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. |
$cache_age | Set this to the number of days that a cached image is stored before it is deleted. Set this value to be greater than $cache_expiry. |
| Image Upload Section | |
$disable_uploads | Set to 0 to enable and 1 to disable. |
$maxpost | If you enable image uploads, you will need to increase this value from the default of 8KB. |
$upload_dir | This is the directory to store uploaded images. Note that this directory needs to be writable by the webserver owner. |
$upload_age | Age in days, that old uploaded images get deleted. |
$upload_types | List of allowable upload types. Note that they are case insensitive. |
| 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. |
$postcard_dir | Location of where the postcards will be stored. By default, this is in the postcards directory where the PD HTML files exist. |
$postcard_age | This is the maximum age in days to store a postcard on the server before it is deleted. |
$future_card_age | This is the maximum age in days in the future that a card can be sent. |
$receipt_subject | The subject line for read receipts. Only applicable for receipts sent in the 'traditional' mode. |
| Templates Section | |
$form | Template for the default input form. |
$upload_form | 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. |
$input_error | Template for any invalid data entered in the postcard form. |
$read_receipt | Template for read receipts for cards sent in 'traditional' mode. |
$card-expired | Template for expired cards. |
$stylesheet | Default Stylesheet (CSS) to use for postcards. |
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:
NOTE - You can mix both types of variables/tags if you desire.
| Form name | Description |
| form-default.txt | This is the default form template and has the image above the input fields. |
| form-all.txt | This template has most of the available features specified. |
| form-basic.txt | This template is the same as the default template, but has the postcard design and music options removed. |
| form-side.txt | This template places the image to the side of the form. It is best suited to images that aren't too large. |
| form-bcc.txt | Same as the default template, but has a Bcc option for multiple recipients. |
| form-date.txt | Same as the default template, but has a date option to allow the user to send the postcard at a later date. |
| form-fields.txt | This template shows an example of using additional form fields. |
| form-colours.txt | This template shows an example of using additional form fields to allow colour selections. |
| form-java.txt | This template shows how to integrate a java applet. |
| form-traditional.txt | 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 |
| %INCLUDE% | <pd_include> | Text from the specified include file |
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>
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. |
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. |
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. |
This template is used for sending a read receipt to the sender of the card. This is only applicable to cards sent in the 'traditional' mode.
| Variable | Special Tag | Description |
| %RECIPIENT% | <pd_recipient> | is the name of the recipient. |
| %RECIPIENT_EMAIL% | <pd_recipient_email> | is the email address of the recipient. |
| %SENDER% | <pd_sender> | is the name of the sender. |
| %SENDER_EMAIL% | <pd_sender_email> | is the email address of the sender. |
| %SUBJECT% | <pd_subject> | is the subject of the postcard/email. |
| %STYLESHEET% | <pd_stylesheet> | Inserts a HTML stylesheet |
This template is used for displaying the message when a users card has expired or they have specified an incorrect card id. This is only applicable to cards sent in 'traditional' mode.
| Variable | Special Tag | Description | |
| %RECIPIENT% | <pd_recipient> | is the name of the recipient. | Inserts a HTML stylesheet | %SUBJECT% | <pd_subject> | is the subject of the postcard/email. |
| %STYLESHEET% | <pd_stylesheet> | Inserts a HTML stylesheet |
This template is used for the image upload form.
| Variable | Special Tag | Description |
| %PD_CGI% | <pd_cgi> | URL for pd.cgi. Do not delete. |
| %TITLE% | <pd_title> | Page title |
| %STYLESHEET% | <pd_stylesheet> | Inserts a HTML stylesheet |
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 |
| %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 |
| %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 |
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. |
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 |
| Send Date | The date the card has/will be sent |
| BCC | BCC option specified |
| Send Copy | Copy was sent to the sender |
| Field 1 | Free form field |
| Field 2 | Free form field |
| Field 3 | Free form field |
| Field 4 | Free form field |
| Field 5 | Free form field |
| Field 6 | Free form field |
| Message | Postcard message |
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
/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-default.txt), with the form parameter, for example:
/cgi-bin/pd/pd.cgi?image=/pd/images/photo.jpg;form=myform.txt
If you have multiple configuration files (defaults to pdconfig.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.txt
You can preload the form fields with particular values, for example:
/cgi-bin/pd/pd.cgi?image=/images/photo.jpg;subject=my+own+subject;sender=My+Name
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
| 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 |
| subject | Subject of the postcard. Uses the default if specified in the configuration file. | title=Some+Subject |
| include | Includes the text from the specified include file. | include=pd.txt |
| 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.txt |
| 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 |
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>
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.txt
By default, the form-flash.txt 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.
To specify a java postcard, specify the java form template, for example:
/cgi-bin/pd/pd.cgi?image=/images/photo.jpg;form=form-java.txt
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.
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.
/cgi-bin/pd/pd.cgi?image=/images/photo.jpg;form=form-traditional.txt
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.
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/configs/pdconfig.txt, set $disable_updates=0; 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.
If you have pending cards to be sent at a later date, you can schedule a cronjob (probably to run daily) that will check and send any cards due to be sent. Note that the any pending cards are checked whenever a card is sent, so long as you have at least one card per day sent from your site, you won't have any pending cards sent on the wrong date.
The cronjob needs to call:
/full/path/to/cgi-bin/pd/pd.cgi sendcards=yes
The following types of PD files are stored on the web server and expired/deleted at specified times:
| Type | Directory | Description | Configuration Option/s |
| Uploaded Images | /pd/uploads ($upload_dir) | If image uploads are enabled, then users can upload their own images for the postcard. These images are stored in the directory specified by $upload_dir. | $upload_age specifies the number of days an uploaded image is kept before it gets deleted. |
| Traditional Cards | /cgi-bin/pd/cards ($postcard_dir) | When a card is sent in "traditional" mode, a copy of the card is stored on the server for the recipient to "pick up". The card is stored in a file with a big long number with a .card extension, eg: 11691324960.629362261462123.card. Additionally, if a return receipt was requested, there will be a similarly named file with a .receipt extension. | $postcard_age - Number of days the stored card will be kept on the server before it is deleted. |
| Future Cards | /cgi-bin/pd/cards ($postcard_dir) | Any cards to be sent a a future date are stored as a file with a big long number and the .mail extension. A database of the cards to be sent is kept in .storecards.db | The future card files are only deleted when they are successfully sent. |
| Remote cached images | /cgi-bin/pd/cache ($cache_dir) | If remote images are allowed to be used for cards, they are downloaded and stored in a cache directory. | $cache_age is the maximum age in days before the cached image is deleted. |
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:
The easiest way to upgrade is to save your modified templates and configuration file and do a fresh install.
/pd/postcards directory./cgi-bin/pd/cards. Also ensure the permissions are set to 777 on each of the files.Note that as there are additional fields in the log file, you will not be able to use the Usage Report with the logs from PD version 5.x.x.
pd.cgi to pd.pl or whatever extention the web server is set up to recognise.#!C:\perl\bin\perl.exe) is only recognised on sites that run the Apache web server, otherwise it is ignored and is a function of the web server to be set up to recognise Perl
scripts.For the path C:\web\images\pic.jpg, you would assign it in Perl as either:
$Var="C:/web/images/pic.jpg";
or
$Var="C:\\web\\images\\pic.jpg";
or
$Var='C:\web\images\pic.jpg';
localhost as the SMTP
server, otherwise specify the fully qualified hostname of your mail server.The following limitations are known about:
<BODY BACKGROUND=xxx> tags, along with any <OBJECT> and <APPLET> tags. You should
make sure you design your postcard with a text colour that will be visable on a white background. You can get around the problem by placing the entire page in a table with a background colour.The FAQ is contained in this document.
Support issues can be found on the Support Forums.
If you are still running PD 5.x.x, you can read the relevant documentation for that version.