Using Phorm

Phorm™ v3.5.2

Technical Terms

There are a couple of technical terms which are unavoidably used in this documentation. If you are not a programmer, you should make sure you understand them (of course, if you are a programmer, you should definitely make sure you understand them):

Variable: A variable is simply something which holds a value. It can hold a number, or a string of characters. When your form is submitted, the values of the fields are stored in variables, which Phorm is then able to use. When setting up Phorm, you will use variables to tell it values such as email addresses, etc.
Array: An array is a collection of variables grouped together and handled as a single thing. For example, you might have an array called Names, which would simply have a list of names. Each item in an array is called an element, and an index determines which element you're referring to. Thus, $Names[2] would refer to the second name in the list. See the note Multi-value Form Fields in Appendix A for an important note about this.

Using Phorm:

To use Phorm, name it in the ACTION attribute of your FORM tag:

   <FORM NAME="Form" METHOD=POST ACTION="phorm.php">

Note that, when your form data is passed to Phorm, all the field names become variable names. Variable names in PHP start with a dollar sign. Form field names, of course, do not. So, for example, if you have the following in your form:

   <INPUT TYPE=TEXT NAME="FirstName" SIZE=30>

then the contents of this field will be accessible to Phorm in the variable $FirstName. In this documentation, generally I've tried to use a dollar sign if I'm talking about a variable, and to leave it off when I'm talking about a field. But for all practical purposes, they're essentially the same thing. Important Note: Since all your fields are being converted to PHP variables, the names must be legal PHP variable names. PHP variable names must begin with a letter or the _ (underscore) character, and consist only of letters, numbers and the _ character. Letters are defined as A-Z, a-z and ASCII characters 127 through 255. PHP variable names are case-sensitive, so name is not the same as Name.

Phorm's Internal Variables

Phorm uses many internal variables when it operates, as well as the configuration variables described in this documentation. In order to avoid having internal variables with the same name as form fields, all Phorm configuration variables start with $PHORM_, and all Phorm internal variables start with either $ph_ or $xPHORM_, where x is any letter. What this means to you is that you should avoid having any field name starting with PHORM_ unless it's actually one of Phorm's configuration variables that you're using, or any field name starting with ph_ or xPHORM_.

Since the $ph_ variables are so intimate to the operation of Phorm, there is a security measure to prevent them from being manipulated. When Phorm starts up, the first thing it does is erase any variables starting with $ph_. This prevents someone from sending bogus controls to your installation of Phorm to try to abuse it.

Variable Substitution

An important concept in using Phorm is "variable substitution". As mentioned above, all your form fields are converted to PHP variables. These can then be inserted into email messages, your acknowledgement page, and many other places. To include the value of a form field somewhere, simply enclose the name in double curly braces. For example, supposing you had a field named "FirstName" with the visitor's first name. You could then say:

   Thank you for subscribing to our newsletter, {{FirstName}}!
   We're sure you'll enjoy it!

The places where variable substitution is applicable will be mentioned throughout the documentation. See the note Multi-value Form Fields in Appendix A for something to watch out for in this.

Special Variable

There is a special variable named {{ph_FORMDATA}}, which will list all the fields from your form, and their values. You can use it in your acknowledgement template or your email template(s). Fields which are empty will not be included. If you wish them to be, add an F to the variable name: {{ph_FORMDATAF}}.

Other Variables

You can also use any other variables, such as environment variables. For example, if you wanted to know your visitor's IP, you could include {{REMOTE_ADDR}} in your mail template. Environment variables are beyond the scope of this document, but you can find a list at http://hoohoo.ncsa.uiuc.edu/cgi/env.html

PHP3: Phorm is fully compatible with PHP3 -- simply change the file extension to .php3. The only file that needs to be changed is Phorm itself - phorm.php. Other files are not executed directly, but instead are called by Phorm; they can remain as named.

0101000001101000011011110111001001101101010010010111001101000011011011110110111101101100