Module name TWiki::Form.pm FormDotPm Location TWIKIROOT/lib/TWiki/Form.pm Summary Handle the encoding and decoding of the TWikiForms presented at the bottom of each page Primary Author JohnTalintyre CVS history CVS:lib/TWiki/Form.pm CVS alpha CVSget:lib/TWiki/Form.pm Contributing authors (see CVS History) Is Class NO First Release to be filled out

File Hierarchy   TWIKIROOT   lib   TWiki   Form.pm

Purpose

To handle the encoding and decoding of the TWikiForms

Used by

This module is primarily used by the ViewCgiScript and EditCgiScript.

Please see CodevDocumentationProject and CodevDocumentationProjectDev for comments on the format of these pages.

package TWiki::Form

Object representing a single form definition.

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
   * =$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

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

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

ObjectMethod renderHidden( $meta ) -> $html

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) -> ( $seen, \@missing )

Extract new values for form fields from a query.

   * =$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.

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.

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.

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

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?

Contributors:
-- MartinCleaver - 23 Jun 2002
-- PeterThoeny - 02 Feb 2004

Discussions

No documentation!

How do I get a list of fields on a given form?

-- MartinCleaver - 03 Oct 2004