Unzip the archive and extract the contents to a folder.
Read the license and check that you agree with the terms and conditions. Read the text on security. Upload the files in directory sendcard/ to your web server. You need to chmod sendcard.php, sendcard_setup.php, admin/config.php and the contents of the admin/plugins/ directory 666.
Now point your browser at http://yoursite/path/to/sendcard/admin/ You will need to use the password "password" to get in.
When the page loads, you may see broken images and javascript errors. This is OK, they will go away once you have configured the admin section.
At the bottom of the page it will say in bold print: "First time here?". Click on the link below it to set up the administration are so that it will work - if you don't then you will not be able to install sendcard. You will also have the option to CHANGE YOUR PASSWORD! Don't forget to do so!
Next click on the button on the left hand menu labelled "Configure". Change the setting to fit your needs - don't forget to enter the database details! Save the changes.
Scroll to the bottom of the configure screen and click on the link which says "Create Tables". Create both the tables.
The installation is now complete. Try sending yourself a postcard to check it is set up correctly.
The administration interface is protected using PHP4 sessions. However, I still recommend that you protect the directory using an .htaccess and .htpassword files, as two layers of protection is always better than one. If you don't know how to do this, please read this tutorial. There is also an .htpassword generator at this site.
For extra security, rename the administration directory, or move it into a different folder (untested, but should work).
You have two options:
1. Try it and see if you get errors. I think you will because you'll get the "Warning: Call to undefined function" message.
2. This does require you to edit the code. Open prepend.php, remembering to make a backup first, and locate the part which looks like
session_start();
if($session["password"] != ADMIN_PASSWORD || !$session["password"])
{
header("Location: login.php?redirect=" . basename($PHP_SELF));
}
Either delete this code, or comment it out.
Whichever of the above solutions you take, you MUST protect the directory using .htaccess/.htpassword files.
You may also need to use an .htaccess file to recognize the .php file extension. For more details click here
The easiest (and most secure) way is to move the directory outside the web tree (e.g. above your document root) where it is not visible to anyone. If you do this you must change the path to the template directory in the configuration (under "Advanced Options").
If you cannot do this then the best way is to make an .htaccess file containing the following line and put this in the template directory:
<Directory />
Order Deny, Allow
Deny from All
</Directory>
Please note that this will only work if you are using the Apache web server. If you use a different server, and know how to protect a directory, please get in contact.
The templates use the PHPLib template class, documentation for which can be found on their website. You are encouraged to customize the supplied templates to make the design fit your web site.
Note that where variables have been entered by the user (for instance in the form) the input name is usually the lower case version of the template variables.
In the des file (usually card.tpl)
{CONTENT}
In the template file (usually message.tpl)
Private variables
{INVALIDTO_EMAIL} - if a recipient's email address is invalid, this will show the error message.
{INVALIDFROM_EMAIL} - if the sender's email address is invalid, this will show the error message.
{IMG_PATH} - the path to the directory containing the images.
Public variables
{IMG} - the place you want the picture to show up.
{BGCOLOR} - the background colour.
{FONTCOLOR}
{FONTFACE}
{CAPTION} - the caption defined.
{IMAGE} - name of the image
{IMG_WIDTH} - the width of the image
{IMG_HEIGHT} - the height of the image.
{TO} - recipient's name
{TO_EMAIL} - recipient's email address
{FROM} - sender's name
{FROM_EMAIL} - sender's email address
The table below shows how the form elements relate to these template placeholders.
| Form element name | Template variable | Notes |
|---|---|---|
| to[{I}] | {TO} | Name of the recipient(s) |
| to_email[{I}] | {TO_EMAIL} | Email address(es) of the recipient(s) |
| from | {FROM} | Sender's name |
| from_email | {FROM_EMAIL} | Sender's email address |
| fontface | {FONTFACE} | |
| fontcolor | {FONTCOLOR} | |
| bgcolor | {BGCOLOR} | |
| template | n/a | controls the layout of the form (Note: currently interferes with a template value set in index.php |
| music | {MUSIC} | The name of the music file |
| message | {MESSAGE} | The message |
| image | {IMAGE} | Name of the image |
| caption | {CAPTION} | |
| num_recipients | {NUM_RECIPIENTS} | Number of recipients which the card is to be sent to |
| des | n/a | Name of the outer template to be used. Must not have the extension ".tpl". Default value is "card". |
| preview | n/a | This is the name of the submit button and MUST be present
in form.tpl. If you don't want to have the preview stage, change it to send |
| applet_name | n/a | Contains the name of the java applet to be used. Decides which java block is to be included in the template. |
If you've looked at the source code of index.php maybe you're confused as to how it works. Here, I hope to show you.
Each image for the card is set up using the following code:
<form method="post" action="sendcard.php">
<input type="image" border="0" value="Submit"
src="images/tn_starburst.gif" width="200" height="120"
name="image">
<input type="hidden" name="image" value="imgname.gif">
<input type="hidden" name="caption" value="Lots
of stars are visible here">
<input type="hidden" name="des" value="test">
<input type="hidden" name="template" value="templatename">
<input type="hidden" name="fixed_layout" value="1">
<input type="hidden" name="img_width" value="nnn">
<input type="hidden" name="img_height" value="nnn">
<input type="hidden" name="applet_name" value="applet_block_name">
</form>
You do not have to use every <input>
shown above, apart from the top two. Those you don't need, leave out of your
code as this will make it less cluttered. Let us consider the hidden inputs
one at a time.
| Name | Required | Notes |
|---|---|---|
| image | Yes | The name of the image file to be used in the card. |
| caption | No | The caption to be displayed under the picture in {CAPTION} |
| des | No | Allows you to specify an alternative design to use around the card. The default is "card" |
| template | No | Allows you to specify an alternative layout for the card. The default is "template". |
| fixed_layout | No |
If you specify a special template you may not want to allow the sender to select different templates in the card. By setting this to "1", the option in form.tpl to do this will be hidden. In practice, it is probably easier to miss this out and just delete the code from form.tpl, although this will mean that none of the cards can have this option. If you delete the code from form.tpl, you CAN NOT use this option. |
| img_width | No | Specifies the width of the image. Not needed if the image is a GIF, JPEG, PNG or SWF file. |
| img_height | No | Specifies the width of the image. Not needed if the image is a GIF, JPEG, PNG or SWF file. |
| applet_name | No | The name of the block containing the code for the java applet. See here for further details. |
so for instance, the most basic image could look like:
<form method="post" action="sendcard.php">
<input type="image" border="0" value="Submit"
src="images/tn_starburst.gif" width="200" height="120"
name="image">
<input type="hidden" name="image" value="imgname.gif">
</form>
Of course, usually you'd want to add a caption at the very least.
If you edit form.tpl and are intending to use the multiple recipients feature, you must be careful that you don't prevent it from working.
The form inputs for the recipients name and email address must be surrounded by <!-- BEGIN recipient_block --> and <!-- END recipient_block -->. This is so that they can be duplicated when the card is sent to more than one person.
The contents of the form asking whether you want to send the card to more than one person must not be altered, or you risk the card not working properly. It should look like:
<form method="post" action="">
How many people would you like to send this card to? (if one person,
please skip this step)
<select name="num_recipients">
<option value="1" selected>1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
<option value="6">6</option>
</select> <input type="hidden" name="image" value="{IMAGE}">
<input type="hidden" name="caption" value="{CAPTION}">
<input type="hidden" name="des" value="{DES}">
<input type="hidden" name="template" value="{TEMPLATE}">
<input type="hidden" name="applet_name" value="{APPLET_NAME}">
<input type="hidden" name="img_width" value="{IMG_WIDTH}">
<input type="hidden" name="img_height" value="{IMG_HEIGHT}">
<input type="hidden" name="user1" value="{USER1}">
<input type="hidden" name="user2" value="{USER2}">
<input type="submit" name="Submit" value="Go">
</form>
If you remove any of the fields from form.tpl, you must check to see if they are listed at the top of the file under /* BEGIN AUTHOR SPECS */ and if so, you must remove the corresponding line, or risk getting a javascript error
You can change the way the colours are selected to one of the following code snippits. Please note that these are only examples - make your own if you want!:
<!-- Table row for setting the background colour.
If you don't want this feature then remove it -->
<tr>
<td width="140">Choose the background Colour:</td>
<td width="80%">
<select name="bgcolor">
<option value="#000000">Black</option>
<option value="#ffffff" selected>White</option>
<option value="#ffcc00">Orange</option>
</select>
</td>
</tr>
<!-- End table row for setting the background colour -->
Or
<!-- Table row for setting the background colour.
If you don't want this feature then remove it -->
<tr>
<td width="140">Choose the background Colour:</td>
<td width="80%">
<table width="275" border="0" cellspacing="3"
cellpadding="0">
<tr align="center">
<td><font size="-1">Default</font></td>
<td bgcolor="#FFFFCC"> </td>
<td bgcolor="#CCFFCC"> </td>
<td bgcolor="#333399"> </td>
<td bgcolor="#CC0000"> </td>
<td bgcolor="#333333"> </td>
</tr>
<tr align="center">
<td><input type="radio" name="bgcolor" checked></td>
<td><input type="radio" name="bgcolor" value="#FFFFCC"></td>
<td><input type="radio" name="bgcolor" value="#CCFFCC"></td>
<td><input type="radio" name="bgcolor" value="#333399"></td>
<td><input type="radio" name="bgcolor" value="#CC0000"></td>
<td><input type="radio" name="bgcolor" value="#333333"></td>
</tr>
</table>
</td>
</tr>
<!-- End table row for setting the background colour -->
And for font colour:
<select name="fontcolor">
<option value="#000000" selected>Black</option>
<option value="#ffffff">White</option>
<option value="#ffcc00">Orange</option>
</select>
OR
<table width="275" border="0"
cellspacing="3" cellpadding="0">
<tr align="center">
<td><font size="-1">Default</font></td>
<td bgcolor="#660066"> </td>
<td bgcolor="#FFCC99"> </td>
<td bgcolor="#006699"> </td>
<td bgcolor="#006600"> </td>
<td bgcolor="#FFFFFF"> </td>
</tr>
<tr align="center">
<td>
<input type="radio" name="bgcolor" checked>
</td>
<td>
<input type="radio" name="bgcolor" value="#660066">
</td>
<td>
<input type="radio" name="bgcolor" value="#FFCC99">
</td>
<td>
<input type="radio" name="bgcolor" value="#006699">
</td>
<td>
<input type="radio" name="bgcolor" value="#006600">
</td>
<td>
<input type="radio" name="bgcolor" value="#FFFFFF">
</td>
</tr>
</table>
Applets each have their own block in image.tpl (in the templates directory). The syntax for the block is as follows:
<!-- BEGIN java_block_Appletname -->
<applet code="classname.class" codebase="{IMG_PATH}"
width="{IMG_WIDTH}" height="{IMG_HEIGHT}">
[params if needed]
Sorry, your browser does not support java :-(
</applet>
<!-- END java_block_Appletname -->
where Appletname is the name in the form input applet_name. Using a codebase of {IMG_PATH} only if you are going to put the applet class files in your images directory. Any of the settings could of course be hard-coded - however by using the placeholders {XXX} gives you more flexibility.
The above code is for an applet which displays an image, with special effects. Have a look at the sample blocks in image.tpl, and then see if you can modify them to suit your needs. By looking at them you'll probably understand it much better!
If you have crontab available on your web hosting account, then you can use this to run advancesend.php. You need to use Lynx or wget. I do not have access to crontab, so have never tried it, but these are what other people have said:
You must include the next line in your crontab file:
0 0,8,16 * * * lynx -dump
www.your-domain.com/path-to-sendcard/advancesend.php >/dev/null 2>&1
and next type this command:
$ crontab cronjobs
where cronjobs is the file that contains the line mentioned
The best way to call sendcard using cron is to set it up with a wget
command. See the example below:
wget -q http://www.xyz.com/sendcard/advancesend.php
This will use the wget utility from the cron to call the advancesend.php
file as many times as you like.
If you don't have access to crontab on your server, sign up for a free account with QWKMon or a similar company. Set up a HTTP monitoring job pointing to advancesend.php, and tell it to check the page every 6 or 12 hours (I prefer 6, but if you don't want too much extra traffic to your server, 12 will do).
Open replace.txt in your favourite test editor. The syntax of each line is:
item to replace [tab] item
to replace it with
Suppose we want to turn :-) into an image each time it appears in the card. To do so, we would add the following line:
:-) <img src=\"images/foobar.gif\">
Note that it should be a tab instead of a large space between the two items. If it isn't, it won't work
You can download some emoticons from
http://homepage.eircom.net/~bray/em.htm
http://volmeister.tripod.com/emoticons/emoticons.html
http://www.geocities.com/jabot2000/emoticons.html
My favourite ones are at http://www.anduin.de/emoticons/
There is one emoticon included with sendcard by default. To try it, send yourself a card, and place [rolleyes] in the message. Have a look at replace.txt to see how this one was set up.
The simplest way is to not allow them to select a background colour, and
then you can use the {BGCOLOR} variable to
hold the image. So, in form.tpl you would assign to the radio buttons for
the selection of background image the names of the images. In card.tpl/message.tpl
you would change bgcolor="{BGCOLOR}
to background="{BGCOLOR}".
Open form.tpl and find the line <input type="submit"
name="preview" value="Preview the card">
Change it to read <input type="submit"
name="send" value="Send the card"> where value
can equal anything you wish.
To do this you will have to edit the PHP source of sendcard, as well as image.tpl. Before you start, back up your existing versions of these files, in case you make a mistake...
Open image.tpl and see if one of the blocks has the correct code in it for your media type -- for instance, the embed_block section will cover most things, and is actually the default for unknown media types.
The problem is probably that you are using a different file extension to the ones which sendcard is set up to recognize. Let us suppose that your java applets end in .jar, which would prevent them from using the correct code in image.tpl.
Open functions.tpl and find
function set_img_block($image)
Look further through this
function until you find the line which looks like }
elseif( ereg("\.(class)$", trim($image)) ) {
Change it to look like }
elseif( ereg("\.(class|jar)$", trim($image)) ) {. The vertical line
"|" means OR, so the block of code defined here will be used by
*.class OR *.jar files.
If you don't understand that, then I suggest you read a few tutorials on regular expressions :-)
This is a little harder to correct! Open image.tpl and
add the code you need. The code must be surrounded by two comments in the
format
<!-- BEGIN somename_block -->where somename is a descriptive name for the purpose of the
code in the block.
[code goes here]
<!-- END somename_block -->
Now, open functions.php, and scroll down until you see function
set_img_block($image) .
Copy the following section into a new file
} elseif( ereg("\.(class)$", trim($image)) ) {
$tpl->set_block("img_tags", "java_block");
$code = $tpl->get_var("java_block");
Alter it to look like:
} elseif( ereg("\.(ext)$",
trim($image)) ) {
$tpl->set_block("img_tags", "somename_block");
$code = $tpl->get_var("somename_block");
where ext is the file extension, and somename is the name of the blockin image.tpl. Remember, if there is more than one file extension to separate them with "|".
Add the new code in just below the original section that you copied, and test it.
Open sendcard.php. At the top you will find a line which looks like:
// This prints the format: "Sunday 8th October
at 09:57 GMT"
$date = date("l jS F")." at ".date("H:i T");
Edit this line to fit your needs. You can find out about the different options available by reading the page in the PHP manual.
The administration interface should be self-explanatory, and each module should hopefully have its own help. The documentation therefore concentrates on writing modules.
Modules comprise of at least two files: modi_xxx.php and mod_xxx.php. Modi_xxx.php is used to create the entry in the menu of the admin area, and currently should look something like:
<?php
// Name to appear in the menu
$mod_name = "Module Name";
// Only used if path to module is not the same directory as menu.php
// currently not used.
// $mod_path = "";
?>
mod_xxx.php contains the code to be executed when someone clicks on the link in the menu. The file must have right at the top the following:
<?php
include("prepend.php");
?>
There must be no whitespace before the <?php tag, otherwise
it will not work properly.
Prepend.php includes all the variable in config.php, allowing you to use them in your script, and also provides the authentication security layer, preventing unauthorised people from altering the configuration of sendcard. This relies on PHP4 sessions at the present time - if enough people are using PHP3 then I will rewrite it.
Once you have included prepend.php, you are free to include other files as you wish.
Modules do not have to be released under the QPL, as they are separate programs rather than part of Sendcard. (If anyone thinks this is wrong, and I've misunderstood the license, please get in touch)
More documentation on writing modules will follow.
These are the constants which are made available via prepend.php. They are available as defined constants, rather than the usual $variables, preventing them from being modified.
| Name | Notes |
|---|---|
| DOCROOT | The system path to the directory where sendcard is installed (eg /home/user/web/sendcard/ or C:/apache/htdocs/sendcard/ ) |
| SENDCARD_HOST | The url to the directory where sendcard is installed (eg http://somehost.com/sendcard/ ) |
| SENDCARD_DIR | The path from the web root (eg sendcard/ ) |
In sendcard, a plugin is a separate piece of code to be inserted in sendcard.php in a certain place. This allows other people to develop extras to work with sendcard, and for you to install them without having to edit sendcard.php (though at the moment you'll have to edit any other files necessary.
In sendcard.php at certain points, there are comments which look like /***
plugin before_view ***/. These are placeholders, marking where plugin
code can be inserted. I have not listed the placeholders here, because before
you can use them you need to look in sendcard.php to see which is in the best
position.
The position of the plugin sites is not set in stone: if you believe one would be better somewhere else, or that another one would be useful, please email me, and I'll change it in a future release of sendcard.
I am unsure of the license issues for plugins, and whether they have to be released under the QPL.
Under your administration folder you should have a folder called "plugins". Into this folder you need to put any plugins that you download. Once you have done this, go to the administration interface and click on the link labelled "Plugins". This will bring up a list of all plugins in that folder, with a description about each and whether or not they are installed.
Click on the link that says "Install". You may be prompted to enter some information, or the plugin may install immediately. when you next go to the plugin page, the link should have changed from "Install" to "Uninstall". To remove the plugin, click on this link. You will be asked if you are sure you want to remove it, and if you say yes, the plugin will be uninstalled. You will still have to manually delete the file from the plugins directory.
The easiest way is to look at the plugins in the admin/plugins/ directory to get an idea of how they are written. Play around with these plugins, and try and build your own from them. Look in sendcard.php for the comments in the form /*** plugin some_name ***/. Change the line which looks like this in one of the plugins, and see what happens in sendcard.php.
The variabled which go in the plugin files are described in more detail below.| Variable | Notes |
|---|---|
| $plugin_name | Name of the plugin. This must be the same as the name in comments around the code you are inserting, and it's a good idea to give the file this name as well. |
| $plugin_description | Tells people what your plugin does |
| $plugin_installed | Must equal 0. It is changed to 1 when the function is installed. |
| $plugin_installed_msg | Message shown when the plugin is installed |
| $plugin_uninstalled_msg | Message shown when the plugin is uninstalled. |
| $plugin_edit | Not yet implemented. |
| $plugin_set_variables | 1 if you have a function called set_variables(), 0 if you don't. |
| $plugin_original_code | An array of the placeholder names in sendcard.php which you want to insert your code just below |
| $plugin_replacement_code | An array of the code to be added. |
The plugin above as actually a more complicated example than most, because it asks the user for some information (in this case the table name) before inserting the code, using the function plugin_set_variables() to collect it. If $plugin_set_variables = 1 then a form will automatically be generated to collect the information, and plugin_set_variable() executed. In the function you do not need to generate the form tags or the submit button: these are done automatically.
More documentation on writing plugins will follow.
Yes, as of version 3.03 you can provided you are using PHP 4. If you are using sendcard 3.02 or earlier, then you need PHP 4.0.5 or greater and PCRE support enabled. PHP in templates is disabled by default. To enable it, log into the administration interface and click on "Configure". Look under advanced options for the setting.
Sendcard is released under the Trolltech QPL. By using sendcard you are agreeing to the terms of this license.
Please note: sendcard includes a "Powered by sendcard" button which is installed by default. While it is not a license violation to remove this button, it is requested that the attribution remain. A significant investment has been put into sndcard, and this effort will continue if the sendcard community continues to grow. This is one way to assure that growth.
Don't understand the QPL? Read the annotated version
There are two reasons why this may not work:
If the problem is the second, and you are using the Apache web server, place an .htaccess file in your sendcard directory with he following lines:
If you are using PHP3:
AddType application/x-httpd-php3 .php3 .php .phtml
DirectoryIndex index.php index.php3 index.phtml
If you are using PHP4:
AddType application/x-httpd-php .php3 .php .phtml
DirectoryIndex index.php index.php3 index.phtml
OK, you don't have to love it, but your support would still be very welcome
:-)
Please see http://www.sendcard.f2s.com/support.php
for more details.
If you can't find the answer to your problem, ask your question in the forum. This is the preferred method because it means that the answer will be available for everyone to read.
If you've found a mistake in the documentation please contact me. I've tried my best with this documentation, but as I have written sendcard as well I forget what may cause problems to other people. If you think I've missed something, or you can't understand what I'm talking about, get in touch and I'll see what I can do!
Well, I don't wish to push my services too hard, but I can install it for you. Please see my services page for more details.
Version 0.14 Last revised 22 October, 2001