[Pieforms-commit] SF.net SVN: pieforms: [199] pieforms-php5/branches/0.2.0/doc
Status: Alpha
Brought to you by:
oracleshinoda
Menu
▾
▴
[Pieforms-commit] SF.net SVN: pieforms: [199] pieforms-php5/branches/0.2.0/doc
|
From: <ora...@us...> - 2007-03-18 12:36:11
|
Revision: 199
http://svn.sourceforge.net/pieforms/?rev=199&view=rev
Author: oracleshinoda
Date: 2007-03-18 02:05:07 -0700 (Sun, 18 Mar 2007)
Log Message:
-----------
Added HTML documentation
Added Paths:
-----------
pieforms-php5/branches/0.2.0/doc/html/
pieforms-php5/branches/0.2.0/doc/html/html4css1.css
pieforms-php5/branches/0.2.0/doc/html/index.html
pieforms-php5/branches/0.2.0/doc/html/style.css
pieforms-php5/branches/0.2.0/doc/html/user/
pieforms-php5/branches/0.2.0/doc/html/user/concepts.html
pieforms-php5/branches/0.2.0/doc/html/user/configuration.html
pieforms-php5/branches/0.2.0/doc/html/user/elements.html
pieforms-php5/branches/0.2.0/doc/html/user/examples.html
pieforms-php5/branches/0.2.0/doc/html/user/features.html
pieforms-php5/branches/0.2.0/doc/html/user/usage.html
Added: pieforms-php5/branches/0.2.0/doc/html/html4css1.css
===================================================================
--- pieforms-php5/branches/0.2.0/doc/html/html4css1.css (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/html/html4css1.css 2007-03-18 09:05:07 UTC (rev 199)
@@ -0,0 +1,279 @@
+/*
+:Author: David Goodger
+:Contact: go...@us...
+:Date: $Date: 2005-12-18 01:56:14 +0100 (Sun, 18 Dec 2005) $
+:Revision: $Revision: 4224 $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left {
+ clear: left }
+
+img.align-right {
+ clear: right }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em ;
+ background-color: #eeeeee }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+tt.docutils {
+ background-color: #eeeeee }
+
+ul.auto-toc {
+ list-style-type: none }
Added: pieforms-php5/branches/0.2.0/doc/html/index.html
===================================================================
--- pieforms-php5/branches/0.2.0/doc/html/index.html (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/html/index.html 2007-03-18 09:05:07 UTC (rev 199)
@@ -0,0 +1,111 @@
+<?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: Advanced web forms made easy</title>
+
+<link rel="stylesheet" type="text/css" href="style.css" />
+</head>
+<body>
+<div class="document" id="pieforms-advanced-web-forms-made-easy">
+<h1 class="title"><a class="reference" href="http://pieforms.sourceforge.net/">Pieforms</a>: Advanced web forms made easy</h1>
+<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> » <a href="">Documentation Home</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@catalyst.net.nz">nigel@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>
+<p>The latest copy of the Pieforms documentation may be obtained from SVN:</p>
+<blockquote>
+<tt class="docutils literal"><span class="pre">svn</span> <span class="pre">co</span> <span class="pre">https://pieforms.svn.sourceforge.net/svnroot/pieforms/pieforms-php5/trunk</span> <span class="pre">pieforms</span></tt></blockquote>
+<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="#general-documentation" id="id1" name="id1">General Documentation</a></li>
+<li><a class="reference" href="#user-user-documentation" id="id2" name="id2"><tt class="docutils literal"><span class="pre">user/</span></tt>: User Documentation</a></li>
+<li><a class="reference" href="#ref-reference-material" id="id3" name="id3"><tt class="docutils literal"><span class="pre">ref/</span></tt>: Reference Material</a></li>
+<li><a class="reference" href="#howto-miscellaneous-articles" id="id4" name="id4"><tt class="docutils literal"><span class="pre">howto/</span></tt>: Miscellaneous Articles</a></li>
+<li><a class="reference" href="#dev-core-development-information" id="id5" name="id5"><tt class="docutils literal"><span class="pre">dev/</span></tt>: Core Development Information</a></li>
+</ul>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id1" id="general-documentation" name="general-documentation">General Documentation</a></h1>
+<p>These files may be of interest to any Pieforms user.</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"><a class="reference" href="../../README">README</a>:</th><td class="field-body">The project overview, requirements, and licensing details</td>
+</tr>
+<tr class="field"><th class="field-name"><a class="reference" href="../../COPYING">COPYING</a>:</th><td class="field-body">Pieforms is licensed under the <a class="reference" href="http://gnu.org/licenses/gpl.html">GNU GPL</a>, this file contains a full
+copy of the license</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id2" id="user-user-documentation" name="user-user-documentation"><span id="user"></span><tt class="docutils literal"><span class="pre">user/</span></tt>: User Documentation</a></h1>
+<p>These files contain documentation about how to use Pieforms. They will be of
+interest to almost any Pieforms user.</p>
+<ul class="simple">
+<li><a class="reference" href="user/concepts.html">Pieforms Concepts and Terms</a> - basic Pieforms
+concepts. <strong>Read this first!</strong></li>
+<li><a class="reference" href="user/features.html">Pieforms Feature List</a> - list of major Pieforms
+features</li>
+<li><a class="reference" href="user/configuration.html">Pieforms Configuration</a> - instructions on
+installation and basic configuration of Pieforms</li>
+<li><a class="reference" href="user/usage.html">Basic Usage</a> - A step by step guide to writing your
+first Pieform</li>
+<li><a class="reference" href="user/examples.html">Examples of Pieforms</a> - examples that show
+Pieforms usage, and may give you good ideas</li>
+<li><a class="reference" href="user/elements.html">Elements</a> - General information about elements
+including a list of elements that come with Pieforms.</li>
+<li><a class="reference" href="user/renderers.html">Renderers</a></li>
+<li><a class="reference" href="user/rules.html">Rules</a></li>
+<li><a class="reference" href="user/i18n.html">i18n</a></li>
+</ul>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id3" id="ref-reference-material" name="ref-reference-material"><tt class="docutils literal"><span class="pre">ref/</span></tt>: Reference Material</a></h1>
+<p>These files contain developer specifications and reference notes that will be
+of interest to anyone who wishes to write plugins for Pieforms, or re-implement
+it in another language.</p>
+<ul class="simple">
+<li><a class="reference" href="ref/api/index.html">Pieforms frontend API documentation (in phpdoc form)</a></li>
+<li><a class="reference" href="ref/elements.html">Element API</a></li>
+<li><a class="reference" href="ref/renderers.html">Renderer API</a></li>
+<li><a class="reference" href="ref/rules.html">Rule API</a></li>
+<li><a class="reference" href="ref/i18n.html">i18n API</a></li>
+</ul>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id4" id="howto-miscellaneous-articles" name="howto-miscellaneous-articles"><tt class="docutils literal"><span class="pre">howto/</span></tt>: Miscellaneous Articles</a></h1>
+<p>These files contain various documentation about the use of Pieforms in many
+situations.</p>
+</div>
+<div class="section">
+<h1><a class="toc-backref" href="#id5" id="dev-core-development-information" name="dev-core-development-information"><tt class="docutils literal"><span class="pre">dev/</span></tt>: Core Development Information</a></h1>
+<p>These files contain information for Pieforms hackers, administrators and others
+involved with the Pieforms source.</p>
+<ul class="simple">
+<li><a class="reference" href="dev/coding.html">Pieforms Coding Standards</a></li>
+<li><a class="reference" href="dev/todo.html">Pieforms TODO List</a></li>
+</ul>
+<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> » <a href="">Documentation Home</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>,
+© 2006 Catalyst IT Ltd. Pieforms is released under the <a href="http://gnu.org/licences/gpl.html">GNU GPL</a></div>
+</body>
+</html>
Added: pieforms-php5/branches/0.2.0/doc/html/style.css
===================================================================
--- pieforms-php5/branches/0.2.0/doc/html/style.css (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/html/style.css 2007-03-18 09:05:07 UTC (rev 199)
@@ -0,0 +1,88 @@
+/*
+ :Author: Nigel McNie
+ :Contact: ni...@ca...
+ :Copyright: This stylesheet has been placed in the public domain.
+
+ Stylesheet for use with Docutils.
+
+ TODO:
+ - style a bit more like the website (green header, margins)
+ - header should have the links like the rest of the site to various places
+ - some kind of breadcrumbs
+ */
+
+@import url(html4css1.css);
+
+html, body {
+ font-family: Verdana, sans-serif;
+ font-size: 0.9em;
+ margin: 0;
+ padding: 0;
+}
+body {
+ width: 90%;
+ margin: 0 auto;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ font-family: "Trebuchet MS", sans-serif;
+}
+a[href!=""] {
+ color: blue;
+ text-decoration: underline;
+}
+a:visited {
+ color: #551a8b;
+}
+a:active {
+ color: blue;
+}
+h1.title {
+ background-color: #cfc;
+ border-bottom: 1px solid #393;
+ color: #6a6;
+ padding: 0.7em;
+ margin: 0 -5.5%;
+}
+h1.title a {
+ color: #6a6;
+}
+h2, h3 {
+ margin: .5em 0 .25em;
+ color: #363;
+}
+hr {
+ height: 0;
+ border: solid #696;
+ border-width: 0 0 1px 0;
+}
+ul {
+ margin: 0 2.5em;
+ padding: 0 0 0 .2em;
+}
+li {
+ margin: 0;
+ padding: 0 0 0 .5em;
+}
+pre a {
+ text-decoration: none;
+}
+
+#breadcrumbs {
+ padding: 0 0.75em;
+ margin: -.3em 0 0 -.5em;
+ font-size: smaller;
+ color: #393;
+}
+#breadcrumbs a {
+ color: #6a6;
+}
+#footer {
+ background-color: #f0f0f0;
+ border-top: 1px solid #c0c0c0;
+ color: #808080;
+ font-size: smaller;
+ padding: 0.25em 0 1em;
+ text-align: center;
+ margin: 1em -5.5% 0;
+}
Added: pieforms-php5/branches/0.2.0/doc/html/user/concepts.html
===================================================================
--- pieforms-php5/branches/0.2.0/doc/html/user/concepts.html (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/html/user/concepts.html 2007-03-18 09:05:07 UTC (rev 199)
@@ -0,0 +1,302 @@
+<?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> » <a href="../">Documentation Home</a> » <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@catalyst.net.nz">nigel@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, "heavy" 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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">></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">-></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">&</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:#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"><</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">-></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 "required" rule was violated, although generally that is quite hard to
+violate with the "date" 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->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 "text" element, which represents a simple HTML
+<tt class="docutils literal"><span class="pre"><input</span> <span class="pre">type="text"></span></tt> widget. But there is also a "date" widget, which is
+rendered as three <tt class="docutils literal"><span class="pre"><select></span></tt> widgets for year, month and day, and a
+"calendar" widget which is a full-blown popup javascript calendar! The Mahara
+project created a "wysiwyg" 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 "table" renderer which puts each element inside a table
+row, and a "div" renderer that puts them inside a <tt class="docutils literal"><span class="pre"><div></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> » <a href="../">Documentation Home</a> » <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>,
+© 2006 Catalyst IT Ltd. Pieforms is released under the <a href="http://gnu.org/licences/gpl.html">GNU GPL</a></div>
+</body>
+</html>
Added: pieforms-php5/branches/0.2.0/doc/html/user/configuration.html
===================================================================
--- pieforms-php5/branches/0.2.0/doc/html/user/configuration.html (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/html/user/configuration.html 2007-03-18 09:05:07 UTC (rev 199)
@@ -0,0 +1,198 @@
+<?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 Configuration</title>
+
+<link rel="stylesheet" type="text/css" href="../style.css" />
+</head>
+<body>
+<div class="document" id="pieforms-configuration">
+<h1 class="title">Pieforms Configuration</h1>
+<p><div id="breadcrumbs"><a href="http://pieforms.sourceforge.net/">Pieforms Home</a> » <a href="../">Documentation Home</a> » <a href="">Pieforms Configuration</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@catalyst.net.nz">nigel@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="#requirements" id="id3" name="id3">Requirements</a></li>
+<li><a class="reference" href="#installation" id="id4" name="id4">Installation</a></li>
+<li><a class="reference" href="#using-pieforms-on-a-page" id="id5" name="id5">Using Pieforms on a Page</a></li>
+<li><a class="reference" href="#configuration" id="id6" name="id6">Configuration</a><ul>
+<li><a class="reference" href="#configuring-a-default-form" id="id7" name="id7">Configuring a Default Form</a></li>
+<li><a class="reference" href="#validation-for-all-forms" id="id8" name="id8">Validation for All Forms</a></li>
+<li><a class="reference" href="#configuring-elements" id="id9" name="id9">Configuring elements</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>This document describes how to install and configure Pieforms for use in your
+application. Once you have completed the steps in this document, all of the
+features of Pieforms will be available for your use.</p>
+<div class="section">
+<h1><a class="toc-backref" href="#id3" id="requirements" name="requirements">Requirements</a></h1>
+<p>Currently, Pieforms is written for PHP5. Pieforms will not run in PHP4, however
+it is planned that PHP4 support will be added as a separate tree. That way,
+those people using PHP5 will gain the full benefits of their choice while those
+people who still insist on running PHP4 may also use Pieforms if they need.
+<a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a></p>
+<p>If you wish to use the JSForms support, you will need a couple of extra
+dependencies:</p>
+<ul class="simple">
+<li>The <tt class="docutils literal"><span class="pre">json_encode</span></tt> function, so that Pieforms can reply to JSForm requests.
+This dependency is in fact optional - Pieforms includes Services_JSON from PEAR
+which contains a pure PHP implementation. However, this is slower than t...
[truncated message content] |
