This documentation has been the work of many hours, but one fact remains clear: I am not good at writing documentation of any kind. therefore if anyone would like to volunteer to clarify sections of the documentation or to rewrite the whole thing I'd be more than happy to let them do so.
Conventions used
It is assumed that you are using the Apache web server. If not, then certain sections showing you how to do things using .htaccess/.htpasswd files will not be relevent. As this is the only server I have used I am unable to tell people what do do if they used something else - so if you could fillin these gaps I'd be grateful.
I also assume that you are installing sendcard in the location/directory http://yourdomain/sendcard/. If you install it elsewhere you will have to adjust the paths accordingly.
sendcard requires PHP 4 and a database. All testing is done using the latest version of PHP, but it should still work with previous versions.
Unzip the archive and extract the contents to a folder. You will get the following structure:
sendcard_3-X-X/
docs/
options/
sendcard/
The folder named sendcard is the one you need to upload, and in which you
will find all the files mentioned below. All paths given are relative to
sendcard/.
Read the license and check that you agree with the
terms and conditions. Read the text on security.
If you are on a Unix/Linux/FreeBSD server chmod the files sendcard.php, sendcard_setup.php,
admin/config.php, admin/plugins/<all files> and
include/lang/<all files> to 666 (that is, rw-rw-rw) so that the web
server
can write to them. To do this, you must either use your FTP program
and do each file manually, or if you have ssh access to your server
you can use the script chmod.php to do it for you. Run it via the
command line:
% php -q ./chmod.php
Delete this file once you have used it or if you are not going to use it. It is a security risk!
SENDCARD20 and get $20 off your hosting.
On Windows system you need to ensure these files are not write-protected and that they have global write permissions (see your servers documentation or contact your hosting provider if you are unsure on how to achieve this).
Go to http://yourdomain/sendcard/admin/index.php and log in using the
password:
password
Click on the link for the installation wizard and follow through the steps. Once you have finished, send yourself an e-card to check that everything is working. That's it!
If you have access to crontab on your server, you can easily set up the delayed send feature - allowing visitors to send cards that will arrive on the recipient's birthday for example.
Depending on the configuration of your server you can use one of the following tools to actually run the maintenance file: curl, fetch, lynx or wget. To find out which is supported by your server simply type the name of the tool on the command-line. If you get a message ‘command not found’ the tool isn’t supported on your server.
Based on which tool your server supports add one of the following lines to the cron.txt file:
# if your server supports curl:
0 */4 * * * curl -s -o /dev/null http://yoursite/sendcard/advancesend.php
# if your server supports fetch:
0 */4 * * * fetch -o /dev/null http://yoursite/sendcard/advancesend.php
# if your server supports lynx:
0 */4 * * * lynx > /dev/null -dump http://yoursite/sendcard/advancesend.php
# if your server supports wget:
0 */4 * * * wget -q -O /dev/null http://yoursite/sendcard/advancesend.php
Sometimes this may produce errors when run, saying that the command cannot
be found. If this is the case, type the command which
[[command name]] at the shell prompt to find out the full path to
the tool, and edit the above to reflect it. For example, if which
wget gave the result /usr/bin/wget, you would alter
the line above to:
0 */4 * * * /usr/bin/wget -q -O /dev/null http://yoursite/sendcard/advancesend.php
If you don't have access to crontab on your server, sign up for a free account with a service listed below and follow their instructions.
Certainly. I (the author) am available to install or customize sendcard to suit your needs. Please see the sendcard website for further details.
If you think that you can manage to do it yourself but are unable to work out how to do something then please search the forum. If you do not find the solution to your problem then post your question in the forum. I do not provide free support via email, so this is the only means to solve a problem.
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 linked to from that tutorial.
For extra security, rename the administration directory, or move it into a different folder (untested, but should work).
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 via the Configuration page in the administration area. PLEASE NOTE: I havenot tested that this will work with 3.2.X - so it may break sendcard (but I hope not)
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 such as Zeus or IIS 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. It only requires a basic knowledge of HTML and the ability to read the documentation!
Note that where variables have been entered by the user (for instance their name via the form) the form field's name is usually the lower case version of the template variables.
In the des file (usually card.tpl) we have:
{CONTENT} - This MUST be present! It is a placeholder in the design for the contents of form.tpl, message.tpl, message-left.tpl etc.
In the template file (usually message.tpl)
Private variables - these are filled by sendcard, and so just need to be present.
{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 - these hold values that the user supplies or you have passed to sendcard.
{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
{USER1} - Contains any input defined in user1
{USER2} - Contains any input defined in user2
{USER3} - Contains any input defined in user3
Obviously, just because a placeholder is called {FONTCOLOR} doesn't mean that it can only hold the font color - you could pass any value through with it (so long as it's not longer than the database field).
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. |
You can also use any of the strings in the language file within the template, using the syntax {LANG:key_of_entry}. So, to take a line from the langauge file:
$sc_lang['send_button_label'] = "Send this card";
To include the text 'Send This card' in your postcard, you would add the following tag to your template:
{LANG:send_button_label}
This is a great way to add text to your templates if you want to repeat it in many different locations, or if you only want one set of templates but multiple languages.
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="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". |
| 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="path/to/thumbnail.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.
Ideally all this would be done using a Dreamweaver/Golive extension, so you'd just have to fill out a form. I have a half-written Dreamweaver extension to do this, but I've never got round to finishing it... maybe one day :-).
You can use sendcard with multiple langauge websites without too many problems.
Step 1: You MUST pass sendcard.php a variable called 'sc_language' when the image is chosen, so that sendcard knows which langauge to use. If you don't then it will use the default langauge, defined in the administration area. By default this is English (en).
Step 2: There are now two options:
a)
You can create separate directories in
templates/ to hold the language specific templates.
b) If you only want
to use one
set
of templates
you
could use
the {LANG:placeholder} method and add extra language strings to the correct
language file in includes/lang/.
All the foreign language templates included with sendcard use method (a).
You have the choice of either duplicating replace.txt and putting a copy in each of the language directories (ideal if you have different emoticons for different languages) or you can leave the file in the templates/ directory and it will be used for all langauges (so long as a file named replace.txt isn't present in the language-specific directory). Confused? Just stick a replace.txt somewhere and see if it does what you want - sometimes the flexibility of sendcard is just a bit too great for everyday use.
Do NOT translate the comments in the templates (text between <!-- and -->).
Many comments are used by sendcard's template engine, and it only understands
English.
To translate sendcard into another language:
sendcard/templates/en to sendcard/templates/no.sendcard/include/lang/en to sendcard/include/lang/no.sendcard/index.php - I suggest calling it sendcard/index_no.php (where 'no' is the language code we're using in this case). Now, in each
of the codes for the cards (as seen in Creating
index.php) we need to add an extra hidden form field: <input type="hidden"
name="sc_language" value="no">. This tells sendcard
to show the templates in this language (Norwegian in this case).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="hidden" name="user3" value="{USER3}">
<input type="submit" name="Submit" value="Go">
</form>
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 -->
Similarly you can do the same thing for the font colour:
<select name="fontcolor">
<option value="#000000" selected>Black</option>
<option value="#ffffff">White</option>
<option value="#ffcc00">Orange</option>
</select>
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 value in the form input applet_name.
Use 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
using placeholders as shown above gives you more flexibility to reuse
the code for more than one applet.
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!
There is now a tutorial on this subject which supercedes the information below.
Open replace.txt in your favourite test editor. The syntax of each line is:
item to replace[tab]item to replace it with
From sendcard 3.2.0 onwards you can use 4 spaces instead of a tab - I know this makes it a lot easier for some people, as many programmers have their editors set to insert 4 spaces instead of a tab.
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>
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}". Of course
you could always make use of one of the three user-defined variables, {USER1},
{USER2}, {USER3}.
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 the value
attribute 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.
Log into the administration interface, and click on the "Translation" link. Scroll to the bottom of the page, and there is a box that allows you to enter the date format. 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.
Log into the administration area. Go to the configure screen and scroll down to advanced options. You will see an option asking for the image path. Change this path to http://yoursite/path/to/image/folder/ and send yourself a card.
You will have to edit the respective paths in templates/image.tpl to point to the correct location.
Yes, as of sendcard 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 OSI-certified Artistic License. This license is GPL-compatible (allowing sendcard to be used as a PHPNuke module for example) while offering some assurance that improvements will be contributed back to sendcard.
If you are modifying sendcard, please make sure to read section 3 of the 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 the number of people using sendcard continues to grow.
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.org/moral.php
for more details of how you can support the project.
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!
I (the author) can - and I can customise sendcard to exactly fit your needs. Please see my the sendcard installation page for more details.
Documentation for sendcard version 3.4.1. Last updated 10 August, 2006