Documentation

Configuring the fields >> << Creating a form

Creating the HTML

As mentioned in the previous section the form's HTML is all placed in a single file. This file's name consists of the forms name followed by .form.php. A form may be named anything as long as it will make a valid filename.

To create a new form create a new file inside of the forms directory (php/SimpleContactForm/forms/).
Make sure to format the file's name correctly eg. contact.form.php

The form tag

Every form is required to have at least the following :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<form method="POST"
      action="<?php echo '#' . $this->id ?>"
      id="<?php echo $this->id ?>"
      class="SimpleCF-container">
     
    <!-- Form initialization -->
    <?php $this->HTMLFormHeader() ?>
     
    <!-- Form fields goes here -->
    <!-- ... -->
     
    <!-- Submit button -->
    <input type="submit" value="Send" name="Submit-<?php echo $this->id ?>">
     
</form>

This simply creates the HTML form element that will be used to submit the enquiry.
The form tag has the following attributes :

  • The method attribute tells the browser how the form data should be submitted; most people will not need to worry about this.
  • The action attribute tells the browser where to submit the form to.
    The # tells the browser to scroll to this form after it has been submitted.
  • The id attribute uniquely identifies this form and is required for the form to function correctly.
  • The class attribute assigns a style to the form and is required for the form to function correctly.

Line 7 calls the form's HTMLFormHeader() function which automatically includes some HTML needed by the form.
The submit button code is very simple; to change the button text just modify the value attribute.

Creating fields

Each field should be in the following format :

1
2
3
4
5
<div class="field<?php $this->HTMLCheckField('FIELD-NAME') ?>">
    <label for="FIELD-NAME" id="FIELD-NAME-label">FIELD-DISPLAY-NAME :</label>
    <input name="FIELD-NAME"<?php $this->HTMLGetValue('FIELD-NAME') ?>
           id="FIELD-NAME" class="textfield">
</div>

It would be possible to include only the input tag with the name attribute set but the other code is required to for client side validation and styling.
All instance of FIELD-NAME should be replaced with a name uniquely identifying this field eg. ContactNumber
FIELD-DISPLAY-NAME is simply a label identifying the field for the user and may be anything.
The HTMLCheckField function checks a field and marks it if validation failed.
The HTMLGetValue function retrieves and outputs the value attribute of this field after the form is submitted. The value will automatically be wrapped in a value attribute eg. value="FIELD_VALUE"

As an example here is the code for the contact number field of the default form :

1
2
3
4
5
<div class="field<?php $this->HTMLCheckField('Number') ?>">
    <label for="Number" id="Number-label">Contact Number :</label>
    <input name="Number"<?php $this->HTMLGetValue('FIELD-NAME') ?>
           id="Number" class="textfield">
</div>

You may now copy this code and give each field an appropriate name.

Text Area

The code above creates a single line text box; Another common input is a multi-line text area.
To create one is simple, just replace the input tag with a textarea tag. This code is from the message field of the default form :

1
2
3
<textarea id="Message" name="Message" class="textbox" rows="6" cols="32">
<?php $this->HTMLGetValue('Message', true) ?>
</textarea>

The textbox class is needed to style the text area.
The HTMLGetValue retrieves and outputs the value of this field after the form is submitted. The second parameter of the function tells it to only output the value without the value attribute.
Notice also that the HTMLGetValue function is called between the textarea opening and closing tags.

Verification

Most people will also want a verification field to prevent spam bots from exploiting the contact form.
The verification field is similar to a regular field and should follow the same basic format as above but requires some extra code.

A verification field needs to display the verification image (or text, if the useTextCaptcha configuration option is set to true).
To do this you must call the HTMLFormVerification function. The default form includes this in the fields label tag :

1
2
3
4
<label for="Verification" id="Verification-label">
    Verification :<br>
    <?php $this->HTMLFormVerification('Verification') ?>
</label>

The default form calls the verification field Verification but you may change this to anything you like.

A verification field should also display a link allowing the user to request a different verification incase the current one is difficult to understand :
<a id="FIELD-NAME-refresh"></a>.
Nothing else is needed here and FIELD-NAME should be changed to match.
In the default form this link is include after the fields input text box :

1
2
<input id="Verification" name="Verification" size="14" class="textfield"><br>
<a id="Verification-refresh"></a>

Combo box

Here is the code for a combo box :

1
2
3
4
5
6
<select name="FIELD-NAME" class="combobox">
    <option<?php $this->HTMLGetSelectedState('FIELD-NAME', OPTION-VALUE) ?>>OPTION-VALUE</option>
    <!-- Option 2 -->
    <!-- Option 3 -->
    <!-- ... -->
</select>

A combo box is created with the select HTML tag.
The HTMLGetSelectedState function checks if the option specified by OPTION-VALUE has been selected.

Check box

Here is the code for a check box :

1
2
3
<input type="checkbox" value="OPTION-VALUE"
       name="FIELD-NAME"<?php $this->HTMLGetCheckedState('FIELD-NAME', 'OPTION-VALUE') ?>
       > OPTION-LABEL

The HTMLGetSelectedState function checks if this check box has been ticked.
Check boxes can be grouped by creating multiple check boxes with the same name. Brackets must also be added after the field name of each checkbox to tell the script that they belong to a group :

1
<input type="checkbox" name="FIELD-NAME[]" ... >

As a reference the code for the entire default form is shown here :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<form method="POST" action="<?php echo '#' . $this->id ?>" id="<?php echo $this->id ?>" target="_self" class="SimpleCF-container">
    <?php $this->HTMLFormHeader() ?>
     
    <!-- Form fields -->
    <div class="field<?php $this->HTMLCheckField('Name') ?>">
        <label for="Name" id="Name-label">Name :</label>
        <input id="Name" name="Name"<?php $this->HTMLGetValue('Name') ?> size="40" class="textfield">
    </div>
     
    <div class="field<?php $this->HTMLCheckField('Email') ?>">
        <label for="Email" id="Email-label">Email :</label>
        <input id="Email" name="Email"<?php $this->HTMLGetValue('Email') ?> size="40" class="textfield">
    </div>
     
    <div class="field<?php $this->HTMLCheckField('Number') ?>">
        <label for="Number" id="Number-label">Contact Number :</label>
        <input id="Number" name="Number"<?php $this->HTMLGetValue('Number') ?> size="40" class="textfield">
    </div>
     
    <div class="field<?php $this->HTMLCheckField('Message') ?>">
        <label for="Message" id="Message-label">Message :</label>
        <textarea id="Message" name="Message" class="textbox" rows="6" cols="32"><?php $this->HTMLGetValue('Message', true) ?></textarea>
    </div>
     
    <!-- Verification -->
    <div class="field<?php $this->HTMLCheckField('Verification') ?>">
        <label for="Verification" id="Verification-label">
            Verification :<br>
            <?php $this->HTMLFormVerification('Verification') ?>
        </label>
        <input id="Verification" name="Verification" size="14" class="textfield"><br>
        <a id="Verification-refresh"></a>
    </div>
     
    <!-- Submit button -->
    <input type="submit" value="Send" name="Submit-<?php echo $this->id ?>">
</form>

Before the form can be used the fields need to be configured in the scripts configuration file.
The settings in this file tell the script what fields to expect and also how to validate them.
A mail template also needs to be created to which will be used to insert the form data into an email.

Configuring the fields >> << Creating a form

SimpleContactForm