My Postcards Platinum © Web Application (version 5)

Owner's Manual: Setup

Directories and permissions
Files and permissions
Global configuration file (magics.cfg)
Custom configuration files
Changes from versions 3 and 4

Here and later: if permissions are not specified - system default permissions (defined by UMASK) would be enough and there is no need to change them

Directories and permissions

NOTE: This section describes default setup. It may be changed during the installation according to customer's request.

$ROOT_DIR - (chmod 755)

By default "platinum", unless you renamed it or requested an other directory name during installation. It has to be world-viewable.

$SCRIPT_DIR - (chmod 755)

If your server allows execution of cgi-scripts in any directory then $SCRIPT_DIR = $ROOT_DIR, otherwise SCRIPT_DIR = /cgi-bin

$CARDS_URL - (chmod 731)

Directory where card sources are written to. It should not necessarily be world-viewable. Server path to this directory is defined in magics.cfg.

You don't need even to look there - files there are created and deleted automatically. Do not upload or delete files and folders there!

For sysadmin: detailed setup of card datafiles storage is described in the "administration" section of this manual

$QUEUE_DIR - (chmod 731)

Directory where e-mail notifications for scheduled delivery are written to. It should not necessarily be world-viewable. Server path to this directory is defined in magics.cfg.

All contents are created/removed automatically - do not do anything with this directory. Do not upload or delete files and folders there!

For sysadmin: detailed setup of card datafiles storage is described in "administration" section of this manual

$STATS_DIR - (chmod 777)

Directory where stat data and reports are accumulated - do not do anything with this directory. Do not upload or delete files and folders there! It has to be world-viewable. Server path to this directory is defined in magics.cfg.

Good idea is to protect this directory with .htaccess to prevent others from peeking at your stats. If you do not know how to do this - ask your webhost.

If you want us to include your site into Top20 traffic reports - send us the login and password for this directory.

$INC_DIR - (chmod 731)

Directory where custom configuration files, html, e-mail and error templates are stored. It should not necessarily be world-viewable. Server path to this directory is defined in magics.cfg. It contains 4 subdirectories with predefined names.

$INC_DIR/html

HTML templates for cards are to be stored there, You can upload any number of files there. Read more about HTML templates in "customization" section of this manual.

$INC_DIR/errors

Special templates for error pages are stored there. All those pages have fixed names, you can edit them, but do not delete or rename! Adding there any other files will get you nowhere - program will not "see" them.

$INC_DIR/mail

E-mail templates for cardshop are to be stored there. You can upload any number of files there. Read more about e-mail templates in "customization" section of this manual.

$INC_DIR/conf

Custom configuration files are to be stored there. All files in this subdirectory should have extension *.txt and permissions chmod 666. You can create any number of files in this directory. The format of those files is explained below.

$POEMS_DIR (chmod 731)

Directory where you store all source files for poems (*.txt) and java applets (*.jav). You can upload/delete any files there. Read more details about those files in "customization" section. Server path to this directory is defined in magics.cfg. It should not necessarily be world-viewable.

$SAVE_DIR (chmod 777)

Directory where the card datafiles are written to. It must be world-viewable. Server path to this directory is defined in magics.cfg.

$SAVE_URL

WWW address for $SAVE_DIR, defined in magics.cfg. You won't need to change it unless you have changed $SAVE_DIR It must be world-viewable.

$IMG_URL

WWW address for the directory where your images are stored, defined in magics.cfg. You can create subdirectories within it to organize your images.

IMPORTANT! there is a subdirectory inside - "upload" (chmod 777) It is used to store uploaded files. You should be checking its content occasionally and clean it up.

$MIDI_URL

WWW address for the directory where your music files are stored, defined in magics.cfg. You can create subdirectories within it to organize your music files. It must be world-viewable.

$ROOT_DIR/backs/

Sample background files are stored there. You can create subdirectories within it to organize your background files. It must be world-viewable.

$ROOT_DIR/stamps/

Sample stamps (icon) files are stored there. You can create subdirectories within it. It must be world-viewable.

backs and stamps directories are not mandatory, you can put their contents elsewhere, these directories are not defined in global configuration file magics.cfg

Back to top or index
Files and permissions

All files marked by asterisk are required for Platinum performance and cannot be removed or renamed.

$SCRIPT_DIR - main program module

magiccard.cgi * - main program (chmod 755)

magics.cfg * - global configuration file (chmod 666)

$ROOT_DIR - sample card composition pages

p5-index.html - sample cardshop entrance

p5-card1.shtml - simple composition page

p5-card2.shtml - max selections composition page

p5-card3.shtml - quick card sample

p5-card4.shtml - use any composition element

p5-card5.shtml - max selections composition page with java-script

p5-card6.shtml - secret pal sample

p5-card-upload.shtml - sample upload form

p5-card-custom.shtml - composition page with custom fields

p5-card-steps.shtml - step by step card composition with custom fields

p5-card-icq.shtml - sample icq card

p5-preview.shtml - preview page for java-script enabled card composition

p5-view.shtml - sample composition page with preselected picture

p5-view-upload.shtml - sample composition page with uploaded picture

later.txt * - automatically generated file with send later dates, do not edit it!

$INC_DIR/conf/ - custom configuration files

magic.txt * - default custom config file (minimum features), used for card1.shtml and card-icq.html

magic-enh.txt - enhanced config file with all features of Platinum 5, used for card2, card4-6, view.shtml, view-upload.shtml

quick.txt - custom config file for card3.shtml, illustrates different card layout

forward.txt - custom config file for forwarded cards

birthday.txt - custom config file for "Virtual Gift" sample, used for card-custom.shtml and card-steps.shtml

$INC_DIR/html/ - card HTML templates

for all configurations - multi.html *, email.html *

for default simple config: receive.html, preview.html, sent.html

for "quick card" sample: Qreceive.html, Qpreview.html

for enhanced config with all features: receive-enh.html, preview-enh.html, sent-enh.html, save.html, print.html, forward.html

for forwarded cards: receive-fwd.html

for "Virtual Gift" sample: birthday-wrap.html, birthday-stamp.html, birthday-note.html, birthday-card.html, birthday-address.html, birthday-preview.html, birthday-receive.html

$INC_DIR/mail/ - sample e-mail templates

mail1.txt, mail2.txt, fwdmail1.txt

$INC_DIR/error/ - - customizable error pages

Edit_Email.html *, Edit_Email_Multi.html *, Err_CardNum.html *, Err_Code.html *, Err_Email.html *, Err_File.html *, Err_Incomp.html *, Err_NoCard.html *, Err_NoTick.html *

$POEMS_DIR

applet1.jav, applet2.jav - sample source file for Java applets to be used on cards

poem1.txt, poem2.txt, poem3.txt - sample files with poetry

Also sample images, midis, backgrounds, stamps in appropriate directories.

Back to top or index
Global configuration file magics.cfg

File permissions - chmod 666. This file should be in $SCRIPT_DIR. You cannot rename this file or move it outside $SCRIPT_DIR, otherwise your software will not work!

Be careful when editing this file, make sure you don't have extra-spaces anywhere. If you are editing this file offline and uploading with FTP be sure to use ASCII transfer mode.

Below is a sample of magics.cfg.
```
CARDS_URL|/home/yourdomain/htdocs/platinum/cards/
OLD_CARDS_URL|/home/yourdomain/htdocs/platinum/old_cards/
INC_DIR|/home/yourdomain/htdocs/platinum/includes/
POEMS_DIR|/home/yourdomain/htdocs/platinum/poems/
QUEUE_DIR|/home/yourdomain/htdocs/platinum/queue/
STATS_DIR|/home/yourdomain/htdocs/platinum/stats/
SAVE_DIR|/home/yourdomain/htdocs/platinum/save/
SAVE_URL|http://yourdomain.com/platinum/save/
IMG_URL|http://yourdomain.com/platinum/images/
MIDI_URL|http://yourdomain.com/platinum/music/
SEND_MAIL|/usr/lib/sendmail -t
MODE|ASAP
DAYS|30
STORED|14
```
OLD_CARDS_URL

compatibility setting for cards created with previous versions of Platinum

SEND_MAIL

sendmail program location, most probably will look like /usr/lib/sendmail for Solaris and /usr/sbin/sendmail for BSD and LINUX

if you don't know where it is and what it is and still want to change it - ask your webhost for assistance

MODE

notification mail delivery mode, default setting is ASAP, can be set to QUEUE mode. See detailed description in "administration" section

DAYS

days to send cards in advance, default setting is 30, you can set it to anything between 1 and 180

STORED

days to store cards, default setting is 14, you can set it to anything between 1 and 180. Be sure to check "administration" section - "Storing large amounts of card datafiles" before changing this setting.

Other settings are described above in directories and permissions

Back to top or index
Custom configuration files

Custom configuration files are used to specify the different set of HTML and e-mail templates. Such files are to be placed in $INC_DIR/conf, should have *.txt extension and permissions chmod 666.

Be careful when editing these files, make sure you don't have extra-spaces anywhere. When uploading with FTP be sure to use ASCII transfer mode.

By default magics.txt configuration file is used. Below are the contents of magic.txt from sample cardshop with minimal number of settings.
```
PRE_PAGE|preview.html
REC_PAGE|receive.html
SEN_PAGE|sent.html
CARD_MAIL|mail1.txt
PICK_MAIL|mail2.txt
```
Another sample configuration file magic-enh.txt contains maximum number of settings.
```
PRE_PAGE|preview-enh.html
REC_PAGE|receive-enh.html
SEN_PAGE|sent-enh.html
CARD_MAIL|mail1.txt
PICK_MAIL|mail2.txt
MULTI|multi.html
SAVE|save.html
PRINT|print.html
FWD|forward.html
FWD_MAIL|fwdmail1.txt
```
What each setting means and how to use them is explained in "customization" section.

Back to top or index
Changes from versions 3 and 4

This section describes only changes from previous versions, not the new features added. New features are documented in other sections of this guide.
1. Global configuration file is renamed from magic-conf.txt to magics.cfg. File format is changed - value-names separator now is | (pipe symbol) instead of > (greater than symbol). Same file format is used now for custom configuration files (e.g. magic.txt).
2. Custom configuration files are moved from $SCRIPT_DIR to a separate subdirectory $INC_DIR/conf. HTML templates, error templates and mail templates are moved to separate subdirectories within $INC_DIR. This was done to help cardmasters with big cardshops to organize their data more efficiently.
3. Card datafiles are now stored hierarchically - each day in a separate subdirectory. It allows to store cards for longer periods and longer "send later" periods. However be sure to check with your server's sysadmin first before changing settings to longer periods.
4. We have removed separate settings for the period to keep picked and not picked old cards and combined them to one setting STORED. This setting tells admin program to delete all cards older than $STORED regardless of the pickup fact.
5. Ticket number format was changed. Now it can contain only 15-17 digits. Ticket number format is described in "variables" section.
6. Email syntax checkup now conforms to RFC 822.
Back to top or index

Owner's Manual: Setup

Directories and permissions

Files and permissions

Global configuration file magics.cfg

Custom configuration files

Changes from versions 3 and 4