Rev 1 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>contact_us.php Documentation</title>
<meta name="GENERATOR" content="Quanta Plus">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<style>
td {
border: inset 1pt;
text-align : left;
vertical-align : top;
}
TABLE {
border: outset 1pt;
border-collapse: separate;
border-spacing: 1pt;
}
pre {
font-size : 8pt;
line-height : 8pt;
word-spacing : 0px;
}
</style>
</head>
<body>
<h1>contact_us.php</h1>
<h2>User Documenation</h2>
<p>contact_us is a series of php scripts to allow rapid creation of a contact us form in any web based application.</p>
<p>It is designed with virtual hosting, ie more than one web site hosted on a given server. In the author's site, a common alias for all domains (named, strangely enough, common-cgi) is created outside any single domains directory tree. Thus, to use the contact form, a particular web site simply creates a link to /common-cgi/contact_us.php. However, for single domain implementations, contact_us.php (and its associated contact_us_lib.php) may be placed in the web sites directory tree, if desired. <em>Note, the web server must allow php code to be executed in this location.</em></p>
<h3>How does it work?</h3>
<p>When called, contact_us.php determines who called it. First, it looks for a session variable named 'contact_us home' and, if that is not populated, it takes HTTP_REFERER and tears it apart to determine the caller. Especially important is the fact the script looks for the calling domain name and path within the domain name. This allows for contact_us.php to be called from not just multiple web sites, but multiple locations within a web site with different actions.</p>
<p>At this point, contact_us.php takes DOCUMENT_ROOT, applies the directory information found above, and applies it to DOCUMENT_ROOT to determine the local path being used by the process that called it. <strong>NOTE that, for this reason, you can not call contact_us.php from any server other than the one your domain is on.</strong> By this, we mean you can not call contact_us.php from a server other than the one your site is hosted on.</p>
<p>contact_us.php then looks for a file named contact_us_local.php in the directory found above. This file is then included (via php's include_once command) in the script and its variables and defines used to build the page dynamically</p>
<p><emp>Other Important Files:</emp> contact_us.css from the root directory of the calling domain is included. See below for information on its structure</p>
<p>Once the user presses the Submit button on the form, validation, contact_us.php is called again. The form is verified and, if all required fields are filled in, the action(s) set up in contact_us_local.php (currently e-mail and database) are performed. If the actions succeed, a success message is displayed, otherwise a failure message is displayed</p>
<h3>contact_us_local.php structure</h3>
<p>The variables available in contact_us_local.php are defined in tables 1 through 3. Additionally, to implement database storage of acquired data, see section below tables for recommended and required modifications to contact_us_local.php.</p>
<table>
<caption><strong>Table 1:</strong> contact_us_local.php Variables</caption>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>$HEADER</td>
<td>Contains html that is placed at the top of the contact us form. This information lives in a <div></div> block with an id of header</td>
</tr>
<tr>
<td>$SUCCESS_MESSAGE</td>
<td>Plain text message displayed if the form action is successful</td>
</tr>
<tr>
<td>$FAILURE_MESSAGE</td>
<td>Plain text message displayed if the form action is not successful</td>
</tr>
<tr>
<td>$WINDOW_WIDTH</td>
<td>If the form resizes itself, this will be its width, in pixels</td>
</tr>
<tr>
<td>$WINDOW_HEIGHT</td>
<td>If the form resizes itself, this will be its hieght, in pixels</td>
</tr>
<tr>
<td>$CATEGORIES</td>
<td>An array (hash) of values for each possible category. See details in table 2</td>
</tr>
<tr>
<td>$FIELDS</td>
<td>An array (hash) definining the fields displayed on the form. See table 3 for additional information</td>
</tr>
<tr>
<td>$MAX_DISPLAY_WIDTH</td>
<td>The maximum width of input fields, in characters. Used to limit the max size of all <input> and <textarea> fields</td>
</tr>
<tr>
<td>define(SEND_EMAIL,[true|false])</td>
<td>Not a varialbe, per se, but a constant definition. If this is set to false (allowed values, true or false, 1 or 0), and e-mail is not sent when the form action is performed. Defaults to true if this constant is not defined.</td>
</tr>
</tbody>
</table>
<p>contact_us.php generally has multiple categories which are displayed in a <select> at the top of the page. This provides a recipient of the e-mail (so the same form can send to different recipients) and a subject for the e-mail.</p>
<p>$CATEGORIES is an array whose key is numeric. This key determines the order of the categories in the <select>, ie the lowest number is the first, the next lowest is second, etc... The numbers do not have to be sequetial.</p>
<p>Each array element is in turn an additional array (hash), with the keys that are strings. These are defined in Table 2 below</p>
<table>
<caption><b>Table 2:</b> $CATEGORIES field definitions</caption>
<thead>
<tr>
<th>Variable</th>
<th>Use</th>
</tr>
</thead>
<tbody>
<tr>
<td>title</td>
<td>String displayed in <select> box.</td>
</tr>
<tr>
<td>email</td>
<td>e-mail address of recipient for forms submitted with this category</td>
</tr>
<tr>
<td>subject</td>
<td>Subject displayed on e-mail when form submitted</td>
</tr>
</tbody>
</table>
<p>There are no predefined fields with contact_us except the inital <select>. The remainder of the fields are defined via the $FIELDS variable.</p>
<p>The $FIELDS variable is an array, similar to the $CATEGORIES variable, with an numeric index that determines the order the fields appear on the form. Again, lowest value goes first, up to highest value. If two values are the same, the second one physically in the definition overwrites the previous one(s)</p>
<p>Each element of the $FIELDS array is itself an array, with string index keys. Some keys, such as <em>title</em>, <em>type</em> and <em>required</em> are available in all fields. However, other fields do not make sense except in fields defined to be of a certain type.</p>
<p>There are two major types defined, <em>text</em> and <em>textarea</em>, which have a direct correlation to the html entities of these names. Currently, there is limited supports for the types but they are placed there for future expansion whereby validation and helper scripts could allow differentiation between text, numeric, dates, etc...</p>
<p>Table 3 shows the variable definitions available in a $FIELDS entity</p>
<table>
<thead>
<tr>
<th>Key</th>
<th>Description</th>
<th>Applicable To</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td>varname</td>
<td>unique name of variable on form. THIS IS REQUIRED and must be distinct from other names. Note that this is also the column name if storing results in a database (see below)</td>
<td>All Elements</td>
<td><strong>None. Required</strong></td>
</tr>
<tr>
<td>type</td>
<td>'text' or 'textarea'. 1-1 correlation with the html entities of the same name</td>
<td>All Elements</td>
<td>text</td>
</tr>
<tr>
<td>cols</td>
<td>Number of columns to display in <textarea></td>
<td>textarea</td>
<td>$maxDisplayWidth</td>
</tr>
<tr>
<td>rows</td>
<td>Number of rows to display in <textarea></td>
<td>textarea</td>
<td>10</td>
</tr>
<tr>
<td>class</td>
<td>Overrides the CSS class for the field</td>
<td>All Elements</td>
<td>text-area</td>
</tr>
<tr>
<td>maxlength</td>
<td>Maximum length of <input> field</td>
<td>text</td>
<td>unlimited</td>
</tr>
<tr>
<td>size</td>
<td>display size of <input> field</td>
<td>text</td>
<td>lesser of maxlength and $maxDisplayWidth</td>
</tr>
<tr>
<td>required</td>
<td>if true or 1, the form will not process unless a value is placed within the field</td>
<td>All Elements</td>
<td>false</td>
</tr>
</tbody>
</table>
<h3>Example Code</h3>
<p>Following is an example of a contact_us_local.php, with a discussion below</p>
<pre>
<?php
$HEADER = 'Daily Data, Inc.<br>
Post Office Box 140645<br>
Dallas TX 75214-0465<br>
214.827.2170<br>
<p>Please use the form below to send us your questions or concerns.
We review all messages sent to us and will try to reply as soon as possible.
Thank you.</p>';
$SUCCESS_MESSAGE = 'Thank you. Your e-mail has been sent and will be processed by our
staff on the next business day. We appreciate your comments and suggestions';
$FAILURE_MESSAGE = "I'm sorry, your message was not able to be sent, please try again later";
$WINDOW_WIDTH = 620;
$WINDOW_HEIGHT = 620;
$MAX_DISPLAY_WIDTH = 40;
$CATEGORIES = array(
7 => array('title' => 'Web Site Issues',
'email' => 'webmaster@mydomain.com'
),
3 => array('title' => 'Request for Information',
'email' => 'sales@mydomain.com',
'subject' => 'Sales inquiry from web'),
1 => array('title' => 'Work Request',
'email' => 'helpdesk@mydomain.com',
'subject' => 'CLIENT WORK REQUEST')
);
$FIELDS = array (
1 => array( 'title' => 'Name',
'type' => 'text',
'varname' => 'name',
'max length'=> 30,
'class' => 'text-field',
'required' => true
),
3 => array( 'title' => 'Company Name',
'type' => 'text',
'varname' => 'company_name',
'max length'=> 30
),
7 => array ('title' => 'Phone Number',
'varname' => 'phone',
'type' => 'text',
'max length'=> '15',
'required' => true
),
8 => array ('title' => 'e-mail',
'varname' => 'email',
'type' => 'text',
'max length'=> '64',
'required' => true
),
9 => array( 'title' => 'Contact Instructions',
'type' => 'textarea',
'varname' => 'contact_instructions',
'columns' => 40,
'rows' => 4,
'class' => 'text-area'
),
10 => array( 'title' => 'Message',
'type' => 'textarea',
'varname' => 'message',
'columns' => 40,
'rows' => 10,
'class' => 'text-area'
)
);
>
</pre>
<h3>Discussion of Example</h3>
<p>The first five lines after <?php are fairly self explainatory. They simply define some variables.</p>
<ul><li>$HEADER will be placed at the top of the form. NOTE that this can have embedded graphics, whatever. It is your header</li>
<li>$SUCCESS_MESSAGE and $FAILURE_MESSAGE are displayed upon success or failure of the form action</li>
<li>$WINDOW_WIDTH and $WINDOW_HEIGHT are used to determine the height and width of the window created</li>
<li>$MAX_DISPLAY_WIDTH sets the maximum display width on all text and textarea fields to 40</li>
</ul>
<p>The next block defines the categories available. Note that there are three, and the order will be Work Request, then Request for Information, then Web Site issues. Each of these go to a separate e-mail address, and each will have a subject defined in above except for Web Site Issues. Since this has no Subject defined, it will use the category title (Web Site Issues) as its subject line.</p>
<p>The final block definess the fields that are displayed. Note that we are going to ask for 6 fields, two of which are required (e-mail and name). Since Message and Contact Information are free form and may contain multiple lines, we make the type='textarea'</p>
<h3>Database Integration</h3>
<P>contact_us now has the ability to store the results of a form submission into a database in addition to, or instead of, e-mailing the results (ie, any one or more actions)</P>
<p>This is set up currently through a series of defines. Table 4 shows these:</p>
<table>
<caption><emp>Table 4: </emp>Database Required Constants</caption>
<thead>
<tr>
<th>Constant</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>DATABASE</td>
<td>The database to connect to. This is currently only available for MySQL</td>
</tr>
<tr>
<td>DB_TABLE</td>
<td>The table in the database that contains columns compatible with the form (see notes)</td>
</tr>
<tr>
<td>DB_USERNAME</td>
<td>user name that has write access to the above table</td>
</tr>
<tr>
<td>DB_PASSWORD</td>
<td>Password for above user. NOTE, this is very insecure at this point as anyone with read access to your web directory would have access to your database</td>
</tr>
</tbody>
</table>
<p><strong>DB_TABLE Requirements</strong> DB_TABLE must contain a column for each varname defined in the $FIELDS array, and the type of the column must be compatible with the possible values inputted. Remember, Never Underestimate the Power of Human Stupidity (Robert Heinlein, <quote>Time Enough for Love</quote>). Just because you tell someone to put a numnber into a field does not mean they will do so, and the current verions of contact_us does not verify that a field is numeric. I would suggest using only varchar and text columns.</p>
<p>When the form is posted, contact_us will open a connection with the database and insert a new row containing the values from the form. Be very, very careful with this function; consider it beta until further testing is performed.</p>
If the following code were added to the above example, it would add a separate action to be performed after the e-mail was sent.
<pre>
define (DATABASE,'web_requests');
define (DB_TABLE, 'web_info');
switch ($_SERVER['SERVER_NAME']) {
case 'localhost' : define (DB_USERNAME, 'test' );
define (DB_PASSWORD, 'test' );
break;
case 'server.mydomain.com' :
case 'alias.mydomain.com' :
case 'alias' : define (DB_USERNAME, 'timetracker' );
define (DB_PASSWORD, 'timetracker' );
break;
}
</pre>
<p>When a form was submitted, contact_us would connect to the database web_request using the username and password determined by the switch statement. It would then create an SQL statement as follows:</p>
<pre>
insert into web_info (name,company_name,phone,email,contact_instructions,message)
values (
makeSafeSQLValue($_POST['name']),
makeSafeSQLValue($_POST['company_name']),
makeSafeSQLValue($_POST['phone']),
makeSafeSQLValue($_POST['email']),
makeSafeSQLValue($_POST['contact_instructions']),
makeSafeSQLValue($_POST['message']),
)
</pre>
<h5>Note: makeSafeSQLValue is a function that validates, escapes and quotes a value in preparation for inclusion in an SQL statement. It also returns the unquoted string <em>null</em> if the value is not set</h5>
</body>
</html>