Difference: TWikiFormDotPm (1 vs. 7)

Revision 72014-10-05 - TWikiContributor

Line: 30 to 30
 
  • $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.
Added:
>
>
  • $options - hash reference having various options. Curently the boolean option suppressValsEval is the only one supported
  May throw TWiki::OopsException

Revision 62013-10-14 - TWikiContributor

Line: 40 to 40
 
Added:
>
>

StaticMethod getListOfForms ($session,$web) -> @topics

Return a list of TWiki Form Templates found in a web. The name of Form Template topics ends in Form, and topics must contain a table heading like this:

Name Type Size Value Tooltip message Attributes
followed by form field definitions.

 

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

Revision 52008-01-22 - TWikiContributor

Line: 2 to 2
  Object representing a single form definition.
Added:
>
>
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.

 

ClassMethod new ($session,$web,$form,$def)

Added:
>
>
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,
Line: 16 to 35
 
Changed:
<
<

ObjectMethod renderForEdit ($web,$topic,$meta) -> $html

>
>

ObjectMethod finish ()

Break circular references.
 
Deleted:
<
<
  • $web the web of the topic being rendered
  • $topic the topic being rendered
  • $meta the meta data for the form
 
Changed:
<
<
Render the form fields for entry during an edit session, using data values from $meta
>
>

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
 
Changed:
<
<

ObjectMethod renderFieldForEdit ($fieldDef,$web,$topic,$value) -> $html

>
>

ObjectMethod renderForEdit ($web,$topic,$meta) -> $html

 
Deleted:
<
<
  • $fieldDef the field being rendered
 
  • $web the web of the topic being rendered
  • $topic the topic being rendered
Changed:
<
<
  • $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
 
Changed:
<
<
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
 
Line: 49 to 64
 
Deleted:
<
<

ObjectMethod cgiName ($field) -> $string

Generate the 'name' of the CGI parameter used to represent a field.

 

ObjectMethod getFieldValuesFromQuery ($query,$metaObject) -> ($seen,\@missing)

Extract new values for form fields from a query.

Line: 81 to 90
 
Changed:
<
<

ObjectMethod getField ($name) -> \%row

>
>

ObjectMethod getField ($name) -> $fieldDefinition

 
  • $name - name of a form field (value of the name attribute)
Changed:
<
<
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.
 
Line: 97 to 107
 returned list should be treated as read only (must not be written to).
Deleted:
<
<

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?

Revision 42007-01-16 - TWikiContributor

Line: 5 to 5
 
Changed:
<
<

ClassMethod new ($session,$web,$form)

>
>

ClassMethod new ($session,$web,$form,$def)

 
  • $web - default web to recover form from, if $form doesn't specify a web
  • $form - topic name to read form definition from
Added:
>
>
  • $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
Line: 35 to 39
 types

SMELL: this should be a method on a field class

Deleted:
<
<
SMELL: JSCalendarContrib ought to provide a 'date' handler.
 
Line: 51 to 56
 

ObjectMethod getFieldValuesFromQuery ($query,$metaObject) -> ($seen,\@missing)

Added:
>
>
 Extract new values for form fields from a query.
Added:
>
>
 
  • $query - the query
  • $metaObject - the meta object that is storing the form values

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.

Changed:
<
<
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.
>
>
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.
 

Revision 32006-06-25 - TWikiContributor

Line: 14 to 14
 
Changed:
<
<

ObjectMethod renderForEdit ($web,$topic,$meta,$useDefaults) -> $html

>
>

ObjectMethod renderForEdit ($web,$topic,$meta) -> $html

 
  • $web the web of the topic being rendered
  • $topic the topic being rendered
  • $meta the meta data for the form
Deleted:
<
<
  • $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
Line: 40 to 39
 
Changed:
<
<

ObjectMethod renderHidden ($meta,$useDefaults) -> $html

  • $useDefaults if true, will use default values from the form definition if no other value is given
>
>

ObjectMethod renderHidden ($meta) -> $html

 Render form fields found in the meta as hidden inputs, so they pass through edits untouched.
Line: 53 to 50
 
Changed:
<
<

ObjectMethod getFieldValuesFromQuery ($query,$metaObject,$initialiseMissing) -> ($seen,\@missing)

>
>

ObjectMethod getFieldValuesFromQuery ($query,$metaObject) -> ($seen,\@missing)

 Extract new values for form fields from a query.
  • $query - the query
  • $metaObject - the meta object that is storing the form values
Deleted:
<
<
  • $initialiseMissing - if true, will cause fields that are in the form but have no value in the query or in the meta to be initialised to ''.
  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.
Line: 80 to 76
 
Added:
>
>

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).

 

StaticMethod renderForDisplay ($templates,$meta)

  • $templates ref to templates singleton
  • $meta - meta object containing the form to be rendered

Revision 22006-04-01 - TWikiContributor

Line: 53 to 53
 
Changed:
<
<

ObjectMethod getFieldValuesFromQuery ($query,$metaObject,$handleMandatory) -> $metaObject

>
>

ObjectMethod getFieldValuesFromQuery ($query,$metaObject,$initialiseMissing) -> ($seen,\@missing)

 Extract new values for form fields from a query.
  • $query - the query
  • $metaObject - the meta object that is storing the form values
Changed:
<
<
  • $handleMandatory - if set, will throw an OopsException if any mandatory fields are absent from the query.
>
>
  • $initialiseMissing - if true, will cause fields that are in the form but have no value in the query or in the meta to be initialised to ''.
  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.
Changed:
<
<
Otherwise, if $handleMandatory, initialise the field to '' and set it in the meta.
>
>
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.
 

Revision 12006-02-01 - TWikiContributor

Line: 1 to 1
Added:
>
>

Package TWiki::Form

Object representing a single form definition.

ClassMethod new ($session,$web,$form)

  • $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 ($web,$topic,$meta,$useDefaults) -> $html

  • $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 ($fieldDef,$web,$topic,$value) -> $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

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

ObjectMethod renderHidden ($meta,$useDefaults) -> $html

  • $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 ($field) -> $string

Generate the 'name' of the CGI parameter used to represent a field.

ObjectMethod getFieldValuesFromQuery ($query,$metaObject,$handleMandatory) -> $metaObject

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 ($name) -> $boolean

  • $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 ($name) -> \%row

  • $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 ($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?

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiFormDotPm.