# HG changeset patch
# User Sylvain Thénault <sylvain.thenault@logilab.fr>
# Date 1265225684 -3600
# Node ID 83ff2bb898a528e87b63cf3e5af23059e75544f5
# Parent  7bc0e4ed4109151c333ed1d86ffcce48a4dad715
start documenting forms

diff -r 7bc0e4ed4109 -r 83ff2bb898a5 doc/book/en/development/devweb/form.rst
--- a/doc/book/en/development/devweb/form.rst	Wed Feb 03 20:33:49 2010 +0100
+++ b/doc/book/en/development/devweb/form.rst	Wed Feb 03 20:34:44 2010 +0100
@@ -1,28 +1,69 @@
 Form construction
 ------------------
+CubicWeb provides usual form/field/widget/renderer abstraction to provde
+some generic building blocks which will greatly help you in building forms
+properly integrated with |cubicweb| (coherent display, error handling, etc...)
 
-Forms
-~~~~~
-XXX feed me
-:Vocabulary control on relations:
+A form basically only hold a set of fields, and is bound to a renderer that is
+responsible to layout them. Each field is bound to a widget that will be used
+to fill in value(s) for that field.
+
+The Field class and basic fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass: cubicweb.web.formfields.Field
+
+
+Existing field types are:
 
-  * `vocabulary(rtype, x='subject', limit=None)`, called by the
-    editing views, it returns a list of couples (label, eid) of entities
-    that could be related to the entity by the relation `rtype`
-  * `subject_relation_vocabulary(rtype, limit=None)`, called internally
-    by  `vocabulary` in the case of a subject relation
-  * `object_relation_vocabulary(rtype, limit=None)`, called internally
-    by  `vocabulary` in the case of an object relation
-  * `relation_vocabulary(rtype, targettype, x, limit=None)`, called
-    internally by `subject_relation_vocabulary` and `object_relation_vocabulary`
+.. autoclass: cubicweb.web.formfields.StringField
+.. autoclass: cubicweb.web.formfields.PasswordField
+.. autoclass: cubicweb.web.formfields.RichTextField
+.. autoclass: cubicweb.web.formfields.FileField
+.. autoclass: cubicweb.web.formfields.EditableFileField
+.. autoclass: cubicweb.web.formfields.IntField
+.. autoclass: cubicweb.web.formfields.BooleanField
+.. autoclass: cubicweb.web.formfields.FloatField
+.. autoclass: cubicweb.web.formfields.DateField
+.. autoclass: cubicweb.web.formfields.DateTimeField
+.. autoclass: cubicweb.web.formfields.TimeField
+.. autoclass: cubicweb.web.formfields.RelationField
+.. XXX still necessary?
+.. autoclass: cubicweb.web.formfields.CompoundField
 
-Fields
-~~~~~~
-XXX feed me
 
 Widgets
 ~~~~~~~
-XXX feed me
+Base class for widget is :class:cubicweb.web.formwidgets.FieldWidget class.
+
+Existing widget types are:
+.. autoclass: cubicweb.web.formwidgets.HiddenInput
+.. autoclass: cubicweb.web.formwidgets.TextInput
+.. autoclass: cubicweb.web.formwidgets.PasswordInput
+.. autoclass: cubicweb.web.formwidgets.PasswordSingleInput
+.. autoclass: cubicweb.web.formwidgets.FileInput
+.. autoclass: cubicweb.web.formwidgets.ButtonInput
+.. autoclass: cubicweb.web.formwidgets.TextArea
+.. autoclass: cubicweb.web.formwidgets.FCKEditor
+.. autoclass: cubicweb.web.formwidgets.Select
+.. autoclass: cubicweb.web.formwidgets.CheckBox
+.. autoclass: cubicweb.web.formwidgets.Radio
+.. autoclass: cubicweb.web.formwidgets.DateTimePicker
+.. autoclass: cubicweb.web.formwidgets.JQueryDateTimePicker
+.. autoclass: cubicweb.web.formwidgets.JQueryDatePicker
+.. autoclass: cubicweb.web.formwidgets.JQueryTimePicker
+.. autoclass: cubicweb.web.formwidgets.AjaxWidget
+.. autoclass: cubicweb.web.formwidgets.AutoCompletionWidget
+.. autoclass: cubicweb.web.formwidgets.EditableURLWidget
+
+.. XXX StaticFileAutoCompletionWidget, RestrictedAutoCompletionWidget, AddComboBoxWidget, IntervalWidget, HorizontalLayoutWidget
+
+The following classes may also be useful: Button, SubmitButton, ResetButton,
+ImgButton, which are not proper widget (they are not associated to field) but are
+used are form controls.
+
+
+Of course you can not use any widget with any field...
 
 Renderers
 ~~~~~~~~~
diff -r 7bc0e4ed4109 -r 83ff2bb898a5 web/formfields.py
--- a/web/formfields.py	Wed Feb 03 20:33:49 2010 +0100
+++ b/web/formfields.py	Wed Feb 03 20:34:44 2010 +0100
@@ -1,4 +1,6 @@
-"""field classes for form construction
+"""Fields are used to control what's displayed in forms. It makes the link
+between something to edit and its display in the form. Actual display is handled
+by a widget associated to the field.
 
 :organization: Logilab
 :copyright: 2009-2010 LOGILAB S.A. (Paris, FRANCE), license is LGPL v2.
@@ -46,13 +48,11 @@
 _MARKER = object()
 
 class Field(object):
-    """field class is introduced to control what's displayed in forms. It makes
-    the link between something to edit and its display in the form. Actual
-    display is handled by a widget associated to the field.
+    """This class is the abstract base class for all fields. It hold a bunch
+    of attributes which may be used for fine control of the behaviour of a
+    concret field.
 
-    Attributes
-    ----------
-    all the attributes described below have sensible default value which may be
+    All the attributes described below have sensible default value which may be
     overriden by value given to field's constructor.
 
     :name: