My Postcards Platinum Web Application (version 5)

Owner's Manual: Setup

  1. Directories and permissions
  2. Files and permissions
  3. Global configuration file (magics.cfg)
  4. Custom configuration files
  5. 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
  1. 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
  2. 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.
  3. 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

  4. 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.

  5. 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.

My Postcards Platinum Web Application, version 5.
Copyright 1996-2000 Webby, Inc. All rights reserved.