# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1355269606 -3600
# Node ID fdf3f273e417d0df62badfeeedf0f2105fa016e8
# Parent  bec2e385d5047b095106173e2efd4364cf298bbc
Added a draft of the help page.

diff -r bec2e385d504 -r fdf3f273e417 pages/HelpOnMoinForms
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/pages/HelpOnMoinForms	Wed Dec 12 00:46:46 2012 +0100
@@ -0,0 +1,288 @@
+##master-page:HelpTemplate
+##master-date:Unknown-Date
+#format wiki
+#language en
+
+== MoinForms ==
+
+The !MoinForms support for !MoinMoin provides a way of describing Web forms that can be embedded in Wiki pages and handled by special Wiki actions.
+
+<<TableOfContents(3)>>
+
+== Creating Forms ==
+
+To embed a form within a page, a special region must be declared as in the following example:
+
+{{{{
+{{{#!form fragment=exampleform
+
+|| '''Name'''    || <<FormField(name,ExampleFormDict)>>    ||
+|| '''Address''' || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country''' || <<FormField(country,ExampleFormDict)>> ||
+||               || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}
+}}}}
+
+This example demonstrates...
+
+ * A region providing a form
+ * Within which form fields can be inserted using the `FormField` macro
+ * Using normal Wiki syntax, meaning that normal formatting facilities can be used to present forms (with a table being used in this case)
+
+Here, four form fields are used, but their definitions are not provided in the form region itself. Instead, each of the fields references a !WikiDict providing such definition details, and this is described [[#Defining_Fields|below]].
+
+The above form definition produces the following form:
+
+{{{#!form fragment=exampleform
+
+|| '''Name'''    || <<FormField(name,ExampleFormDict)>>    ||
+|| '''Address''' || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country''' || <<FormField(country,ExampleFormDict)>> ||
+||               || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}
+
+=== Defining Form Regions ===
+
+{{{{
+{{{#!form fragment=<fragment> action=<action>
+...
+}}}
+}}}}
+
+Form regions must be defined using the special `#!form` notation and should provide a `fragment` identifier that uniquely identifies the form on the page, along with an `action` identifier indicating which action should be used to interpret and process the form data. If the `action` argument is missing, the default `MoinFormHandlerAction` is used.
+
+Normal Wiki markup can be used within form regions, but care must be taken to ensure that where other regions are embedded within form regions, the number of brackets used to declare the outer regions is greater than the number used to declare the embedded regions. This technique is described on the HelpOnParsers page, but is also illustrated below.
+
+{{{{{
+{{{{#!form fragment=exampleform action=ExampleAction
+
+Fill out the form below:
+
+{{{#!wiki important
+Be sure to fill out '''everything'''!
+}}}
+
+Name:    <<FormField(name,ExampleFormDict)>>
+Address: <<FormField(address,ExampleFormDict)>>
+Done?    <<FormField(finish,ExampleFormDict,label=Finish)>>
+}}}}
+}}}}}
+
+Note how the form declaration uses `{{{{` and `}}}}` while the [[HelpOnAdmonitions|adminition]] uses `{{{` and `}}}`.
+
+=== Using the Form Field Macro ===
+
+{{{
+<<FormField(<name>,<WikiDict>,<option>...)>>
+}}}
+
+The `FormField` macro causes a form field to appear in the page having a particular name and employing a particular form control (text field, text area, pull-down menu, button) depending on the definition of the field. The !WikiDict argument must be the name of a page providing a collection of form definitions as described [[#Defining_Fields|below]].
+
+Besides the name and !WikiDict, some other options can be employed to change the nature of the displayed control:
+
+|| '''Option''' || '''Effect''' ||
+|| `label`      || provides a label for `submit` fields (buttons) ||
+|| `section`    || indicates the kind of section to be added to a form by a selector field (having the `_add` name) ||
+
+The label specified for a `submit` field will be localised according to the user's language settings. If no label is specified, an attempt will be made to localise the field name, but it is recommended that a label always be specified and any required translations be defined in user-specified translation pages (or other appropriate resources) as described on the HelpOnLanguages page.
+
+==== Selector Fields ====
+
+Most fields will rely on a separate definition recorded on the specified !WikiDict page, but a special class of fields known as ''selector'' fields that manipulate the form structure can be included by specifying one of the special names given below:
+
+|| '''Name'''   || '''Purpose''' ||
+|| `_add`       || adds a section to the form (in conjunction with the `section` option) ||
+|| `_remove`    || removes a section from the form ||
+
+The !WikiDict information need not then be specified, but where a [[#Form_Sections|form section]] is to be added, the `section` option may need to be defined to indicate which kind of section is to be added to the form.
+
+Selector fields also employ labels which behave just as they do for `submit` fields.
+
+=== Defining Fields ===
+
+Each form definition is provided as an entry in a !WikiDict, where each entry in the dictionary corresponds to a particular field name, and where each entry describes the details of any field of that name referencing that dictionary. A !WikiDict describing form fields has the following definition list syntax:
+
+{{{
+ <field name>:: <type> <option>...
+}}}
+
+In the above example, fields reference the ExampleFormDict page, and as a result the `name` field appears as a simple text field, the `address` field as a textarea, the `country` field as a pull-down menu, and the `finish` field as a submit button. How this is achieved can be seen on the ExampleFormDict page, but a summary of the different field types and options is provided here:
+
+|| '''Type''' || '''Appearance''' || '''Options''' ||
+|| `text`     || text field       || `size`, `required` ||
+|| `textarea` || text area        || `cols`, `rows`, `required` ||
+|| `select`   || pull-down menu   || `maxselected`, `source`, `required` ||
+|| `submit`   || submit button    || ||
+
+=== Form Sections ===
+
+Some kinds of forms require collections of fields that may be optional or repeating and that may be logically grouped. Form sections permit fields to be declared within their own namespace or group such that they may be collectively added, removed or replicated. For example:
+
+{{{{{
+{{{{#!form fragment=exampleform2
+
+|| '''Name'''           || <<FormField(name,ExampleFormDict)>>    ||
+|| '''Address'''        || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country'''        || <<FormField(country,ExampleFormDict)>> ||
+{{{#!form section=activity
+|| '''Activity/hobby''' || <<FormField(activity,ExampleFormDict)>> ||
+|| '''Hours per week''' || <<FormField(duration,ExampleFormDict)>> ||
+||                      || <<FormField(_remove,label=Remove this activity)>> ||
+}}}||                   || <<FormField(_add,section=activity,label=Add activity)>> ||
+||                      || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}}
+}}}}}
+
+This produces the following form:
+
+{{{{#!form fragment=exampleform2
+
+|| '''Name'''    || <<FormField(name,ExampleFormDict)>>    ||
+|| '''Address''' || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country''' || <<FormField(country,ExampleFormDict)>> ||
+{{{#!form section=activity
+|| '''Activity/hobby''' || <<FormField(activity,ExampleFormDict)>> ||
+|| '''Hours per week''' || <<FormField(duration,ExampleFormDict)>> ||
+||               || <<FormField(_remove,label=Remove this activity)>> ||
+}}}||            || <<FormField(_add,section=activity,label=Add activity)>> ||
+||               || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}}
+
+== Handling Form Data ==
+
+!MoinForms supplies a default form handler called `MoinFormHandlerAction` that supports the manipulation of forms by selector fields and provides a framework for applications to implement their own validation logic. The basic validation logic provided by the default handler is limited to detecting and reporting the following:
+
+ * Whether required fields have been specified or not
+ * Whether the correct number of choices have been specified for a field
+
+Where validation is unsuccessful for a field, it is possible to signal such a condition using a variant of the form section intended to communicate messages to the user, with message information inserted into the page using a special `FormMessage` macro as described below.
+
+=== Form Message Sections ===
+
+Message sections are introduced in forms like normal sections but using the `message` argument in the form region's declaration. For example:
+
+{{{{{
+{{{{#!form fragment=exampleform3
+
+|| '''Name'''           || <<FormField(name,ExampleFormDict)>>    ||
+{{{#!form message=name-error
+||<-2> /!\ <<FormMessage(name-error)>>                            ||
+}}}|| '''Address'''     || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country'''        || <<FormField(country,ExampleFormDict)>> ||
+||                      || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}}
+}}}}}
+
+The form described above should look like this:
+
+{{{{#!form fragment=exampleform3
+
+|| '''Name'''           || <<FormField(name,ExampleFormDict)>>    ||
+{{{#!form message=name-error
+||<-2> /!\ <<FormMessage(name-error)>>                            ||
+}}}|| '''Address'''     || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country'''        || <<FormField(country,ExampleFormDict)>> ||
+||                      || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}}
+
+Here, a message section has been introduced below the `name` field for a field called `name-error`. When validation produces errors, it will typically store them in fields whose names are a combination of the name of the erroneous field and the suffix `-error`. So in the above example, when `name` has an error associated with it, the error will be displayed in a new table row provided by the message section and inserted into the row using the `FormMessage` macro.
+
+The errors can only be seen if the above form is submitted without a name, so you can try this out to reassure yourself that it does work as described.
+
+==== Repeating Message Sections ====
+
+Each field can potentially have many errors associated with it and stored in a separate error field. To be able to show all the errors, as opposed to only the first one, a `repeating` argument can be specified in the declaration of the message section. For example:
+
+{{{{{
+{{{{#!form fragment=exampleform4
+
+|| '''Name'''           || <<FormField(name,ExampleFormDict)>>    ||
+{{{#!form message=name-error repeating
+||<-2> /!\ <<FormMessage(name-error)>>                            ||
+}}}|| '''Address'''     || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country'''        || <<FormField(country,ExampleFormDict)>> ||
+||                      || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}}
+}}}}}
+
+The form described above should look like this:
+
+{{{{#!form fragment=exampleform4
+
+|| '''Name'''           || <<FormField(name,ExampleFormDict)>>    ||
+{{{#!form message=name-error repeating
+||<-2> /!\ <<FormMessage(name-error)>>                            ||
+}}}|| '''Address'''     || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country'''        || <<FormField(country,ExampleFormDict)>> ||
+||                      || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}}
+
+Since the default handler doesn't tend to report multiple errors, this is not particularly instructive, but [[#Extending_the_Default_Form_Handler|specialised handlers]] could associate more errors with fields and this would then be exploited above.
+
+=== Using the Form Message Macro ===
+
+{{{
+<<FormMessage(<field name>)>>
+}}}
+
+The `FormMessage` macro causes a message associated with a field to appear in the page. Although the macro is most likely to be used with error fields, it can insert the value of any field into the page.
+
+=== Extending the Default Form Handler ===
+
+Specific applications will probably need to provide more sophisticated validation and handling of forms than the default action. This is most easily done by writing an action with the following general form:
+
+{{{#!python
+from MoinForms import MoinFormHandlerAction
+
+class ExampleFormAction(MoinFormHandlerAction):
+
+    "An example form handler."
+
+    def finished(self, fields, form):
+
+        """
+        Given a valid form with the given 'fields' and the request's
+        'form' dictionary, perform additional validation.
+        """
+
+        _ = self.request.getText
+
+        # This defines the errors for the activity-error message field.
+
+        errors = []
+
+        if not fields.get("activity"):
+            errors.append(_("Need at least one activity."))
+
+        # Insist on the "finish" button being pressed and no errors.
+        # If these conditions are not met, report the errors and act
+        # as if the form is unfinished.
+
+        if errors or not fields.has_key("finish"):
+            fields["activity-error"] = errors
+            self.unfinished(fields, form)
+
+        # Upon successful validation, a special field is used to store
+        # messages and the underlying action method is called.
+
+        else:
+            fields["form-complete"] = [_("The form was correct.")]
+            MoinFormHandlerAction.finished(self, fields, form)
+
+def execute(pagename, request):
+    ExampleFormAction(pagename, request).processForm()
+}}}
+
+By overriding the `finished` method, it is possible to take advantage of the field-level validation and form manipulation supported by the default form handler whilst adding logic and preventing forms from being accepted until such additional logic considers them to be correct.
+
+Where a form is considered to be unfinished, the corresponding `unfinished` method should be invoked. Unless additional messages need to be added to the form, it is not necessary to override this method in an application-specific action.
+
+Like normal form fields, the fields populated with error messages also use collections of values instead of single values. To show all values, use repeating message sections as described above.