Object representing a single form definition.
+Form definitions are mainly used to control rendering of a form for editing, though there is some application login there that handles transferring values between edits and saves.
+
+A form definition consists of a TWiki::Form object, which has a list of field definitions. Each field definition is an object of a type derived from TWiki::Form::FieldDefinition. These objects are responsible for the actual syntax and semantics of the field type. Form definitions are parsed from TWiki tables, and the types are mapped by name to a class declared in TWiki::Form::\* - for example, the `text` type is mapped to `TWiki::Form::Text` and the `checkbox` type to `TWiki::Form::Checkbox`.
+
+The `TWiki::Form::FieldDefinition` class declares default behaviours for types that accept a single value in their definitions. The `TWiki::Form::ListFieldDefinition` extends this for types that have lists of possible values.
+
<div>
<ul>
<li><a href="#Package =TWiki::Form="> Package TWiki::Form</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$form,$def)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#StaticMethod *field_Title2FieldN"> StaticMethod fieldTitle2FieldName <tt>($title) -> $name</tt></a></li>
<li><a href="#ObjectMethod <strong>render_ForEdit</strong> ($"> ObjectMethod renderForEdit <tt>($web,$topic,$meta) -> $html</tt></a></li>
- <li><a href="#ObjectMethod *render_FieldForEdi"> ObjectMethod renderFieldForEdit <tt>($fieldDef,$web,$topic,$value) -> $html</tt></a></li>
<li><a href="#ObjectMethod <strong>renderHidden</strong> ($me"> ObjectMethod renderHidden <tt>($meta) -> $html</tt></a></li>
- <li><a href="#ObjectMethod <strong>cgiName</strong> ($field)"> ObjectMethod cgiName <tt>($field) -> $string</tt></a></li>
<li><a href="#ObjectMethod *get_FieldValuesFro"> ObjectMethod getFieldValuesFromQuery <tt>($query,$metaObject) -> ($seen,\@missing)</tt></a></li>
<li><a href="#ObjectMethod *is_TextMergeable*"> ObjectMethod isTextMergeable <tt>($name) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>getField</strong> ($name)"> ObjectMethod getField <tt>($name) -> \%row</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getField</strong> ($name)"> ObjectMethod getField <tt>($name) -> $fieldDefinition</tt></a></li>
<li><a href="#ObjectMethod <strong>getFields</strong> () -> \"> ObjectMethod getFields <tt>() -> \@fields</tt></a></li>
- <li><a href="#StaticMethod *render_ForDisplay*"> StaticMethod renderForDisplay <tt>($templates,$meta)</tt></a></li>
</ul>
</li>
</ul>
## <a name="ClassMethod <strong>new</strong> ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$form,$def)`
+Looks up a form in the session object or, if it hasn't been read yet, reads it frm the form definition topic on disc.
+
- $web - default web to recover form from, if $form doesn't specify a web
- `$form` - topic name to read form definition from
- `$def` - optional. a reference to a list of field definitions. if present, these definitions will be used, rather than those in `$form`.
May throw TWiki::OopsException
-## <a name="ObjectMethod <strong>render_ForEdit</strong> ($"></a> [[ObjectMethod]] **renderForEdit** `($web,$topic,$meta) -> $html`
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-- `$web` the web of the topic being rendered
-- `$topic` the topic being rendered
-- `$meta` the meta data for the form
+Break circular references.
-Render the form fields for entry during an edit session, using data values from $meta
+## <a name="StaticMethod <strong>field_Title2FieldN"></a> [[StaticMethod]] \*fieldTitle2FieldName `($title) -> $name`
+
+Chop out all except A-Za-z0-9\_. from a field name to create a valid "name" for storing in meta-data
-## <a name="ObjectMethod <strong>render_FieldForEdi"></a> [[ObjectMethod]] \*renderFieldForEdit `($fieldDef,$web,$topic,$value) -> $html`
+## <a name="ObjectMethod <strong>render_ForEdit</strong> ($"></a> [[ObjectMethod]] **renderForEdit** `($web,$topic,$meta) -> $html`
-- `$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
+- `$meta` the meta data for the form
-SMELL: this should be a method on a field class
+Render the form fields for entry during an edit session, using data values from $meta
## <a name="ObjectMethod <strong>renderHidden</strong> ($me"></a> [[ObjectMethod]] **renderHidden** `($meta) -> $html`
Render form fields found in the meta as hidden inputs, so they pass through edits untouched.
-## <a name="ObjectMethod <strong>cgiName</strong> ($field)"></a><a name="ObjectMethod <strong>cgiName</strong> ($field) "></a> [[ObjectMethod]] **cgiName** `($field) -> $string`
-
-Generate the 'name' of the CGI parameter used to represent a field.
-
## <a name="ObjectMethod <strong>get_FieldValuesFro"></a> [[ObjectMethod]] \*getFieldValuesFromQuery `($query,$metaObject) -> ($seen,\@missing)`
Extract new values for form fields from a query.
If the form does not define the field, it is assumed to be mergeable.
-## <a name="ObjectMethod <strong>getField</strong> ($name)"></a><a name="ObjectMethod <strong>getField</strong> ($name) "></a> [[ObjectMethod]] **getField** `($name) -> \%row`
+## <a name="ObjectMethod <strong>getField</strong> ($name)"></a><a name="ObjectMethod <strong>getField</strong> ($name) "></a> [[ObjectMethod]] **getField** `($name) -> $fieldDefinition`
- `$name` - name of a form field (value of the `name` attribute)
-Returns the field, or undef if the form does not define the field.
+Returns a `TWiki::Form::FieldDefinition`, or undef if the form does not define the field.
## <a name="ObjectMethod <strong>getFields</strong> () - \@"></a> [[ObjectMethod]] **getFields** `() -> \@fields`
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).
-
-## <a name="StaticMethod <strong>render_ForDisplay*"></a> [[StaticMethod]] \*renderForDisplay `($templates,$meta)`
-
-- `$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?
git://git.openafs.org / openafs-wiki.git / blobdiff