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)</tt></a></li>
   9         <li><a href="#ObjectMethod <strong>render_ForEdit</strong> ($"> ObjectMethod renderForEdit <tt>($web,$topic,$meta,$useDefaults) -&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,$useDefaults) -&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,$handleMandatory) -&gt; $metaObject</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="#StaticMethod *render_ForDisplay*"> StaticMethod renderForDisplay <tt>($templates,$meta)</tt></a></li>
  17       </ul>
  18     </li>
  19   </ul>
  20 </div>
  21
  22 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$form)`
  23
  24 - $web - default web to recover form from, if $form doesn't specify a web
  25 - `$form` - topic name to read form definition from
  26
  27 May throw TWiki::OopsException
  28
  29 ## <a name="ObjectMethod &lt;strong&gt;render_ForEdit&lt;/strong&gt; ($"></a> [[ObjectMethod]] **renderForEdit** `($web,$topic,$meta,$useDefaults) -> $html`
  30
  31 - `$web` the web of the topic being rendered
  32 - `$topic` the topic being rendered
  33 - `$meta` the meta data for the form
  34 - `$useDefaults` if true, will use default values from the form definition if no other value is given
  35
  36 Render the form fields for entry during an edit session, using data values from $meta
  37
  38 ## <a name="ObjectMethod &lt;strong&gt;render_FieldForEdi"></a> [[ObjectMethod]] \*renderFieldForEdit `($fieldDef,$web,$topic,$value) -> $html`
  39
  40 - `$fieldDef` the field being rendered
  41 - `$web` the web of the topic being rendered
  42 - `$topic` the topic being rendered
  43 - `$value` the current value of the field
  44
  45 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
  46
  47 SMELL: this should be a method on a field class SMELL: [[JSCalendarContrib]] ought to provide a 'date' handler.
  48
  49 ## <a name="ObjectMethod &lt;strong&gt;renderHidden&lt;/strong&gt; ($me"></a> [[ObjectMethod]] **renderHidden** `($meta,$useDefaults) -> $html`
  50
  51 - `$useDefaults` if true, will use default values from the form definition if no other value is given
  52
  53 Render form fields found in the meta as hidden inputs, so they pass through edits untouched.
  54
  55 ## <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`
  56
  57 Generate the 'name' of the CGI parameter used to represent a field.
  58
  59 ## <a name="ObjectMethod &lt;strong&gt;get_FieldValuesFro"></a> [[ObjectMethod]] \*getFieldValuesFromQuery `($query,$metaObject,$handleMandatory) -> $metaObject`
  60
  61 Extract new values for form fields from a query.
  62
  63 - `$query` - the query
  64 - `$metaObject` - the meta object that is storing the form values
  65 - `$handleMandatory` - if set, will throw an [[OopsException]] if any mandatory fields are absent from the query.
  66
  67 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.
  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="StaticMethod &lt;strong&gt;render_ForDisplay*"></a> [[StaticMethod]] \*renderForDisplay `($templates,$meta)`
  84
  85 - `$templates` ref to templates singleton
  86 - `$meta` - meta object containing the form to be rendered
  87
  88 Static because we want to be able to do this without a form definition.
  89
  90 SMELL: Why? Is reading the form topic such a big burden?