[Pieforms-commit] SF.net SVN: pieforms: [233] pieforms-php5/trunk/doc/rst/user/concepts.rst

[<ora...@us...>]

Revision: 233
          http://pieforms.svn.sourceforge.net/pieforms/?rev=233&view=rev
Author:   oracleshinoda
Date:     2007-12-27 15:26:59 -0800 (Thu, 27 Dec 2007)

Log Message:
-----------
Updated to talk about templates, fixed a few mistakes.

Modified Paths:
--------------
    pieforms-php5/trunk/doc/rst/user/concepts.rst

Modified: pieforms-php5/trunk/doc/rst/user/concepts.rst
===================================================================
--- pieforms-php5/trunk/doc/rst/user/concepts.rst	2007-12-27 23:25:23 UTC (rev 232)
+++ pieforms-php5/trunk/doc/rst/user/concepts.rst	2007-12-27 23:26:59 UTC (rev 233)
@@ -11,8 +11,7 @@
 
 Pieforms is a development of the Mahara_ project, that was later split out into
 its own project on sourceforge_. 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.
+and process forms, with an emphasis on flexibility and extensibility.
 
 .. _Mahara: http://mahara.org/
 .. _sourceforge: http://pieforms.sourceforge.net/
@@ -58,8 +57,10 @@
 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' :)
+IRC was 'pie' [#]_
 
+.. [#] Said co-worker has since returned to Catalyst IT :)
+
 Concepts
 ========
 
@@ -142,13 +143,12 @@
 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.
+a list of elements that are on the form. Every form must have a name, used to
+distinguish it from other forms so Pieforms can tell when the form itself has
+been submitted.
 
-More information about the form array is available on a `separate page`_.
+More information about the form array is available on a `separate page <usage.html>`__.
 
-.. _separate page: usage.html
-
 The ``pieform(...)`` function call
 **********************************
 
@@ -262,6 +262,23 @@
 If all that was confusing, check out the `renderers <renderers.html>`__ page
 for more information.
 
+Templates
+*********
+
+If renderers don't provide the flexibility you require when laying out a form,
+you can instead write a template for it. These are simply PHP/HTML template
+files, in which you can output the form in any layout you choose.
+
+You might find that one or two renderers satisfy most of your form needs, and
+that you write templates for the few forms in your application that you can't
+lay out nicely using a renderer.
+
+Combined with the limitless customisability of elements, this grants you the
+holy grail - a consistent framework for form building that gives you **complete
+control** over how your forms look.
+
+Check out the `template documentation <templates.html>`__ for more information.
+
 How They Fit Together
 =====================
 
@@ -275,8 +292,8 @@
 
 Elements are validated by `rules <rules.html>`__.
 
-Each element in a form is rendered inside some boilerplate HTML provided by a
-`renderer <renderers.html>`__.
+When using a renderer, each element in a form is rendered inside some
+boilerplate HTML provided by a `renderer <renderers.html>`__.
 
 When forms are **submitted**, they are **validated** using the **rules** for
 each **element**. If validation passes, the form **submit callback** is called
@@ -295,7 +312,7 @@
   available on both pages
 * Support for **cancel buttons** - in effect, submit buttons with  no
   validation applied to them
-* **Auto focus** of fields in a form on page load, including focussing the
+* **Auto focus** of fields in a form on page load, including focusing the
   first element with an error if the form has failed validation
 * `JS forms <usage.html#jsform>`__ - forms submitted to a hidden iframe
   with the result returned asynchronously, meaning the form behaves very


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.