Location: PHPKode > projects > Pieforms > pieforms-php5-0.2.2/doc/html/user/concepts.html
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns=http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>Pieforms Concepts and Terms</title>

<link rel="stylesheet" type="text/css" href="../style.css" />
</head>
<body>
<div class="document" id="pieforms-concepts-and-terms">
<h1 class="title">Pieforms Concepts and Terms</h1>
<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> &raquo; <a href="../">Documentation Home</a> &raquo; <a href="">Pieform Concepts and Terms</a></div></p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Nigel McNie</td>
</tr>
<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:nigel&#64;catalyst.net.nz">nigel&#64;catalyst.net.nz</a></td>
</tr>
<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">This document has been placed in the public domain</td>
</tr>
</tbody>
</table>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#background" id="id1" name="id1">Background</a></li>
<li><a class="reference" href="#concepts" id="id2" name="id2">Concepts</a><ul>
<li><a class="reference" href="#the-form-definition-hash" id="id3" name="id3">The form definition hash</a></li>
<li><a class="reference" href="#the-pieform-function-call" id="id4" name="id4">The <tt class="docutils literal"><span class="pre">pieform(...)</span></tt> function call</a></li>
<li><a class="reference" href="#the-testform-validate-function" id="id5" name="id5">The <tt class="docutils literal"><span class="pre">testform_validate</span></tt> function</a></li>
<li><a class="reference" href="#the-testform-submit-function" id="id6" name="id6">The <tt class="docutils literal"><span class="pre">testform_submit</span></tt> function</a></li>
</ul>
</li>
<li><a class="reference" href="#form-api-terms" id="id7" name="id7">Form API Terms</a><ul>
<li><a class="reference" href="#elements" id="id8" name="id8">Elements</a></li>
<li><a class="reference" href="#rules" id="id9" name="id9">Rules</a></li>
<li><a class="reference" href="#renderers" id="id10" name="id10">Renderers</a></li>
</ul>
</li>
<li><a class="reference" href="#how-they-fit-together" id="id11" name="id11">How They Fit Together</a></li>
<li><a class="reference" href="#other-features-of-pieforms" id="id12" name="id12">Other Features of Pieforms</a></li>
</ul>
</div>
<p>Pieforms is a development of the <a class="reference" href="http://mahara.org/">Mahara</a> project, that was later split out into
its own project on <a class="reference" href="http://pieforms.sourceforge.net/">sourceforge</a>. It provides a unified way to create, validate
and process forms all with a common look and feel, with support for pluggable
elements, renderers and validation rules.</p>
<p>What does that all mean? That's what this document is for - to describe the
overall concepts and ideas behind Pieforms.</p>
<div class="section">
<h1><a class="toc-backref" href="#id1" id="background" name="background">Background</a></h1>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">You can skip this section if you don't care for history lessons :)</p>
</div>
<p>In late 2006, the areformentioned Mahara project was in full swing. One of the
technical requirements identified was for a common API for displaying and
processing forms. Nigel was tasked with this job as he had claimed some
familiarity with various PHP form APIs. The three that were given some
consideration were <a class="reference" href="http://drupal.org/">Drupal's</a> forms API, PEAR's <a class="reference" href="http://pear.php.net/package/HTML_QuickForm">QuickForm</a> and Moodle's <a class="reference" href="http://moodle.cvs.sourceforge.net/moodle/moodle/lib/form/">form
API</a>, which was under development at the time.</p>
<p>Of the three, QuickForm was discarded nearly straight away, due to the large
amount of work to produce any one form, and indifferent experiences by members
of the development team in using it before. Moodle's API was briefly considered
but then dropped, as it appeared to have a similar, &quot;heavy&quot; API and was under
development at the time. This left Drupal's form API as the main contender, and
it probably would have won if it could have been pulled out of Drupal
successfully. Unfortunately, all efforts to extract it so that it would sit on
its own failed - it was too tightly bound to Drupal itself.</p>
<p>This resulted in the undersirable situation of one form API required vs. none
available. So in an orgy of weekend coding (and over the next few days at
work), Nigel cobbled together a form API with blackjack and hookers. And
amazingly, it worked pretty well. The best part was that writing forms was
insanely quick (including full validation). And soon after, Richard Mansfield
added 'AJAX form' support - forms that submitted very quickly because they were
posted and got their results asynchronously.</p>
<p>About the same time, Nigel made the elements, renderers and rules fully
pluggable by anyone who wanted to write a new one. It was then that he realised
that this little subproject had turned into a cool implementation of a form
API, that was worth splitting out into its own project. And thus, Pieforms was
born. The name was chosen as a tribute to a leaving team member, whose nick on
IRC was 'pie' :)</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id2" id="concepts" name="concepts">Concepts</a></h1>
<p>So, what is it that made Pieforms so easy to use and quick to build forms with?
It is because from the outset the library was designed to build forms with as
little work by the user as possible, instead of following a strict 'OO'
approach. As a result, the three or four things you need for a form are:</p>
<ul class="simple">
<li>A hash containing the form definition. Basically, this is a big array
describing the overall form properties, and the elements in the form</li>
<li>An optional callback function that can be used to validate a form submission
(which is practice is not required very often as the inbuilt rules handle most
validation)</li>
<li>A callback function that handles the submission of the form. This function
can do anything with the submitted values, in the knowledge that the values are
fully validated.</li>
<li>A call to the <tt class="docutils literal"><span class="pre">pieform()</span></tt> function, passing the form definition, which
manages the entire form building, validating, submitting and displaying
process.</li>
</ul>
<p>Here is an example of a simple form</p>
<pre style="background-color:#ffc;border:1px solid #cc9;"><a href="http://www.php.net/require_once"><span style="color:#a1a100;" title="php/php/keyword">require_once</span></a><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">pieform.php</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">;</span>

<a href="http://www.php.net/echo"><span style="color:#a1a100;" title="php/php/keyword">echo</span></a> <span style="color:#600;font-weight:bold;" title="php/php/functioncall">pieform</span><span style="color:#008000;" title="php/php/symbol">(</span><a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">name</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">testform</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">method</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">post</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">action</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">elements</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
        <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">details</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
            <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">type</span><span style="color:#f00;" title="php/php/single_string/end">'</span>   <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">fieldset</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
            <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">legend</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Your Details</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
            <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">elements</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
                <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">fullname</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">type</span><span style="color:#f00;" title="php/php/single_string/end">'</span>        <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">text</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">title</span><span style="color:#f00;" title="php/php/single_string/end">'</span>       <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Full name</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">description</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Please enter your full name</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">rules</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
                        <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">required</span><span style="color:#f00;" title="php/php/single_string/end">'</span>    <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="font-weight:bold;color:#000;" title="php/php/constant">true</span>
                    <span style="color:#008000;" title="php/php/symbol">)</span>
                <span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">,</span>
                <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">dob</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">type</span><span style="color:#f00;" title="php/php/single_string/end">'</span>        <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">date</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">title</span><span style="color:#f00;" title="php/php/single_string/end">'</span>       <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Date of Birth</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">description</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Your date of birth</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">defaultvalue</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/strtotime"><span style="color:#006;" title="php/php/function">strtotime</span></a><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">1st of January, 1985</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">,</span>
                    <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">rules</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
                        <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">required</span><span style="color:#f00;" title="php/php/single_string/end">'</span>    <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="font-weight:bold;color:#000;" title="php/php/constant">true</span>
                    <span style="color:#008000;" title="php/php/symbol">)</span>
                <span style="color:#008000;" title="php/php/symbol">)</span>
            <span style="color:#008000;" title="php/php/symbol">)</span>
        <span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">,</span>

        <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">submit</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <a href="http://www.php.net/array"><span style="color:#a1a100;" title="php/php/keyword">array</span></a><span style="color:#008000;" title="php/php/symbol">(</span>
            <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">type</span><span style="color:#f00;" title="php/php/single_string/end">'</span>  <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">submit</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span>
            <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">value</span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">=</span><span style="color:#008000;" title="php/php/symbol">&gt;</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Submit</span><span style="color:#f00;" title="php/php/single_string/end">'</span>
        <span style="color:#008000;" title="php/php/symbol">)</span>
    <span style="color:#008000;" title="php/php/symbol">)</span>
<span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">;</span>

<span style="color:#a1a100;" title="php/php/keyword">function</span> <span style="color:#600;" title="php/php/functionname">testform_validate</span><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#000;" title="php/php">Pieform</span> <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">form</span><span style="color:#008000;" title="php/php/symbol">,</span> <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">values</span><span style="color:#008000;" title="php/php/symbol">)</span> <span style="color:#008000;" title="php/php/symbol">{</span>
    <span style="color:#a1a100;" title="php/php/keyword">if</span> <span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#008000;" title="php/php/symbol">!</span><span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">form</span><span style="color:#008000;" title="php/php/symbol">-&gt;</span><span style="color:#933;" title="php/php/oodynamic">get_error</span><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">dob</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">)</span> <span style="color:#008000;" title="php/php/symbol">&amp;</span><span style="color:#008000;" title="php/php/symbol">&amp;</span> <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">values</span><span style="color:#008000;" title="php/php/symbol">[</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">dob</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">]</span> <span style="color:#008000;" title="php/php/symbol">&lt;</span> <a href="http://www.php.net/strtotime"><span style="color:#006;" title="php/php/function">strtotime</span></a><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">1st of January, 1950</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">)</span> <span style="color:#008000;" title="php/php/symbol">{</span>
        <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">form</span><span style="color:#008000;" title="php/php/symbol">-&gt;</span><span style="color:#933;" title="php/php/oodynamic">set_error</span><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">dob</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">,</span> <span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">I will give you another chance to lie about your age, OK? :)</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">;</span>
    <span style="color:#008000;" title="php/php/symbol">}</span>
<span style="color:#008000;" title="php/php/symbol">}</span>

<span style="color:#a1a100;" title="php/php/keyword">function</span> <span style="color:#600;" title="php/php/functionname">testform_submit</span><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#000;" title="php/php">Pieform</span> <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">form</span><span style="color:#008000;" title="php/php/symbol">,</span> <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">values</span><span style="color:#008000;" title="php/php/symbol">)</span> <span style="color:#008000;" title="php/php/symbol">{</span>
    <a href="http://www.php.net/print_r"><span style="color:#006;" title="php/php/function">print_r</span></a><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">values</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">;</span>
    <a href="http://www.php.net/exit"><span style="color:#a1a100;" title="php/php/keyword">exit</span></a><span style="color:#008000;" title="php/php/symbol">;</span>
<span style="color:#008000;" title="php/php/symbol">}</span></pre><p>Here is a description of each part.</p>
<div class="section">
<h2><a class="toc-backref" href="#id3" id="the-form-definition-hash" name="the-form-definition-hash">The form definition hash</a></h2>
<p>This array contains the definition of the form. In this example the form is
hard coded, and that would be what you would do most of the time, but there's
nothing to stop it from being generated dynamically. The array specifies some
metadata for the whole form, like its name, method and action target, and then
a list of elements that are on the form. Evary form must have a name, this name
is used to call the callback functions.</p>
<p>More information about the form array is available on a <a class="reference" href="usage.html">separate page</a>.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id4" id="the-pieform-function-call" name="the-pieform-function-call">The <tt class="docutils literal"><span class="pre">pieform(...)</span></tt> function call</a></h2>
<p>This call builds the form, validates and submits the form if it has been
submitted, and returns the HTML for the form. So in the example above the form
is simply <tt class="docutils literal"><span class="pre">echo</span></tt>'d to the browser, but it could easily be put into a <a class="reference" href="http://smarty.php.net/">Smarty</a> template variable or manipulated any way required.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id5" id="the-testform-validate-function" name="the-testform-validate-function">The <tt class="docutils literal"><span class="pre">testform_validate</span></tt> function</a></h2>
<p>This function is named after the form name, with <tt class="docutils literal"><span class="pre">_validate</span></tt> on the end. It
takes the Pieform object and an array of the submitted values, and can perform
whatever checks are required that cannot be otherwise handled by the inbuilt
form rules. In this case, rather than being a serious rule, a check is made to
give the older viewers a chance to not be so old :). Notice how it uses the
<tt class="docutils literal"><span class="pre">$form</span></tt> object to check for an error beforehand (which might have happened if
the &quot;required&quot; rule was violated, although generally that is quite hard to
violate with the &quot;date&quot; element), and uses it again to set an error on the
form.</p>
<p>This function is optional, as most of the time you will be able to perform all
the validation you require using rules. Notice in the array in the example how
each element had a 'required' rule. If that was all the validation you
required, you would not need the validate function. There are other rules
available, and it's easy to write your own.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id6" id="the-testform-submit-function" name="the-testform-submit-function">The <tt class="docutils literal"><span class="pre">testform_submit</span></tt> function</a></h2>
<p>This function is named after the form name, with <tt class="docutils literal"><span class="pre">_submit</span></tt> on the end. It
takes an array of the submitted values that have already been validated
successfully according to the validation rules set on the form. From here you
can do almost anything, but the last thing that you should do is either:</p>
<ul class="simple">
<li>Redirect the user to another page (perhaps back to this page if you wish to
always display the form to the user), if the form is a standard form</li>
<li>Reply with <tt class="docutils literal"><span class="pre">$form-&gt;json_reply(PIEFORM_OK,</span> <span class="pre">'optional</span> <span class="pre">message')</span></tt> if the form
is a JS form</li>
</ul>
<p>Because you will probably be writing a few forms, you should probably write a
wrapper for redirecting the user to another page, to save you time and effort
later. Something like this:</p>
<pre style="background-color:#ffc;border:1px solid #cc9;"><span style="color:#a1a100;" title="php/php/keyword">function</span> <span style="color:#600;" title="php/php/functionname">redirect</span><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">location</span><span style="color:#008000;" title="php/php/symbol">)</span> <span style="color:#008000;" title="php/php/symbol">{</span>
    <a href="http://www.php.net/header"><span style="color:#006;" title="php/php/function">header</span></a><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">HTTP/1.1 303 See Other</span><span style="color:#f00;" title="php/php/single_string/end">'</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">;</span>
    <a href="http://www.php.net/header"><span style="color:#006;" title="php/php/function">header</span></a><span style="color:#008000;" title="php/php/symbol">(</span><span style="color:#f00;" title="php/php/single_string/start">'</span><span style="color:#f00;" title="php/php/single_string">Location: </span><span style="color:#f00;" title="php/php/single_string/end">'</span> <span style="color:#008000;" title="php/php/symbol">.</span> <span style="color:#33f;" title="php/php/varstart">$</span><span style="color:#33f;" title="php/php/var">location</span><span style="color:#008000;" title="php/php/symbol">)</span><span style="color:#008000;" title="php/php/symbol">;</span>
    <a href="http://www.php.net/exit"><span style="color:#a1a100;" title="php/php/keyword">exit</span></a><span style="color:#008000;" title="php/php/symbol">;</span>
<span style="color:#008000;" title="php/php/symbol">}</span></pre><p>That is a very simple example, and one you will quite possibly want to extend
it further, perhaps to make specifying the location easier for example.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="form-api-terms" name="form-api-terms">Form API Terms</a></h1>
<p>Pieforms has several components, a basic description of each is given here.</p>
<div class="section">
<h2><a class="toc-backref" href="#id8" id="elements" name="elements">Elements</a></h2>
<p>Pieform <strong>elements</strong> are similar to the widgets you have in normal HTML forms,
and in fact all HTML widgets have element implementations in Pieforms. However,
Pieforms does not limit you to using just the standard HTML widgets - you can
write your own elements that have very advanced behaviour, are comprised of
multiple widgets, or do almost anything you like.</p>
<p>For example, there is a &quot;text&quot; element, which represents a simple HTML
<tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type=&quot;text&quot;&gt;</span></tt> widget. But there is also a &quot;date&quot; widget, which is
rendered as three <tt class="docutils literal"><span class="pre">&lt;select&gt;</span></tt> widgets for year, month and day, and a
&quot;calendar&quot; widget which is a full-blown popup javascript calendar! The Mahara
project created a &quot;wysiwyg&quot; element that is a full WYSIWYG editor (a native one
will be created for Pieforms soon), and many more besides.</p>
<p>It's really easy to write your own elements, and they can be reused on any form
that needs them. <a class="reference" href="elements.html">More information about elements</a>, including
how to write your own, is available.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id9" id="rules" name="rules">Rules</a></h2>
<p>Rules are used to validate elements. Given the element's value, they check if
the value matches a certain condition. There is a few simple rules implemented,
such as <em>required</em>, <em>minlength</em> and <em>maxlength</em> etc., but again like elements
they are pluggable, so many more can be written.</p>
<p>Rules may apply differently to different elements, so elements can define a
function that specifies how a rule applies to them, which allows some
flexibility in rule reuse.</p>
<p>More information on the <a class="reference" href="rules.html">rule API and writing your own rules</a> is
available.</p>
</div>
<div class="section">
<h2><a class="toc-backref" href="#id10" id="renderers" name="renderers">Renderers</a></h2>
<p>Renderers are used to output the containers that elements are rendered inside.
For example, there is a &quot;table&quot; renderer which puts each element inside a table
row, and a &quot;div&quot; renderer that puts them inside a <tt class="docutils literal"><span class="pre">&lt;div&gt;</span></tt>. Like elements and
rules, these are pluggable to suit your needs.</p>
<p>One thing that the Mahara project has done is added support for contextual help
for each element. The renderer will render question marks beside each form
element, which when clicked, reveal contextual help for the element. You could
add almost any extra information to each element, to assist your form output -
for example, a description, help text or raw HTML to be output at a certain
point for each element.</p>
<p>If all that was confusing, check out the <a class="reference" href="renderers.html">renderers</a> page
for more information.</p>
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id11" id="how-they-fit-together" name="how-they-fit-together">How They Fit Together</a></h1>
<p>Here are some statements that might help you understand how a form is put
together using Pieforms.</p>
<p>A <strong>form</strong> is made up of <a class="reference" href="elements.html">elements</a>.</p>
<p><strong>Elements</strong> are like standard HTML widgets, except they can be more
complicated and comprised of many widgets if necessary.</p>
<p>Elements are validated by <a class="reference" href="rules.html">rules</a>.</p>
<p>Each element in a form is rendered inside some boilerplate HTML provided by a
<a class="reference" href="renderers.html">renderer</a>.</p>
<p>When forms are <strong>submitted</strong>, they are <strong>validated</strong> using the <strong>rules</strong> for
each <strong>element</strong>. If validation passes, the form <strong>submit callback</strong> is called
with the values. If validation fails, the form is redisplayed, with the
<strong>renderer</strong> drawing the error messages as returned by the <strong>rule</strong> for each
<strong>element</strong> next to it.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id12" id="other-features-of-pieforms" name="other-features-of-pieforms">Other Features of Pieforms</a></h1>
<p>As well as customisable elements, renderers and rules, Pieforms has the
following features:</p>
<ul class="simple">
<li>Forms can be sent via GET or POST</li>
<li>Forms can be sent to different pages, as long as the form definition is
available on both pages</li>
<li>Support for <strong>cancel buttons</strong> - in effect, submit buttons with  no
validation applied to them</li>
<li><strong>Auto focus</strong> of fields in a form on page load, including focussing the
first element with an error if the form has failed validation</li>
<li><a class="reference" href="usage.html#jsform">JS forms</a> - forms submitted to a hidden iframe
with the result returned asynchronously, meaning the form behaves very
responsively</li>
<li>Automatic handling of <strong>tabindex</strong> for each element</li>
<li><strong>HTML 4.01 compliance</strong> (XHTML compliance will be added <a class="reference" href="../dev/todo.html#xhtml">later</a>)</li>
</ul>
<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> &raquo; <a href="../">Documentation Home</a> &raquo; <a href="">Pieform Concepts and Terms</a></div></p>
</div>
</div>

<div id="footer">Pieforms by <a href="http://nigel.mcnie.name/">Nigel McNie</a> and <a href="http://pieforms.sourceforge.net/about#authors">others</a>,
&copy; 2006 Catalyst IT Ltd. Pieforms is released under the <a href="http://gnu.org/licences/gpl.html">GNU GPL</a></div>
</body>
</html>
Return current item: Pieforms