head	1.5;
access;
symbols;
locks; strict;
comment	@# @;


1.5
date	2008.01.22.03.21.35;	author TWikiContributor;	state Exp;
branches;
next	1.4;

1.4
date	2007.01.16.04.11.58;	author TWikiContributor;	state Exp;
branches;
next	1.3;

1.3
date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
branches;
next	1.2;

1.2
date	2006.04.01.05.55.39;	author TWikiContributor;	state Exp;
branches;
next	1.1;

1.1
date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
branches;
next	;


desc
@new-topic
@


1.5
log
@buildrelease
@
text
@---+ Package =TWiki::Form=

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.


%TOC%

---++ ClassMethod *new* <tt>($session,$web,$form,$def)</tt>

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



---++ ObjectMethod *finish* <tt>()</tt>
Break circular references.



---++ StaticMethod *fieldTitle2FieldName* <tt>($title) -> $name</tt>
Chop out all except A-Za-z0-9_. from a field name to create a
valid "name" for storing in meta-data



---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta) -> $html</tt>

   * =$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 *renderHidden* <tt>($meta) -> $html</tt>

Render form fields found in the meta as hidden inputs, so they pass
through edits untouched.



---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject) -> ($seen,\@@missing)</tt>

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

   * =$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* <tt>($name) -> $fieldDefinition</tt>

   * =$name= - name of a form field (value of the =name= attribute)

Returns a =TWiki::Form::FieldDefinition=, or undef if the form does not
define the field.



---++ ObjectMethod *getFields* <tt>() -> \@@fields</tt>

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


@


1.4
log
@buildrelease
@
text
@d5 17
d27 2
d38 3
a40 1
---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta) -> $html</tt>
a41 3
   * =$web= the web of the topic being rendered
   * =$topic= the topic being rendered
   * =$meta= the meta data for the form
d43 3
a45 2
Render the form fields for entry during an edit session, using data values
from $meta
d49 1
a49 1
---++ ObjectMethod *renderFieldForEdit* <tt>($fieldDef,$web,$topic,$value) -> $html</tt>
a50 1
   * =$fieldDef= the field being rendered
d53 1
a53 1
   * =$value= the current value of the field
d55 2
a56 5
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
a66 6
---++ ObjectMethod *cgiName* <tt>($field) -> $string</tt>

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



d77 2
a78 2
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 
d93 1
a93 1
---++ ObjectMethod *getField* <tt>($name) -> \%row</tt>
d97 2
a98 1
Returns the field, or undef if the form does not define the field.
a109 11

---++ StaticMethod *renderForDisplay* <tt>($templates,$meta)</tt>

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


@


1.3
log
@buildrelease
@
text
@d8 1
a8 1
---++ ClassMethod *new* <tt>($session,$web,$form)</tt>
d12 2
d20 1
d31 1
a41 1
SMELL: JSCalendarContrib ought to provide a 'date' handler.
d46 1
d53 1
d59 1
d61 1
d68 3
a70 1
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.
d75 1
d77 1
d85 1
d87 1
d93 1
d102 1
d105 1
@


1.2
log
@buildrelease
@
text
@d17 1
a17 1
---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta,$useDefaults) -> $html</tt>
a20 1
   * =$useDefaults= if true, will use default values from the form definition if no other value is given
d42 1
a42 3
---++ ObjectMethod *renderHidden* <tt>($meta,$useDefaults) -> $html</tt>
   * =$useDefaults= if true, will use default values from the form definition if no other value is given

d53 1
a53 1
---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject,$initialiseMissing) -> ($seen,\@@missing)</tt>
a56 1
   * =$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 ''.
d79 8
@


1.1
log
@buildrelease
@
text
@d56 1
a56 1
---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject,$handleMandatory) -> $metaObject</tt>
d60 1
a60 1
   * =$handleMandatory= - if set, will throw an OopsException if any mandatory fields are absent from the query.
d64 2
a65 1
Otherwise, if $handleMandatory, initialise the field to '' and set it in the meta.
@
