PHP:Form uses a special HTML syntax to create forms. There are several different tags that are used by PHP:Form. Below is a complete list of all the tags.
| Tag | Attributes | Info | Example |
|---|---|---|---|
| php:form | name | Used as the opening and closing for a PHP:Form. | <php:form name="sampleform"> ... form html goes here ... </php:form> |
| validator |
form for name required regex callback numeric |
Used to validate a certain field. Most often used with text fields. | <validator for="test" required="true"> Error: Please fill in the test field </validator> |
| formtype | name src |
Used to specify a certain formtype. | <formtype name="text"> ... html of formtype goes here ... </formtype> |
| formfield | type | Used to display a form field with a certain type (that has been specified with a formtype tag). | <formfield type="text" /> |
Below is the HTML for a very simple PHP:Form with 2 text fields, a textarea and a few validators.
<php:form name="demo1">
Name: <input type="text" name="name" />
<validator for="name" required="true">Please enter your name</validator><br />
E-mail: <input type="text" name="email" />
<validator for="email" required="true">Please enter your e-mail address</validator><br /><br />
Comments:<br /> <textarea name="comments"></textarea>
<validator for="comments" required="true">Please enter some comments</validator><br /><br />
<input type="submit" name="submit" value="Submit Form" />
</php:form>
When you paste this in a HTML page, it will be recognized as a PHP:Form, however nothing will be displayed yet. To actually display a PHP:Form, you must invoke the display() method. In this case, it would be:
<?php
$_FORMS->display('demo1');
?>
Now the form will be displayed, no matter what happens. However, this may not be the result you want either. If the form validates, then there is no need to display it, and we should actually do something with the data (e.g. insert into a database, send e-mail, etc).
To check if a form validates, we can use the validate() method. For this example it would be:
<?php
// Does the form validate?
if (!$_FORMS->validate('demo1')) {
// Display form
$_FORMS->display('demo1');
} else {
// Print POST variables
print_r ($_POST);
}
?>
As you can see, we first check if the form validates, and if it doesn't, we display the form, and if it does we show all the POST variables.
That's pretty much how PHP:Form works, and how you should go about when creating PHP:Forms.
Please note: all HTML in the php:form must be valid XHTML, or else you will get an error message
PHP:Form has support for 5 different kinds of validators. They are used to validate your form, and make sure all the data is entered the way you want it to be.
The neat thing about about validators is that they work both server-side (in PHP) and client-side (in JavaScript). Whenever you create a new validator, the JavaScript will be automatically generated. This means that your visitors will have a pleasant experience when filling out your forms.
You can use validators throughout your page; they do not have to be between the php:form tags. Validators that are outside php:form tags must have the form="formname" attribute to attach them to a certain form. Validators that are between php:form tags do not need this attribute.
Required validators are used to make sure a field isn't empty. The correct syntax for a required validator is: <validator for="fieldname" required="true">Error message here</validator>.
Numeric validators are used to make sure a field contains only numbers. The correct syntax for a numeric validator is: <validator for="fieldname" numeric="true">Error message here</validator>.
Regex validators are used to make sure a field has data in a certain format. You can specify your own regular expression. The correct syntax for a regex validator is: <validator for="fieldname" regex="/test/i">Error message here</validator>. In this case, the value of the field must be 'test' (and nothing else). Perl-Compatible regex is used (learn more).
Callback validators are used for complex validations. In the callback attribute you can specifiy a function it should run on the server-side. It can either be a simple function name (e.g. is_email) or a object name and method name (e.g. myobj::is_email). The correct syntax for a callback validator is: <validator for="fieldname" callback="is_email">Error message here</validator>. On the client-side, you can also create a JavaScript function with the same name (e.g. is_email(str) or myobj_is_email(str) and that will be run. This is only optional though, and you do not have to create a JavaScript function.
Name validators are used to show custom errors or messages. The correct syntax for a name validator is: <validator name="name">Error message here</validator>. A name validator can only be shown when you invoke the trigger method, e.g. <?php $_FORMS->trigger_error ('formname', 'errorname'); ?>. This validator can be very useful in certain situations when you want to display a message only for certain conditions.
Another unique feature of PHP:Form is the ability to set default form values through PHP. You don't have to do difficult when trying to set default values, because PHP:Form makes it very easy:
<?php
$_FORMS->set_value ('formname', 'fieldname', 'value');
?>
That's the way to set a default value for any form field, including select boxes, checkboxes and radio buttons. Another neat thing is that you can pass an array as the value as well. This is especially useful for checkboxes and select boxes.
Note: values are automatically run through htmlentities() so you don't have to do that yourself.
PHP:Form will also re-fill the form automatically after a form has been POST'ed. This is mostly for validation purposes. Most regular forms will display an error message, and either tell you to go back, and edit the form, or you actually have to re-do the complete form (gasp!). But with PHP:Form that is no problem, as the form is automatically re-filled.
PHP:Form also supports form templates, called formtypes. Formtypes allows you to specify HTML templates for new types. This will save you considerable time when you want to create a form in a certain style. See below for a simple example.
<php:form name="demo1">
<formtype name="text">
<label for="{var:id}">{var:label}</label><input type="text" name="{var:name}" id="{var:id}" value="{var:value}" /><br />
</formtype>
<!-- This is used as the begin HTML for this form (formtype 'begin' is a special type) -->
<formtype name="begin">
<![CDATA[<form name="{var:name}" method="POST">]]>
</formtype>
<!-- This is used as the end HTML for this form (formtype 'end' is a special type) -->
<formtype name="end">
<![CDATA[</form>]]>
</formtype>
<formfield type="text" id="field1" name="field1" label="Field 1: " />
<formfield type="text" id="field2" name="field2" label="Field 2: " />
<formfield type="text" id="field3" name="field3" label="Field 3: " />
<formfield type="text" id="field4" name="field4" label="Field 4: " value="this has a default value" />
<formfield type="text" id="field5" name="field5" label="Field 5: " />
<input type="submit" name="submit" value="Submit Form" />
</php:form>
As you can see we created a new form type called text, and then displayed 5 form fields with that type. Another thing worth mentioning are the 'begin' and 'end' formtypes. They are special types, and can be used as a new template for the form beginning and end.
In the example you also see {var:name} and {var:label} in the formtype. These are special variables, and refer to the attributes in the form fields. For example, if in the formfield you have an attribute called 'foobar' with a value of 'qwerty', then {var:foobar} will contain 'qwerty'. There is also a special var called innerhtml, {var:innerhtml}, that contains the innerHTML of a formfield, e.g. <formfield>THIS IS THE INNERHTML</formfield>.
In some cases you might have to surround the HTML of a formtype with <![CDATA[ ... html goes here ... ]]>. This is necessary when the HTML is not valid XHTML. In the example this is the case with the begin and end type.
You can also create external form templates, and include these using the src attribute of a formtype. This works the same way as CSS stylesheets. Inline formtypes override external formtypes. To include an external formtypes, use the following syntax: <formtype src="path/to/external/formtypes.xml" />
PHP:Form will then include that file, and parse it for formtypes. An external formtypes file is a valid XML file that looks like this:
<?xml version="1.0" ?>
<form>
<formtype name="begin">
<![CDATA[
<form name="{var:name}" method="POST">
]]>
</formtype>
<formtype name="end">
<![CDATA[
</form>
]]>
</formtype>
<formtype name="text">
<![CDATA[
<label for="{var:id}">{var:label}</label><input type="text" id="{var:id}" name="{var:name}" value="{var:value}" /><br />
]]>
</formtype>
</form>
As you can see this does the exact same thing as the previous example, only now it's in an external file, and can be used by every form.
ob_end_* then PHP:Form will most likely not work. ob_start ('ob_gzhandler'); however there maybe problems still. ob_gzhandler has a bug in PHP version 4.3.4 and lower that causes output buffering to not fully work. We've developed a workaround, but this may not always work.For any questions, problems, comments or anything else, please visit our Community Support Forums or send us an e-mail at support@pallettgroup.com