From 3ec8e3f052ff65aa3ef7cc13ea4fa64713fcec25 Mon Sep 17 00:00:00 2001
From: Dominique Fournier <dominique@fournier38.fr>
Date: Sun, 1 Jun 2014 07:37:46 +0000
Subject: [PATCH] Add forms in documentation

git-svn-id: https://svn.fournier38.fr/svn/ProgSVN/trunk@1373 bf3deb0d-5f1a-0410-827f-c0cc1f45334c
---
 docs/USAGE | 50 ++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 6 deletions(-)

diff --git a/docs/USAGE b/docs/USAGE
index a80e13f..03af293 100644
--- a/docs/USAGE
+++ b/docs/USAGE
@@ -18,13 +18,13 @@ you can add the framework directely in the base of a project if you want, or in
 a global system directory.
 
 You can start a new project. The following text will be project in
-/var/www/project. 
+/var/www/project.
 You must add a .htaccess file with :
     Options -Indexes
     <IfModule mod_rewrite.c>
       RewriteEngine on
       # if your app is in a subfolder
-      # RewriteBase /my_app/ 
+      # RewriteBase /my_app/
       # test string is a valid files
       RewriteCond %{SCRIPT_FILENAME} !-f
       # test string is a valid directory
@@ -62,7 +62,7 @@ databases directely (as it is the model part). It can provide methods to access
 to database model.
 
 The methods in the controller will be the only access from the framework.
-The controllers shouldn't write directly to stdout. They should return the 
+The controllers shouldn't write directly to stdout. They should return the
 result of their work to the caller.
 
 Example :
@@ -98,7 +98,7 @@ surcharged by using the _METHOD variable in POST method, with the wanted method
 to use.
 The routes are read sequentially. The first which match the class/method wins.
 You should carrefully order the rules.
-Add the debug on routing with 
+Add the debug on routing with
     $route->debug=TRUE;
 to help to see the matches.
 
@@ -115,10 +115,10 @@ application (see the MODULAR APPLICATION chapter)
 6. Output : the renderer
 ------------------------
 When a controller has finished his job, the result returned to the main class of
-routing to be displayed. It can be displayed in a lot of formats : HTML, csv, 
+routing to be displayed. It can be displayed in a lot of formats : HTML, csv,
 json, xml.
 The allowed extensions are puts in the routingCollection in the position you
-want by adding them between parenthesis. Example : 
+want by adding them between parenthesis. Example :
     require_once ("domframework/route.php");
     $route = new route ();
     $res = $route->routingCollection (array (
@@ -160,6 +160,44 @@ The screen will display the actions to help the debug :
     blog/5 ?? blog/{page} => blog->get({page}) : FOUND : URL === REGEX : Call blog()->get(5)
     ==== DEBUG : ROUTING END ====
 
+9. Forms
+--------
+The forms module is the easiest way to display HTML forms for users. It
+integrate the CSRF security with a hidden field, can display a notice, warning
+or error to the user.
+To use it :
+    require ("domframework/form.php");
+    $errors = array ();
+    $f = new form ();
+    // Check CSRF and get the provided values if they exists
+    $values = $f->values ();
+    // Define here the fields (can be done multiple times)
+    $field = new formfield ($name, $label);
+    // Add the parameters to the field
+    $fields[] = $field;
+    unset ($field);
+    $f->fields ($fields);
+    // Display the form
+    echo $f->printHTML ("post", $values, $errors);
+
+The fields are defined by :    
+- name       : name of the field in the HTML page
+- label      : label written to the describe the field
+- [titles]   : text written in radio/checkboxes
+- [defaults] : default values. Must be array for checkbox/select, and
+  string for others
+- [type]     : text, password, hidden, checkbox, select, radio, submit
+  text by default
+- [multiple] : Multiple selection are possible (if the type supports it)
+- [group]    : define a fieldset and define the title with groupe name
+  Warning : all the elements of the same group must be consecutive !
+- [readonly] : put a read-only flag on the field (the user see it but
+  can't interract on it. The value will be sent to next page
+- [mandatory] : boolean to add a red star at end of label
+
+The CSRF parameter is verify automatically when using $f->values ();
+In case of error, an exception is raised.
+
 XX. CLI usage
 -------------
 The DomFramework is designed to be used in console line too.