Add forms in documentation

git-svn-id: https://svn.fournier38.fr/svn/ProgSVN/trunk@1373 bf3deb0d-5f1a-0410-827f-c0cc1f45334c

docs/USAGE

@@ -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.