TWiki/TWikiFormDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Form="></a> Package =TWiki::Form
   2
   3 Object representing a single form definition.
   4
   5 <div>
   6   <ul>
   7     <li><a href="#Package =TWiki::Form="> Package TWiki::Form</a><ul>
   8         <li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$form,$def)</tt></a></li>
   9         <li><a href="#ObjectMethod <strong>render_ForEdit</strong> ($"> ObjectMethod renderForEdit <tt>($web,$topic,$meta) -&gt; $html</tt></a></li>
  10         <li><a href="#ObjectMethod *render_FieldForEdi"> ObjectMethod renderFieldForEdit <tt>($fieldDef,$web,$topic,$value) -&gt; $html</tt></a></li>
  11         <li><a href="#ObjectMethod <strong>renderHidden</strong> ($me"> ObjectMethod renderHidden <tt>($meta) -&gt; $html</tt></a></li>
  12         <li><a href="#ObjectMethod <strong>cgiName</strong> ($field)"> ObjectMethod cgiName <tt>($field) -&gt; $string</tt></a></li>
  13         <li><a href="#ObjectMethod *get_FieldValuesFro"> ObjectMethod getFieldValuesFromQuery <tt>($query,$metaObject) -&gt; ($seen,\@missing)</tt></a></li>
  14         <li><a href="#ObjectMethod *is_TextMergeable*"> ObjectMethod isTextMergeable <tt>($name) -&gt; $boolean</tt></a></li>
  15         <li><a href="#ObjectMethod <strong>getField</strong> ($name)"> ObjectMethod getField <tt>($name) -&gt; \%row</tt></a></li>
  16         <li><a href="#ObjectMethod <strong>getFields</strong> () -> \"> ObjectMethod getFields <tt>() -&gt; \@fields</tt></a></li>
  17         <li><a href="#StaticMethod *render_ForDisplay*"> StaticMethod renderForDisplay <tt>($templates,$meta)</tt></a></li>
  18       </ul>
  19     </li>
  20   </ul>
  21 </div>
  22
  23 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$form,$def)`
  24
  25 - $web - default web to recover form from, if $form doesn't specify a web
  26 - `$form` - topic name to read form definition from
  27 - `$def` - optional. a reference to a list of field definitions. if present, these definitions will be used, rather than those in `$form`.
  28
  29 May throw TWiki::OopsException
  30
  31 ## <a name="ObjectMethod &lt;strong&gt;render_ForEdit&lt;/strong&gt; ($"></a> [[ObjectMethod]] **renderForEdit** `($web,$topic,$meta) -> $html`
  32
  33 - `$web` the web of the topic being rendered
  34 - `$topic` the topic being rendered
  35 - `$meta` the meta data for the form
  36
  37 Render the form fields for entry during an edit session, using data values from $meta
  38
  39 ## <a name="ObjectMethod &lt;strong&gt;render_FieldForEdi"></a> [[ObjectMethod]] \*renderFieldForEdit `($fieldDef,$web,$topic,$value) -> $html`
  40
  41 - `$fieldDef` the field being rendered
  42 - `$web` the web of the topic being rendered
  43 - `$topic` the topic being rendered
  44 - `$value` the current value of the field
  45
  46 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
  47
  48 SMELL: this should be a method on a field class
  49
  50 ## <a name="ObjectMethod &lt;strong&gt;renderHidden&lt;/strong&gt; ($me"></a> [[ObjectMethod]] **renderHidden** `($meta) -> $html`
  51
  52 Render form fields found in the meta as hidden inputs, so they pass through edits untouched.
  53
  54 ## <a name="ObjectMethod &lt;strong&gt;cgiName&lt;/strong&gt; ($field)"></a><a name="ObjectMethod &lt;strong&gt;cgiName&lt;/strong&gt; ($field) "></a> [[ObjectMethod]] **cgiName** `($field) -> $string`
  55
  56 Generate the 'name' of the CGI parameter used to represent a field.
  57
  58 ## <a name="ObjectMethod &lt;strong&gt;get_FieldValuesFro"></a> [[ObjectMethod]] \*getFieldValuesFromQuery `($query,$metaObject) -> ($seen,\@missing)`
  59
  60 Extract new values for form fields from a query.
  61
  62 - `$query` - the query
  63 - `$metaObject` - the meta object that is storing the form values
  64
  65 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.
  66
  67 Returns the number of fields which had values provided by the query, and a references to an array of the names of mandatory fields that were missing from the query.
  68
  69 ## <a name="ObjectMethod &lt;strong&gt;is_TextMergeable*"></a><a name="ObjectMethod *is_TextMergeable&lt;/strong&gt; "></a> [[ObjectMethod]] **isTextMergeable** `($name) -> $boolean`
  70
  71 - `$name` - name of a form field (value of the `name` attribute)
  72
  73 Returns true if the type of the named field allows it to be text-merged.
  74
  75 If the form does not define the field, it is assumed to be mergeable.
  76
  77 ## <a name="ObjectMethod &lt;strong&gt;getField&lt;/strong&gt; ($name)"></a><a name="ObjectMethod &lt;strong&gt;getField&lt;/strong&gt; ($name) "></a> [[ObjectMethod]] **getField** `($name) -> \%row`
  78
  79 - `$name` - name of a form field (value of the `name` attribute)
  80
  81 Returns the field, or undef if the form does not define the field.
  82
  83 ## <a name="ObjectMethod &lt;strong&gt;getFields&lt;/strong&gt; () - \@"></a> [[ObjectMethod]] **getFields** `() -> \@fields`
  84
  85 Return a list containing references to field name/value pairs. Each entry in the list has a \{name\} field and a \{value\} field. It may have other fields as well, which caller should ignore. The returned list should be treated as **read only** (must not be written to).
  86
  87 ## <a name="StaticMethod &lt;strong&gt;render_ForDisplay*"></a> [[StaticMethod]] \*renderForDisplay `($templates,$meta)`
  88
  89 - `$templates` ref to templates singleton
  90 - `$meta` - meta object containing the form to be rendered
  91
  92 Static because we want to be able to do this without a form definition.
  93
  94 SMELL: Why? Is reading the form topic such a big burden?