My Postcards Platinum Web Application (ver.4) 

 Customizing Your CardShop 

 Introductory Notes  

Free electronic postcards are one of the most popular items on line and an ideal way to increase traffic to your site. The My Postcards Platinum software allows you to create the most customizable postcards available. This manual assumes that you have a medium to advanced level of knowledge of HTML, including basic knowledge of tables as well as form construction and layout. Advanced design and consulting services are available from several experienced designers through MyPostcards.com should you require further assistance - click here to view design offers. Click here to see what IS included into free support of Platinum software and what is not.

 How it works 

The core program of My Postcards Platinum (magiccard.cgi) collects information entered by the Sender via the web form, inserts that information into a preformatted design and mails notification to the specified recipient to pick up his card. Your Platinum application comes with all files necessary to set up a full service postcard site. Each, however, must be customized to match your individual needs.

Before proceeding make sure you have read the setup section and are already familiar with cardshop structure (files and directories) and global configurable options. For full list of files click here.

 Templates

In ROOT_DIR/includes directory you will find 6 error pages, sent, preview, receive templates and e-mail text files.

Various points in which the script inserts information into the templates are in the format
<!--@fieldname--> Program will place actual user submitted or server generated data in place of those placeholders.

Be very careful while editing files with such placeholders. DO NOT edit those files with HTML editor or word processor - only with plain text editor like Notepad for Windows or Textpad for Mac.

For full list of form elements with detailed explanation click here.

 E-mail templates  

Mail1.txt is the letter that will be sent to card recipients telling them to pick up their card. Again, this file should be edited so that the wording reflects the personality of your particular site. You will also need to edit the URL's in this message to reflect those of your particular location.

You may remove the alternative link if you care to do so. However, long experience has shown that this alternative pick up link saves many help inquiries. DO NOT RENAME THIS FILE!

Mail2.txt is the letter that is sent to card senders telling them that their card has been picked up. This should be edited in the same manner as Mail1.txt. Again, be very careful not to disturb the insertion points. Both files should be in plain text format and should appear in the file just exactly the same as you would like them to appear to the recipient. DO NOT RENAME THIS FILE!

Both mail1.txt and mail2.txt are plain ASCII text files, size limit to 20 KB for each. You can edit headers (if you are familiar with appropriate RFCs, if you don't know what is RFC - forget about it completely!)

 Card templates

Size for preview.html, receive.html and sent.html templates is not limited. You can use any symbols and html tags you would normally use on HTML page. You can use CSS, java script, Java, anything. However, if some symbols produce wrong output or don't print at all (for example % - percent symbol) - use alternative notation - (&#169 for copyright, &#37 for percent, etc.)

You may have more than one preview, receive and sent pages for different card layouts. However, this requires that you have another configuration file (e.g. magic.txt) specifying that particular preview page. If you choose to offer alternative card layouts, be sure to make a matching receive.html for each new preview.html. It is easiest to name these preview1, preview2 and so on.

Be sure to place your finished files back into the ROOT_DIR/includes directory.

 preview.html 

This is the page that the finished card will be shown to your Sender for final approval on. You may lay out this page in any manner that you desire, following the example of the included template. Where various options are placed is entirely up to you - just be sure that you specify each in this format: <!--@NAME OF ELEMENT HERE-->. For full list of supported form elements with detailed explanation click here.

Using the FCOLOR (font color) for an example, you would specify <!--@FCOLOR--> wherever you wanted that color to appear.

At the bottom of this form you will find a pair of <form></form> tags. This section contains automatically generated code which is passed to program. You can edit INPUT field value but do not touch anything else!

 receive.html 

This is the page on which the recipient will view his card. The easiest way to edit this page is to simply remove the <form></form> tags AND EVERYTHING BETWEEN THEM from the preview.htm. Place this file in the INCLUDES folder when you have finished.

 sent.html 

This is your final message to your guest, confirming the fact of postcard submission. Edit this page to reflect the personality of your particular card site. You may use appropriate tags for any of the various options that you wish to include on this page as long as they are formatted in the same manner as in previous templates.

There is a <!--@when--> placeholder which applies only to this particular template. Depending on when the sender scheduled a card to be delivered either the date will be inserted instead of this placeholder or "now" if it should be sent immediately.

 Error pages 

Each of the 6 error pages (Err_*.html) needs to be edited to reflect the design and personality of your postcard shop. These are each standard HTML files and are very straightforward. You should encounter no problems. Those files can be edited with any HTML editor.

You can completely reword error messages, but DO NOT RENAME THOSE FILES!!!

  Card composition pages 

Those are usual HTML pages and you can edit them with any editor of your choice. We included 4 sample card composition with different number of composition features

Those templates are included for demonstration sake, if you are familiar with forms, you can easily implement other layouts. You can test all those pages from Platinum Demo Cardshop - http://mypostcards.com/platinum/demo

When you have finished editing your card composition pages, you can place them inside any directory on your server, not necessarily ROOT_DIR.

 Available options 

The Platinum program allows you to offer a wide variety of options. For full list of supported form elements with detailed explanation click here.

You may choose to use as few or as many of the various options as you would like in designing your card site. Check Reference section for list of required form elements. You may lay out your Card Composition page in any manner that you desire and use any form elements you find convenient to allow your guests to access their various options and enter information.

However, all form elements must be contained within the <form> and </form> tags. Simply put your beginning <form> tag directly after the <body> tag and your ending </form> directly above the ending </body> tag at the bottom of your page.

Be sure to edit the <form action="path to your postcard script goes here" method="POST"> line. Your script will not function unless this is correctly done. If you have problems determining the relative path, simply use the exact URL beginning with the "http://". If you are not sure what that is, please contact Customer Service.

The template that you receive includes spaces for four thumbnail images. This may be increased should you desire to do so. It is advisable, however, not to exceed twelve images per composition page. You may have as many composition pages as you would like to offer.

PLEASE NOTE: The postcard layout is based on tables. Netscape and IE handle table elements quite differently. Often what looks wonderful in IE is not fit to be seen in Netscape, and vice versa. It is advisable that you install both browses and check your designs in both browsers before you go online with the finished product!

 How to reference image, midi and other files

Because you have specified in global configuration file magic-conf.txt where most of files are located, you do not need to include anything other than the file name when listing options for your pictures, midi, poetry and Java applets. The program already knows where to look for those items. You do however, need to give an exact URL (web address) for anything that you specify to be a stamp, background image or anything that you are using that is not from the location specified in magic-conf.txt.

You have an image file in your ROOT_DIR/images directory (ImageA.gif), but want to also use some other image file from another directory (ImageB.gif) and image file from different server (ImageC.gif).

The image that that is located in your ROOT_DIR/images you specify as:

<input type="radio" name="filename" value="ImageA.gif"> Image A

The image that that is located in directory other than the default one ROOT_DIR/images you specify as:

<input type="radio" name="filename" value="/full name of that directory/ImageB.gif"> Image B

The image file that is located on a different server you specify as:

<input type="radio" name="filename" value="http://www.elsewhere.com/dir/ImageC.gif"> Image C

If you would like to allow your guests to use their own image add the line like this:

<INPUT type="text" NAME="filename">

This will put an empty text box into the form where the sender can specify the URL of the picture that they would like to use. Be SURE to remind your guests, however, that they must use the complete URL, including the http://. Some webmasters find it easiest to include the http:// inside the quotation marks of the VALUE tag like so:

<INPUT type="text" NAME="filename" VALUE="http://">

In this case, the http:// will appear inside the text box, leaving the guest to enter only the remainder of the URL.

Please NOTE: You cannot provide both pictures from your server and the ability to use pictures elsewhere on the same card composition page without using special Java scripts which are not included into this software distribution!

All of above applies to sound selection.

If you would like to give your guests the option of entering their own Headings and Signatures rather than using your preformatted ones follow the same format as for the pictures. Again, you cannot have both preformatted and "use your own" elements on the same view page.

For choices where you have used a pop-up box, scroll box, checkboxes or radio buttons, such as your music, header and color options, it is advisable to include the option "none" as the first choice.

 How to make most of sound features 

The Platinum program supports sound in any format that you choose to offer it in. The basic sample uses standard midi files and "sound" form field. With "sound" files are embedded in browser-dependent way. For Internet Explorer and WebTV the syntax is:

<bgsound src="song.mid" autostart="true">

And for the rest of browsers

<EMBED SRC="song.mid" width="200" height="55" AUTOSTART="TRUE">

(optimized for Crescendo - most popular midi plugin for Netscape)

Of course *.wav files will playback just fine with these default settings, too.

If you want to change this syntax or add more browser/format dependent features - use placeholder <!--@sound_c--> instead of <!--@sound-->. This placeholder tells the script to put only a link to sound file and not attach any special code to it. This way you can embed any sound formats and use any plugin-specific tags.

A custom code could look like this:

< bgsound src=" <!--@sound_c-->" loop=0>
<embed src="< !--@sound_c-->" autostart=true volume="25" width=144 height=15 hspace=0 controls=smallconsole ></ embed>

Note that you MUST include both the <bgsound src> tag and the < embed src> tag! Otherwise half of your guests will not be able to hear your music.

While you are free to use Real Audio or other music formats, be advised that not all browsers support all formats. Should you use a format other than midi you will need to customize your sound tags.

 Poems and Java applets 

Any poetry that you would like to offer should be formatted EXACTLY as you wish it to appear on the finished card and saved as a plain txt file in the ROOT_DIR/poems directory. Poems are referenced in your Card Composition page as

< name="poem" value="poem.txt"> Name of Poem

DO NOT add any directories, domain names, http:// to value here. You might note that "Poems" do not have to be poetry - they could be recipes, Java applets, horoscopes and so on.

Java applets are also formatted exactly as you wish them to appear on the card and placed into the ROOT_DIR/poems directory. Format your applet as a text file, but save it with the extension .jav rather than .txt. Be sure to include the exact codebase for the applet and to upload your class files as binary files

Your Platinum program includes licensed Anfy Java Collection with 30 applets and an easy to use desktop configurator. Please contact Customer Support for more information about where to download your copies of these wonderful applets

 Specific issues for send later option 

Drop down menu with dates formatted for send later option is created automatically daily and is stored in ROOT_DIR/later.txt file. This file is embedded into your card composition pages with SSI directive INCLUDE (see source of card composition pages for full syntax).

If you see drop down menu with dates selection on your sample card composition pages - you have nothing to worry about, just be sure to keep the line with INCLUDE directive in every card composition page.

Depending on your particular webserver setup you may need to use *.shtml extensions for all your pages in order to enable SSI. On some webservers pages with *.html extensions will work just fine with SSI. If your server doesn't support SSI altogether (which is highly unlikely nowadays) - contact us and we will offer a workaround depending on your particular case.

If you have experience in Java-script programming you can replace this code with your own using following date format DD-MM-YYYY.

 Alternate card layouts 

We mentioned above that you could easily have different preview and receive pages for different card layouts. In order to do that you need to make another SCRIPT_DIR/magic.txt configuration file.

Open the original magic.txt in your text editor, and then SAVE AS. You can name this something like magic1.txt. By the way, you can have any number of these. All should be placed to SCRIPT_DIR along with magic.txt.

Edit the form so that it looks for the alternate preview and receive files (call those preview1.html and receive1.html)

Now, on your card composition page add the following line of code anywhere between the <form ></ form> tags:

<input type="hidden" name="config" value="magic1">

If you would like to give your guests a choice of layouts, you can make the options visible by writing the code like this:

<select name="select">
<option value="magic1">Layout 1
<option value="magic2">Layout 2
<option value="magic3">Layout 3
</select>

 Extras 

If you would like to include DAILY HOROSCOPES or MULTISEND options in your site, those are available for an extra fee. Please contact Support for more information on setting up these options and the new extras that could be available in the future.

 Miscellaneous tips and tricks

Image inserted with <!--@filename--> tag will appear on preview and receive pages with following HTML code <img src="filename" alt="Loading... Please wait" border="0">. There is no way to change this except for using text files with preformatted portions of HTML code " imagename.jav", which should be placed in ROOT_DIR/poems.

You will want to make an index.html file for each and every file folder to prevent unauthorized access to your files. If you do not do so, anyone can simply type in the name of the directory like this: http://www.yoursite.com/postcards/images And get a listing of the exact contents of your directory. Your index does not need to have even a single word on it as long as it has proper header and body tags. Just open a new HTML file, save it as index.html and upload it.

Good idea is to protect your stats directory with .htaccess to prevent unauthorized access from curious competitors. Do not however put .htaccess to any other directory of your cardshop - otherwise you can have problems with program functionality.

 // index // setup // customize // reference // admin // support // license //  

 My Postcards Platinum Web Application