[Pieforms-commit] SF.net SVN: pieforms: [197] pieforms-php5/branches/0.2.0/doc
Status: Alpha
Brought to you by:
oracleshinoda
Menu
▾
▴
[Pieforms-commit] SF.net SVN: pieforms: [197] pieforms-php5/branches/0.2.0/doc
|
From: <ora...@us...> - 2007-03-18 12:35:54
|
Revision: 197
http://svn.sourceforge.net/pieforms/?rev=197&view=rev
Author: oracleshinoda
Date: 2007-03-18 02:02:03 -0700 (Sun, 18 Mar 2007)
Log Message:
-----------
Added RST documentation, first cut. Not remotely complete yet.
Added Paths:
-----------
pieforms-php5/branches/0.2.0/doc/rst/
pieforms-php5/branches/0.2.0/doc/rst/index.rst
pieforms-php5/branches/0.2.0/doc/rst/user/
pieforms-php5/branches/0.2.0/doc/rst/user/concepts.rst
pieforms-php5/branches/0.2.0/doc/rst/user/configuration.rst
pieforms-php5/branches/0.2.0/doc/rst/user/elements.rst
pieforms-php5/branches/0.2.0/doc/rst/user/examples.rst
pieforms-php5/branches/0.2.0/doc/rst/user/features.rst
pieforms-php5/branches/0.2.0/doc/rst/user/usage.rst
Added: pieforms-php5/branches/0.2.0/doc/rst/index.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/index.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/index.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,83 @@
+=========================================
+ Pieforms_: Advanced web forms made easy
+=========================================
+:breadcrumbs:`Documentation Home`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+The latest copy of the Pieforms documentation may be obtained from SVN:
+
+ ``svn co https://pieforms.svn.sourceforge.net/svnroot/pieforms/pieforms-php5/trunk pieforms``
+
+.. _Pieforms: http://pieforms.sourceforge.net/
+
+.. contents::
+
+General Documentation
+=====================
+
+These files may be of interest to any Pieforms user.
+
+:README_: The project overview, requirements, and licensing details
+:COPYING_: Pieforms is licensed under the `GNU GPL`_, this file contains a full
+ copy of the license
+
+.. _README: ../../README
+.. _COPYING: ../../COPYING
+.. _GNU GPL: http://gnu.org/licenses/gpl.html
+
+.. _user:
+
+``user/``: User Documentation
+=============================
+
+These files contain documentation about how to use Pieforms. They will be of
+interest to almost any Pieforms user.
+
+* `Pieforms Concepts and Terms <user/concepts.html>`__ - basic Pieforms
+ concepts. **Read this first!**
+* `Pieforms Feature List <user/features.html>`__ - list of major Pieforms
+ features
+* `Pieforms Configuration <user/configuration.html>`__ - instructions on
+ installation and basic configuration of Pieforms
+* `Basic Usage <user/usage.html>`__ - A step by step guide to writing your
+ first Pieform
+* `Examples of Pieforms <user/examples.html>`_ - examples that show
+ Pieforms usage, and may give you good ideas
+* `Elements <user/elements.html>`__ - General information about elements
+ including a list of elements that come with Pieforms.
+* `Renderers <user/renderers.html>`__
+* `Rules <user/rules.html>`__
+* `i18n <user/i18n.html>`__
+
+``ref/``: Reference Material
+============================
+
+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.
+
+* `Pieforms frontend API documentation (in phpdoc form) <ref/api/index.html>`__
+* `Element API <ref/elements.html>`__
+* `Renderer API <ref/renderers.html>`__
+* `Rule API <ref/rules.html>`__
+* `i18n API <ref/i18n.html>`__
+
+``howto/``: Miscellaneous Articles
+==================================
+
+These files contain various documentation about the use of Pieforms in many
+situations.
+
+``dev/``: Core Development Information
+======================================
+
+These files contain information for Pieforms hackers, administrators and others
+involved with the Pieforms source.
+
+* `Pieforms Coding Standards <dev/coding.html>`__
+* `Pieforms TODO List <dev/todo.html>`__
+
+:breadcrumbs:`Documentation Home`
Added: pieforms-php5/branches/0.2.0/doc/rst/user/concepts.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/user/concepts.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/user/concepts.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,307 @@
+=============================
+ Pieforms Concepts and Terms
+=============================
+:breadcrumbs:`Documentation Home > Pieform Concepts and Terms`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+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.
+
+.. _Mahara: http://mahara.org/
+.. _sourceforge: http://pieforms.sourceforge.net/
+
+What does that all mean? That's what this document is for - to describe the
+overall concepts and ideas behind Pieforms.
+
+Background
+==========
+
+.. NOTE:: You can skip this section if you don't care for history lessons :)
+
+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 `Drupal's`_ forms API, PEAR's QuickForm_ and Moodle's `form
+API`_, which was under development at the time.
+
+.. _Drupal's: http://drupal.org/
+.. _QuickForm: http://pear.php.net/package/HTML_QuickForm
+.. _form API: http://moodle.cvs.sourceforge.net/moodle/moodle/lib/form/
+
+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.
+
+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.
+
+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' :)
+
+Concepts
+========
+
+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:
+
+* A hash containing the form definition. Basically, this is a big array
+ describing the overall form properties, and the elements in the form
+* 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)
+* 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.
+* A call to the ``pieform()`` function, passing the form definition, which
+ manages the entire form building, validating, submitting and displaying
+ process.
+
+Here is an example of a simple form
+
+.. highlight:: php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'testform',
+ 'method' => 'post',
+ 'action' => '',
+ 'elements' = array(
+ 'details' => array(
+ 'type' => 'fieldset',
+ 'legend' => 'Your Details',
+ 'elements' => array(
+ 'fullname' => array(
+ 'type' => 'text',
+ 'title' => 'Full name',
+ 'description' => 'Please enter your full name',
+ 'rules' => array(
+ 'required' => true
+ )
+ ),
+ 'dob' => array(
+ 'type' => 'date',
+ 'title' => 'Date of Birth',
+ 'description' => 'Your date of birth',
+ 'defaultvalue' => strtotime('1st of January, 1985'),
+ 'rules' => array(
+ 'required' => true
+ )
+ )
+ )
+ ),
+
+ 'submit' => array(
+ 'type' => 'submit',
+ 'value' => 'Submit'
+ )
+ )
+ );
+
+ function testform_validate(Pieform $form, $values) {
+ if (!$form->get_error('dob') && $values['dob'] < strtotime('1st of January, 1950')) {
+ $form->set_error('dob', 'I will give you another chance to lie about your age, OK? :)');
+ }
+ }
+
+ function testform_submit(Pieform $form, $values) {
+ print_r($values);
+ exit;
+ }
+
+Here is a description of each part.
+
+The form definition hash
+************************
+
+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.
+
+More information about the form array is available on a `separate page`_.
+
+.. _separate page: usage.html
+
+The ``pieform(...)`` function call
+**********************************
+
+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 ``echo``'d to the browser, but it could easily be put into a `Smarty
+<http://smarty.php.net/>`__ template variable or manipulated any way required.
+
+The ``testform_validate`` function
+**********************************
+
+This function is named after the form name, with ``_validate`` 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
+``$form`` 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.
+
+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.
+
+The ``testform_submit`` function
+********************************
+
+This function is named after the form name, with ``_submit`` 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:
+
+* 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
+* Reply with ``$form->json_reply(PIEFORM_OK, 'optional message')`` if the form
+ is a JS form
+
+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:
+
+.. highlight:: php
+
+ function redirect($location) {
+ header('HTTP/1.1 303 See Other');
+ header('Location: ' . $location);
+ exit;
+ }
+
+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.
+
+Form API Terms
+==============
+
+Pieforms has several components, a basic description of each is given here.
+
+Elements
+********
+
+Pieform **elements** 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.
+
+For example, there is a "text" element, which represents a simple HTML
+``<input type="text">`` widget. But there is also a "date" widget, which is
+rendered as three ``<select>`` 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.
+
+It's really easy to write your own elements, and they can be reused on any form
+that needs them. `More information about elements <elements.html>`__, including
+how to write your own, is available.
+
+Rules
+*****
+
+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 *required*, *minlength* and *maxlength* etc., but again like elements
+they are pluggable, so many more can be written.
+
+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.
+
+More information on the `rule API and writing your own rules <rules.html>`__ is
+available.
+
+Renderers
+*********
+
+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 ``<div>``. Like elements and
+rules, these are pluggable to suit your needs.
+
+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.
+
+If all that was confusing, check out the `renderers <renderers.html>`__ page
+for more information.
+
+How They Fit Together
+=====================
+
+Here are some statements that might help you understand how a form is put
+together using Pieforms.
+
+A **form** is made up of `elements <elements.html>`__.
+
+**Elements** are like standard HTML widgets, except they can be more
+complicated and comprised of many widgets if necessary.
+
+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 forms are **submitted**, they are **validated** using the **rules** for
+each **element**. If validation passes, the form **submit callback** is called
+with the values. If validation fails, the form is redisplayed, with the
+**renderer** drawing the error messages as returned by the **rule** for each
+**element** next to it.
+
+Other Features of Pieforms
+==========================
+
+As well as customisable elements, renderers and rules, Pieforms has the
+following features:
+
+* Forms can be sent via GET or POST
+* Forms can be sent to different pages, as long as the form definition is
+ 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
+ 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
+ responsively
+* Automatic handling of **tabindex** for each element
+* **HTML 4.01 compliance** (XHTML compliance will be added `later
+ <../dev/todo.html#xhtml>`__)
+
+:breadcrumbs:`Documentation Home > Pieform Concepts and Terms`
Added: pieforms-php5/branches/0.2.0/doc/rst/user/configuration.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/user/configuration.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/user/configuration.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,181 @@
+========================
+ Pieforms Configuration
+========================
+:breadcrumbs:`Documentation Home > Pieforms Configuration`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+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.
+
+Requirements
+============
+
+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.
+[#]_
+
+If you wish to use the JSForms support, you will need a couple of extra
+dependencies:
+
+* The ``json_encode`` 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 the
+ native JSON extension for PHP, so if you have that extension it is a bonus. PHP
+ 5 >= 5.2 contains the JSON extension built in, so you do not need to worry if
+ you are using a version above that.
+* The ``Base``, ``Iter``, ``Style``, ``DOM`` and ``Async`` modules of `MochiKit
+ <http://mochikit.com/>`__, greater than version 1.3.1. A packed version of
+ MochiKit containing just these modules is available for your convenience in the
+ ``static/core/MochiKit`` directory, however you can use your own MochiKit if
+ you require other modules.
+
+Installation
+============
+
+To install Pieforms:
+
+1. Copy the ``pieform.php`` file and the ``pieform`` diretory (contained in the
+ ``src`` directory of the standard Pieforms distribution) to somewhere in your
+ application's directory structure. Also copy the ``JSON`` directory to the same
+ place if you do not have the JSON extension for PHP available and want to use
+ the JS form submission support.
+2. If you wish to use the more advanced javascript widgets (such as the
+ calendar), or the JS form submission support, copy the ``static`` directory
+ contents to some place where your application can link to the appropriate
+ javascript files.
+
+And you're done!
+
+Using Pieforms on a Page
+========================
+
+On any page in your application where a Pieform is to be made:
+
+* Make sure that the MochiKit javascript file is sourced by a <script> tag in
+ the output of the page, if you are using JS forms, autofocus, or any other
+ javascript effect.
+* Also make sure that ``pieforms.js`` is included (which is located in
+ ``static/core/``), if you are using javascript effects.
+* Include the ``pieform.php`` file.
+* You will need to call ``pieform_get_headdata()`` somewhere. This will return
+ an array of ``<script>`` tags, ``<link>`` tags and other things that need to go
+ in the ``<head>`` of your document somewhere.
+
+As long as you have followed all of those steps, all features of Pieforms
+should be available.
+
+Configuration
+=============
+
+Pieforms provides a way for you to configure how a "default" form should be set
+up, as well as the "default" configuration for each element. You can also write
+a function that is called by all forms for validation, which is useful if you
+always have an element in all of your forms.
+
+If none of the next section makes too much sense, don't worry too much.
+Instead, skip on to the `step by step guide <usage.html>`__ to creating
+Pieforms, and read that. After having read that, you will quickly see the
+benefits of the configuration functions provided below.
+
+Configuring a Default Form
+**************************
+
+To configure a default form, you should write a ``pieform_configure()``
+function. This function should return what looks like the definition of a
+Pieform, that will be used as the default for all forms. You could use this to,
+for example, turn 'autofocus' on for all forms by default. Here is an example:
+
+.. highlight:: php/php5
+
+ function pieform_configure() {
+ // This is just a variable specific to your application,
+ // for example purposes.
+ global $LIBDIR;
+
+ return array(
+ // Make all forms by default POST. The default for Pieforms,
+ // as for normal HTML forms, is GET.
+ 'method' => 'post',
+
+ // Autofocus the first field of the form on page load, or the
+ // first field with an error if there is an error. If there is
+ // more than one form on a page, only the first is focused.
+ 'autofocus' => true,
+
+ // Add the element type to the list of classes for each element.
+ // For example, the 'text' element will get a class of 'text'. Useful
+ // for styling forms when you have to support broken IE6.
+ 'elementclasses' => true,
+
+ // Look in this directory as well as the default for plugins. So you
+ // can keep your elements/renderers/rules separate from the Pieforms
+ // ones.
+ 'configdirs' => $LIBDIR . 'form/',
+
+ // You can add elements that will be in all forms. Here's the prime
+ // example of why you would want to...
+ 'elements' => array(
+ // Using a session key for forms prevents CSRF (check google or
+ // wikipedia for an explanation). Without this, you may as well
+ // invite hackers in to play with your users.
+ 'sesskey' => array(
+ 'type' => 'hidden',
+ // This function specific to your application
+ 'value' => get_sesskey()
+ )
+ )
+ );
+ }
+
+Validation for All Forms
+************************
+
+Of course, with the session key in the previous section as a good example, it
+would get boring pretty quickly if you had to add validation to it to all
+forms. Pieforms allows you to define the ``pieform_validate`` function that
+will be called whenever any form is validated to do any validation that should
+be done for all forms.
+
+.. highlight:: php/php5
+
+ function pieform_validate(Pieform $form, $values) {
+ if (!isset($values['sesskey'])) {
+ throw new Exception('No session key');
+ }
+ $sesskey = get_sesskey();
+ if ($sesskey && $sesskey != $values['sesskey']) {
+ throw new Exception('Invalid session key');
+ }
+ }
+
+Configuring elements
+********************
+
+Some elements (such as the ``calendar``), take configuration parameters that
+you may not want to specify everywhere that they are used. To prevent
+duplication, you can specify a function for each element to configure it.
+
+.. highlight:: php/php5
+
+ function pieform_element_calendar_configure($element) {
+ $element['jsroot'] = '/js/jscalendar/';
+ $element['themefile'] = '/style/calendar.css';
+ $element['imagefile'] = '/img/calendar.gif';
+ $element['language'] = 'en';
+ return $element;
+ }
+
+See the documentation of each element for more information about what you can
+configure them to do.
+
+.. [#] The author works with and has authored many PHP4 projects in his time, thus eventually Pieforms **will** be ported for some of these projects (or for a new project if PHP4 is a requirement). Once you've used Pieforms you won't want to use anything else :)
+
+:breadcrumbs:`Documentation Home > Pieforms Configuration`
Added: pieforms-php5/branches/0.2.0/doc/rst/user/elements.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/user/elements.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/user/elements.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,113 @@
+===================
+ Pieforms Elements
+===================
+:breadcrumbs:`Documentation Home > Pieforms Elements`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+This document describes how elements fit into the Pieforms architecture, how you use them, and how you can write your own to suit your needs.
+
+Overview
+========
+
+As you may be aware by now, if you have used Pieforms for a little while or have read the documentation that comes before this, Pieform elements represent distinct part of a form. It takes one or more elements to make up a form, but normally at least two - any elements the form has plus some kind of "submit" element. For example, a form may have three elements - a text box, a select dropdown, and a submit button.
+
+The important thing to remember is that Pieform elements do not necessarily correspond to the standard HTML form widgets. In fact, they are a lot more powerful. While it is almost guaranteed that elements will contain at least one HTML widget, in reality they can contain almost anything you want. For the Mahara project, elements were written that:
+
+* Made AJAX requests to populate select dropdowns
+* Used smarty templating to lay themselves out
+* Displayed a calendar for picking a date
+* Allowed users to maintain a list of e-mail addresses, and pick a "primary" address
+
+Once you understand how elements work, it will be easy for you to write your own. All you need to make sure of is that each element deals with one separate task. A good rule of thumb is to make elements that can return one value or one array of values, though in some cases you may relax this rule (for example, the email list element described above returns both a list of e-mail addresses and which one is the primary address).
+
+Using Elements
+==============
+
+To use an element in your form, you name it when declaring the type of one of your form elements.
+
+.. highlight:: php/php5
+
+ <?php
+
+ $form = array(
+ 'name' => 'myform',
+ 'elements' => array(
+ 'myelement' => array(
+ // Choose the type of the element here
+ 'type' => 'text',
+ // Any other configuration for the element goes here...
+ )
+ )
+ );
+
+ ?>
+
+In the above example, the element has been declared as having a type of 'text'. The text element is for a standard HTML text input. You put any other configuration for the element in there as well. For example, you can declare the default value for the element using ``defaultvalue`` or its size using ``size``. The list varies per element, but the major ones are listed here.
+
+Common Configuration Items for Elements
+---------------------------------------
+
+.. NOTE:: These items are supported by most of the standard elements, although their behaviour may vary between elements
+
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Item | Description |
++==================+========================================================================================================================================================================================================+
+| ``defaultvalue`` | What value the element should have by default |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``value`` | The value the element should have *regardless of what the user submits* |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``accesskey`` | What value to use for the ``accesskey`` attribute of the element |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``class`` | What value to use for the ``class`` attribute of the element |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``dir`` | What value to use for the ``dir`` attribute of the element |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``lang`` | What value to use for the ``lang`` attribute of the element |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``onclick`` | What value to use for the ``onclick`` attribute of the element. Note that it is preferred that you use MochiKit's event handling library if you can. |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``style`` | What value to use for the ``style`` attribute of the element |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``name`` | You can name your elements using the ``name`` item, but the name for the element is usually sourced by the array key it was declared with. |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``id`` | What to use as an ID for the element. Pieforms gives all your elements IDs, so you generally should not set one this way. |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``size`` | What to use for the "size" of an element. The meaning varies from element to element, but generally means what the ``size`` attribute means for the element in HTML. |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``tabindex`` | What to use for the tabindex of an element. Pieforms manages tabindex automatically, and you can set the tabindex for every element in the form elsewhere, so generally there is no need to set this. |
++------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Supported Elements
+------------------
+
+The elements that you can use will depend on several things, such as what version of Pieforms you have, what elements you have written or downloaded, and what you have set the search path for plugins as. Here is a list of Pieform elements that come with Pieforms.
+
+* button
+* bytes
+* calendar
+* cancel
+* checkbox
+* date
+* expiry
+* fieldset
+* file
+* hidden
+* html
+* image
+* password
+* radio
+* select
+* submitcancel
+* submit
+* textarea
+* text
+
+.. TODO:: Link to docs for the elements, generate the list programatically
+
+Most of these elements correspond to basic HTML elements
+:breadcrumbs:`Documentation Home > Pieforms Elements`
Added: pieforms-php5/branches/0.2.0/doc/rst/user/examples.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/user/examples.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/user/examples.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,16 @@
+===================
+ Pieforms Examples
+===================
+:breadcrumbs:`Documentation Home > Pieforms Examples`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+There is no examples yet, but they will be coming soon! Check the `concepts
+<concepts.html>`__ page for a simple example, and you could also `download
+Mahara <http://mahara.org/>`__ and see the many forms written for it.
+
+:breadcrumbs:`Documentation Home > Pieforms Examples`
Added: pieforms-php5/branches/0.2.0/doc/rst/user/features.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/user/features.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/user/features.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,96 @@
+===================
+ Pieforms Features
+===================
+:breadcrumbs:`Documentation Home > Pieforms Features`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+This document outlines the major features that Pieforms has, with a brief
+description of each one and links to more information for them.
+
+Simple To Use API
+=================
+
+For the vast majority of cases, all you ever see of the Pieforms API is the
+``pieform($form)`` function call. Most of the work is specific to your
+application - the definition of the form, and the function to handle successful
+submission. This means you can concentrate your efforts on the important parts
+- how your form is defined, and what to do when the user submits it properly.
+
+Practically, this means that:
+
+* Prototyping is really easy - if you need to prototype a page, it won't take
+ you very long to hack up a display-only form
+* The submit function can follow the so-called "happy path" - because you know
+ that all the data is validated, your function can concern itself entirely with
+ the job of writing information to the database, sending e-mail, logging a user
+ in, or anything else you need.
+
+The form definition itself is intuitive, making it really easy to add, remove
+and re-order the elements in your form in about a minute of work - which is how
+long it **should** take. And with all the available elements, renderers and
+rules pre-made for your convenience, form building will often just be a case of
+selecting the parts you require.
+
+And if you find you need something that isn't available, the APIs for making
+new plugins are simple and consistent, making this job easy as well. Combined
+with `MochiKit <http://mochikit.com/>`__ on the client side, you will find
+making new plugins dead easy!
+
+Pluggable and Extensable
+========================
+
+Each of the three main components to a Pieform - elements, renderers and rules
+- are pluggable. This means if Pieforms doesn't provide something you require,
+you can just write it yourself. Pieforms provides a method for you to list
+directories where plugins are located, meaning you can keep your creations
+separate from the core Pieforms plugins if you like. And if you think your
+plugin is neat and could be used by others, you could submit it to Pieforms as
+a `feature request
+<http://sourceforge.net/tracker/?group_id=182497&atid=901456>`__, and it could
+be included in the next release for everyone to enjoy.
+
+Asynchronous Forms
+==================
+
+By simply flipping a switch, you can turn your forms from being standard
+``POST`` forms into snappy, responsive "Javascript Forms" (or JSForms as
+Pieforms knows them). Rather than doing a full ``POST`` every time the form is
+submitted, the form data is submitted to a hidden iframe, and the result
+returned as JSON. This makes the form "feel" much faster and responsive,
+especially when the validation may be complex and the user may have to have
+several goes at submitting a form before they get it right.
+
+This also frees your page to perform actions using javascript during and after
+the form submission. For example, you could place a spinner on the page
+somewhere or disable the submit button and replace the text with 'processing
+form...' when the form is submitted, and then display a message when the form
+is successfully submitted.
+
+Full Internationalisation (i18n)
+================================
+
+Though there is not a lot to translate, Pieforms has i18n support, so the rule
+messages can be in your native language if you need. Elements also support i18n
+where required - for example, the calendar element supports different
+languages. Although the only supported language at the moment is "en.utf8", it
+will take only around 10 minutes to add new languages. Ask on the mailing list
+or in the forums!
+
+HTML 4.01 Compliance
+====================
+
+Pieforms generates HTML 4.01 compatible output. It does not support XHTML at
+the moment, but the author reckons this will only take an hour of work, if you
+ask nicely :).
+
+Pieforms uses the ``tabindex`` attribute for form elements, meaning that
+keyboard users are not forgotten. Pieforms also supports auto-focusing the
+first field of a form on page load, and auto-focusing the first field with an
+error on it if there is one.
+
+:breadcrumbs:`Documentation Home > Pieforms Features`
Added: pieforms-php5/branches/0.2.0/doc/rst/user/usage.rst
===================================================================
--- pieforms-php5/branches/0.2.0/doc/rst/user/usage.rst (rev 0)
+++ pieforms-php5/branches/0.2.0/doc/rst/user/usage.rst 2007-03-18 09:02:03 UTC (rev 197)
@@ -0,0 +1,526 @@
+================
+ Pieforms Usage
+================
+:breadcrumbs:`Documentation Home > Pieforms Usage`
+
+:Author: Nigel McNie
+:Contact: ni...@ca...
+:Copyright: This document has been placed in the public domain
+
+.. contents::
+
+This document takes you through the creation of a Pieform, step by step. After
+reading this document, you should be able to put together all manner of
+Pieforms, and you will be ready to begin learning how to create your own
+plugins for your own needs.
+
+Before You Begin...
+===================
+
+Make sure that you have `read the concepts document <concepts.html>`__, so that
+you understand the basic ideas behind how Pieforms works. Also make sure you
+have `installed <configuration.html>`__ Pieforms, of course!
+
+Your First Pieform
+==================
+
+For the sake of argument, let us assume that you are writing a blogging application, and that your current task is to write a form into which new posts will be entered. This form will consist of:
+
+* A text box, for the subject
+* A textarea, for the post content
+* A multiple-select dropdown, for choosing categories for the post
+* A date field for choosing the date on which the post will become viewable, defaulting to the current date
+* A submit and cancel button
+
+Also, for the sake of argument, let us assume that the category selection and date fields are optional and not really used that much, so we will place them in a fieldset and collapse it by default, to make the form seem simpler for general use.
+
+So, given these requirements, let's get started!
+
+The Basics
+----------
+
+We shall start with the basic page shell, and build the pieces as required. Here is the most basic shell:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array());
+
+ ?>
+
+And here is the output you get when running this:
+
+[insert screenshot here of boom]
+
+Whoops! Pieforms forms **must** have a name. This name is used on the client side to identify the form, and on the server side to provide unique names for the validation/submission callbacks. More on those later, but for now let's add some of the most basic parameters required:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post'
+ ));
+
+ ?>
+
+[insert screenshot of boom]
+
+So now the form has a name, and will be sent by POST when submitted. But it has no elements! There's not too much point in having a form that does not have an element, so lets add the title field and submit/cancel buttons.
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'elements' => array(
+ 'title' => array(
+ 'type' => 'text',
+ 'title' => 'Post Title'
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ )
+ )
+ ));
+
+ ?>
+
+[insert screenshot of yay]
+
+Now we have some concrete progress, at last! We now have a single text box, with a submit and cancel button under it. Compare how much effort it took to add these elements with how you would normally make forms. I hope you are already seeing how quick this is!
+
+Now let's try submitting the form:
+
+[insert screenshot of boom]
+
+We have not specified the function that gets run when the form is submitted. This function has the name ``[formname]_submit``, and once it is done it should somehow redirect the user to another page (or redirect back to the same page if you wish, but it must be a redirect so that the form state is cleared), or exit the script. For now we will just show a success page:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'elements' => array(
+ 'title' => array(
+ 'type' => 'text',
+ 'title' => 'Post Title'
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ )
+ )
+ ));
+
+ function blogpost_submit(Pieform $form, $values) {
+ echo <<<EOF
+ <p>Congratulations! New post entered. <a href="">Back to enter another one</a>...</p>
+ EOF;
+ exit;
+ }
+
+ ?>
+
+Please pardon my terrible HTML, this is only an example :). Now, when you submit the form:
+
+[screenshot of success]
+
+That's much better. Of course, the submit function should have inserted the blog post into the database before displaying this message, but I'll leave that detail as an exercise for the reader.
+
+But what about the cancel button?
+
+[screenshot of cancel boom]
+
+Not so great, luckily Pieforms tells you what you need to do to fix that. While we're at it, let's add the textarea for the post content:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'elements' => array(
+ 'title' => array(
+ 'type' => 'text',
+ 'title' => 'Post Title'
+ ),
+ 'content' => array(
+ 'type' => 'textarea',
+ 'title' => 'Content'
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ 'goto' => $_SERVER['SCRIPT_NAME']
+ )
+ )
+ ));
+
+ function blogpost_submit(Pieform $form, $values) {
+ echo <<<EOF
+ <p>Congratulations! New post entered. <a href="">Back to enter another one</a>...</p>
+ EOF;
+ exit;
+ }
+
+ ?>
+
+[insert screenshot of form]
+
+You will get the result above both when you view and cancel the form. Of course, your cancel button could redirect elsewhere, or put a message in the session that is displayed on the next page, using the cancel function ``[formname]_cancel_submit`` rather than ``'goto'`` on the element.
+
+So now all that remains is the category multiple select and the date for when the post will be published. These should be in a fieldset:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'elements' => array(
+ 'title' => array(
+ 'type' => 'text',
+ 'title' => 'Post Title'
+ ),
+ 'content' => array(
+ 'type' => 'textarea',
+ 'title' => 'Content'
+ ),
+ 'optional' => array(
+ 'type' => 'fieldset',
+ 'title' => 'Advanced Options...',
+ 'collapsable' => true,
+ 'collapsed' => true,
+ 'elements' => array(
+ 'categories' => array(
+ 'type' => 'select',
+ 'title' => 'Categories',
+ 'multiple' => true,
+ 'size' => 5,
+ 'values' => array(
+ 1 => 'Personal',
+ 2 => 'Rants',
+ 3 => 'Politics',
+ 4 => 'Religion',
+ 5 => 'Science',
+ 6 => 'Arts'
+ )
+ ),
+ 'publishdate' => array(
+ 'type' => 'date',
+ 'title' => 'Publish Date'
+ )
+ )
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ 'goto' => $_SERVER['SCRIPT_NAME']
+ )
+ )
+ ));
+
+ function blogpost_submit(Pieform $form, $values) {
+ echo <<<EOF
+ <p>Congratulations! New post entered. <a href="">Back to enter another one</a>...</p>
+ EOF;
+ exit;
+ }
+
+ ?>
+
+[insert screenshot]
+
+Adding a Touch of Class
+-----------------------
+
+Now the whole form is layed out, including the collapsable fieldset. Cool! But we are not finished yet. The form has no rules attached to it (other than a hidden rule on the multiselect box to automatically check that the submitted value is in the array of values), and could be improved with a bit of javascript love. On the rule side, let's make the title and content of the post required and the publish date be later than the current time. For javascript improvement, we can make the textarea resizable and auto focus the title element on page load.
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'blogpost',
+ 'method' => 'post',
+ 'autofocus' => true,
+ 'elements' => array(
+ 'title' => array(
+ 'type' => 'text',
+ 'title' => 'Post Title',
+ 'rules' => array('required' => true)
+ ),
+ 'content' => array(
+ 'type' => 'textarea',
+ 'title' => 'Content',
+ 'rules' => array('required' => true),
+ 'resizable' => true
+ ),
+ 'optional' => array(
+ 'type' => 'fieldset',
+ 'title' => 'Advanced Options...',
+ 'collapsable' => true,
+ 'collapsed' => true,
+ 'elements' => array(
+ 'categories' => array(
+ 'type' => 'select',
+ 'title' => 'Categories',
+ 'multiple' => true,
+ 'size' => 5,
+ 'values' => array(
+ 1 => 'Personal',
+ 2 => 'Rants',
+ 3 => 'Politics',
+ 4 => 'Religion',
+ 5 => 'Science',
+ 6 => 'Arts'
+ )
+ ),
+ 'publishdate' => array(
+ 'type' => 'date',
+ 'title' => 'Publish Date'
+ )
+ )
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ 'goto' => $_SERVER['SCRIPT_NAME']
+ )
+ )
+ ));
+
+ function blogpost_validate(Pieform $form, $values) {
+ if ($values['publishdate'] && $values['publishdate'] < time()) {
+ $form->set_error('publishdate', 'Sorry, your publish date must be in the future');
+ }
+ }
+
+ function blogpost_submit(Pieform $form, $values) {
+ echo <<<EOF
+ <p>Congratulations! New post entered. <a href="">Back to enter another one</a>...</p>
+ EOF;
+ exit;
+ }
+
+ ?>
+
+Not too much added, and pretty much everything we wanted is implemented. The title and content are now required - try submitting the form without them set. There's no easy rule for checking that a value is greater than another just yet, so we added a 'validate' function which sets an error on the form if the publish date is not in the future. It took one line to make the textarea resizable, and just one more to make the title element focus on page load. Note that we specified 'autofocus' to be **true** - this means that the first element in the form will be focussed on page load. You can specify an element by name if you want that particular element to be focussed on page load.
+
+The Finishing Touches
+---------------------
+
+Programatically, the form is done (except for any actualy logic to save the data somewhere). Now all you need it a bit of CSS magic, and you're done!
+
+[insert CSS code here]
+
+[insert screenshot here]
+
+From zero to form in very short order - when you get good at writing forms and Pieforms is already integrated into your software, the above form will be very quick indeed to create.
+
+Now let's move on to another form, this time one that will have a bit more of an 'AJAX feel'.
+
+A Form With Wings
+=================
+
+Happy with the form you made in the previous section, you now move on to your next task - a settings page for the admin section of your blog software. The form is for managing some global information about file uploads. As you will see, a little bit of Pieforms magic makes this form trivial to write.
+
+Overview
+--------
+
+The form will have the following fields for an administrator to fill out:
+
+* A global toggle, for whether file uploading is enabled or disabled
+* A text field, in which the user can put the path to the ``file`` binary, used for checking the file type of uploaded files
+* An element for inputting the quota that each user is allowed
+
+Let's get started with the boilerplate:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'filesettings',
+ 'method' => 'post',
+ 'elements' => array(
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ )
+ )
+ ));
+
+ function filesettings_submit(Pieform $form, $values) {
+ echo '<pre>';
+ print_r($values);
+ echo '</pre>';
+ echo '<a href="">Back to try again</a>';
+ exit;
+ }
+
+ ?>
+
+Now to add the elements:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'filesettings',
+ 'method' => 'post',
+ 'elements' => array(
+ 'enabled' => array(
+ 'type' => 'checkbox',
+ 'title' => 'File Uploading Enabled?',
+ 'defaultvalue' => true
+ ),
+ 'pathtofile' => array(
+ 'type' => 'text',
+ 'title' => 'Path to the "file" command',
+ 'defaultvalue' => '/usr/bin/file'
+ ),
+ 'quota' => array(
+ 'type' => 'bytes',
+ 'title' => 'User Quota',
+ 'defaultvalue' => 10 * 1024 * 1024
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ )
+ )
+ ));
+
+ function filesettings_submit(Pieform $form, $values) {
+ echo '<pre>';
+ print_r($values);
+ echo '</pre>';
+ echo '<a href="">Back to try again</a>';
+ exit;
+ }
+
+ ?>
+
+Nothing too dramatic there... but what about that 'bytes' element?
+
+The 'bytes' element is the first example of how **elements do not have to correspond to HTML form widgets**. In fact, the 'bytes' element is made up of both a (short) text box and a select dropdown. Users can input the quota in either bytes, kilobytes or megabytes using this element, depending on what suits them.
+
+This form was not hard to make, given the previous example, but it does seem like such a waste to have to do a whole round trip to the server to save the values each time. Lets make this form a 'jsform', for speed.
+
+Making a Form Work Quickly
+--------------------------
+
+Making the form submit via a hidden iframe takes one more line of code in the form definition, and a small change to the submit function:
+
+.. highlight:: php/php5
+
+ <?php
+
+ require_once('pieform.php');
+
+ echo pieform(array(
+ 'name' => 'filesettings',
+ 'method' => 'post',
+ 'jsform' => true,
+ 'elements' => array(
+ 'enabled' => array(
+ 'type' => 'checkbox',
+ 'title' => 'File Uploading Enabled?',
+ 'defaultvalue' => true
+ ),
+ 'pathtofile' => array(
+ 'type' => 'text',
+ 'title' => 'Path to the "file" command',
+ 'defaultvalue' => '/usr/bin/file'
+ ),
+ 'quota' => array(
+ 'type' => 'bytes',
+ 'title' => 'User Quota',
+ 'defaultvalue' => 10 * 1024 * 1024
+ ),
+ 'submit' => array(
+ 'type' => 'submitcancel',
+ 'value' => array('Enter New Post', 'Cancel')
+ )
+ )
+ ));
+
+ function filesettings_submit(Pieform $form, $values) {
+ if ($form->get_property('jsform')) {
+ $form->json_reply(PIEFORM_OK, 'Form saved successfully');
+ }
+ echo '<pre>';
+ print_r($values);
+ echo '</pre>';
+ echo '<a href="">Back to try again</a>';
+ exit;
+ }
+
+ ?>
+
+Give it a try. What works, and what doesn't?
+
+All that was added was the one line, ``'jsform' => true`` in the form definition, and the one if statement in the submit function. But behind the scenes, the whole submission process of the form as changed. Now, when you click the submit button, the following things happen:
+
+* A hidden <iframe> is created
+* The form target is changed so that the form submits to the newly created <iframe>
+* A javascript function is created that will handle the reply, when it arrives
+* The form is submitted
+* The reply that comes back to the <iframe> calls the function registered to handle the reply
+
+You send a reply to a jsform using the ``$form->json_reply`` method. Pretty much all of the time, the first parameter will be ``PIEFORM_OK``. The second parameter contains data that you can send back to the application.
+
+Speaking of that data - why did you not see a happy success message like you were expecting? Well, Pieforms may be pretty smart, but it's not the next Einstein. You haven't told it *how* to deal with this data. You need to add one more line to the form definition, and write a javascript function:
+
+[insert example here]
+
+And this is the result, when you submit the form:
+
+[insert screenshot here]
+
+Excellent! There's only one little issue now. Because you're a great believer in not using tables where not required, you want to change how the form is layed out. All you need to do is add one line to change the renderer:
+
+[insert example here]
+
+[insert screenshot here]
+
+Pieforms comes with a few renderers by default, they're in the ``pieform/renderers`` directory. Try them all, and see how the layout of your form changes.
+
+Conclusion
+==========
+
+As you can see, Pi...
[truncated message content] |
