---+ Package =TWiki::Form=

Object representing a single form definition.


%TOC%

---++ ClassMethod *new* <tt>($session,$web,$form)</tt>

   * $web - default web to recover form from, if $form doesn't specify a web
   * =$form= - topic name to read form definition from

May throw TWiki::OopsException



---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta,$useDefaults) -> $html</tt>
   * =$web= the web of the topic being rendered
   * =$topic= the topic being rendered
   * =$meta= the meta data for the form
   * =$useDefaults= if true, will use default values from the form definition if no other value is given

Render the form fields for entry during an edit session, using data values
from $meta



---++ ObjectMethod *renderFieldForEdit* <tt>($fieldDef,$web,$topic,$value) -> $html</tt>
   * =$fieldDef= the field being rendered
   * =$web= the web of the topic being rendered
   * =$topic= the topic being rendered
   * =$value= the current value of the field

Render a single form field for entry during an edit session, using data values
from $meta. Plugins can provide a handler that extends the set of supported
types

SMELL: this should be a method on a field class
SMELL: JSCalendarContrib ought to provide a 'date' handler.



---++ ObjectMethod *renderHidden* <tt>($meta,$useDefaults) -> $html</tt>
   * =$useDefaults= if true, will use default values from the form definition if no other value is given

Render form fields found in the meta as hidden inputs, so they pass
through edits untouched.



---++ ObjectMethod *cgiName* <tt>($field) -> $string</tt>
Generate the 'name' of the CGI parameter used to represent a field.



---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject,$handleMandatory) -> $metaObject</tt>
Extract new values for form fields from a query.
   * =$query= - the query
   * =$metaObject= - the meta object that is storing the form values
   * =$handleMandatory= - if set, will throw an OopsException if any mandatory fields are absent from the query.

For each field, if there is a value in the query, use it.
Otherwise if there is already entry for the field in the meta, keep it.
Otherwise, if $handleMandatory, initialise the field to '' and set it in the meta.



---++ ObjectMethod *isTextMergeable* <tt>($name) -> $boolean</tt>
   * =$name= - name of a form field (value of the =name= attribute)
Returns true if the type of the named field allows it to be text-merged.

If the form does not define the field, it is assumed to be mergeable.



---++ ObjectMethod *getField* <tt>($name) -> \%row</tt>
   * =$name= - name of a form field (value of the =name= attribute)
Returns the field, or undef if the form does not define the field.



---++ StaticMethod *renderForDisplay* <tt>($templates,$meta)</tt>
   * =$templates= ref to templates singleton
   * =$meta= - meta object containing the form to be rendered
Static because we want to be able to do this without a form definition.

SMELL: Why? Is reading the form topic such a big burden?