This postcard system was written by Meindert van der Bijl. 
Please send comments, bugs, suggestions for improvement 
to mvdbijl@inedita.com.

This is version 2.1, released 1/25/2002.
New versions will be made available at 
http://inedita.com/home/english/ineditas.htm

*****************************************************************
* These scripts come WITHOUT ANY WARRANTY nor can the author be *
* held liable for any damage resulting from use or misuse of    *
* these scripts. Permission is granted to copy, steel, borrow   *
* or otherwise use this code or parts of this code for non-     *
* commercial purposes. No part of these scripts may be sold     *
* or otherwise used for commercial ends, wihtout prior written  *
* permission from the author.                                   *
*****************************************************************

The system consists of the following files:

1) pcard-setup.pl
2) select-card.pl
3) write-card.pl
4) preview-card.pl
5) send-card.pl
6) show-card.pl
7) cron-card.pl

1) pcard-setup.pl defines global variables and several
subroutines used in the other scripts. You should edit
this file to suit your installation. Also the text
of the email messages can be changed in this file.

2) select-card.pl expects the name of the card from a 
static HTML page, an example page is included. It is 
assumed that there is a thumbnail named "image_th.ext" 
of each "image.ext" file. select-postcard.pl shows 
the card in the actual size.
This HTML page is ./pages/select-card.html.

3) write-card.pl gets the name of the card from select-card.pl, 
it outputs an HTML page where the user needs to fill in sender 
name and email, recipient name and email, greeting and message, 
and the date the email message should be sent. Also the user
can choose the text and background colors.
This HTML page is ./pages/write-card.html.

4) preview-card.pl outputs the postcard as it will be seen 
by the recipient. It also checks to see if all the necessary 
input data have been supplied. The HTML output file is 
./pages/preview-card.html.

5) send-card.pl makes the connection with the database and 
stores all the data. When the date "sdate" (date the message 
should be sent) is today, an email message is sent with the 
URL for the recipient to pick up the  postcard. This script 
also sets a cookie which identifies the sender so that the 
next time around the same user does not have to fill in 
her/his name and email again. An HTML "thank you" page is 
output,  ./pages/send-card.html.

6) show-card.pl is script that shows the postcard  to the 
recipient. It expects an ID number on the (GET) query string. 
This ID number is used as the key to get the postcard from 
the database, HTML output from ./pages/show-card.html.
The sender is notified that the recipient has picked up
the postcard.

7) cron-card.pl is a program to be run by crontab daily. 
     ******* YOU NEED TO EDIT THIS FILE **********
All you need to do is put the full path to the setup file 
(pcard-setup.pl) on your system at the beginning of the script.
It connects to the database and sends all the  postcards with 
"sdate" date equal to "today". Also cleans the database
of all postcards whose notification message has been sent
a month or more ago.

As a check that the notification messages are have been sent, the
field "retrieved" in the postcards table is initially set to "-1",
when the notification message is sent (either by send-card.pl
or cron-card.pl) it set to 0. 

So in the table all rows with:
retrieved = -1 :   notification not sent, send_on still to come
retrieved =  0 :   notification sent, send_on passed
retrieved >= 1 :   number of times the card was seen.

cron-card.pl also checks the state of the "retrieved" field so that
even if you run the script more than once a day it will not send
out repeated messages.

The HTML code is separated from the Perl code. The HTML output 
is in separate files in the directory ./pages/, these pages 
contain tags like <tmpl_var name=perlvariable>, which are
evaluated by the HTML::Template module before being sent to
stdout.

To customize the layout, edit the HTML files in ./pages/, but
take care with the HTML::Template tags.

The Perl DBI (database interface) module is used and therefore the
scripts should work with any database supported by DBI, though minor
changes to the SQL used may be necessary. Tested only with MySQL,
http://www.mysql.com, you can also find the DBI and Msql-MySQL
modules there.

See the file postcards.sql for the SQL code to create the tables.


HISTORY

The first version dates back to late 1997, after an article by 
Reuven M. Lerner in the "Linux Journal", Oct. 1997, issue 42, p. 106.
It was my first attempt at MySQL driven pages. As a regular number 
of people are still downloading the scripts, I try to update the 
program when time allows me to. I try to keep it as simple as possible, 
so as to allow even people who are new to Perl to be able to customize
the program to their needs.


Januari 2002
  - senders and postcards divided into two tables
  - sender id is written to a cookie so that a returning user 
    does not have fill in name and email again
  - use HTML::Template for HTML output 

Februari 2001
  - updated to the (not so new anymore) DBI modules
  - separated HTML from Perl code
  - added functionality to warn the sender when the recipient picks up the card
  - added automatic cleaning of the database of old postcards

June 1998
  - first version made available for download

late 1997
  - first functional version in operation at http://inedita.com
    


TODO
  - some kind of error handling of bounced messages. This
    should somehow be reported back to the sender







