data/TWiki/TWikiFormDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 ---+ Package =TWiki::Form=
     2 
     3 Object representing a single form definition.
     4 
     5 Form definitions are mainly used to control rendering of a form for
     6 editing, though there is some application login there that handles
     7 transferring values between edits and saves.
     8 
     9 A form definition consists of a TWiki::Form object, which has a list
    10 of field definitions. Each field definition is an object of a type
    11 derived from TWiki::Form::FieldDefinition. These objects are responsible
    12 for the actual syntax and semantics of the field type. Form definitions
    13 are parsed from TWiki tables, and the types are mapped by name to a
    14 class declared in TWiki::Form::* - for example, the =text= type is mapped
    15 to =TWiki::Form::Text= and the =checkbox= type to =TWiki::Form::Checkbox=.
    16 
    17 The =TWiki::Form::FieldDefinition= class declares default behaviours for
    18 types that accept a single value in their definitions. The
    19 =TWiki::Form::ListFieldDefinition= extends this for types that have lists
    20 of possible values.
    21 
    22 
    23 %TOC%
    24 
    25 ---++ ClassMethod *new* <tt>($session,$web,$form,$def)</tt>
    26 
    27 Looks up a form in the session object or, if it hasn't been read yet,
    28 reads it frm the form definition topic on disc.
    29    * $web - default web to recover form from, if $form doesn't specify a web
    30    * =$form= - topic name to read form definition from
    31    * =$def= - optional. a reference to a list of field definitions. if present,
    32               these definitions will be used, rather than those in =$form=.
    33 
    34 May throw TWiki::OopsException
    35 
    36 
    37 
    38 ---++ ObjectMethod *finish* <tt>()</tt>
    39 Break circular references.
    40 
    41 
    42 
    43 ---++ StaticMethod *fieldTitle2FieldName* <tt>($title) -> $name</tt>
    44 Chop out all except A-Za-z0-9_. from a field name to create a
    45 valid "name" for storing in meta-data
    46 
    47 
    48 
    49 ---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta) -> $html</tt>
    50 
    51    * =$web= the web of the topic being rendered
    52    * =$topic= the topic being rendered
    53    * =$meta= the meta data for the form
    54 
    55 Render the form fields for entry during an edit session, using data values
    56 from $meta
    57 
    58 
    59 
    60 ---++ ObjectMethod *renderHidden* <tt>($meta) -> $html</tt>
    61 
    62 Render form fields found in the meta as hidden inputs, so they pass
    63 through edits untouched.
    64 
    65 
    66 
    67 ---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject) -> ($seen,\@missing)</tt>
    68 
    69 Extract new values for form fields from a query.
    70 
    71    * =$query= - the query
    72    * =$metaObject= - the meta object that is storing the form values
    73 
    74 For each field, if there is a value in the query, use it.
    75 Otherwise if there is already entry for the field in the meta, keep it.
    76 
    77 Returns the number of fields which had values provided by the query,
    78 and a references to an array of the names of mandatory fields that were
    79 missing from the query.
    80 
    81 
    82 
    83 ---++ ObjectMethod *isTextMergeable* <tt>($name) -> $boolean</tt>
    84 
    85    * =$name= - name of a form field (value of the =name= attribute)
    86 
    87 Returns true if the type of the named field allows it to be text-merged.
    88 
    89 If the form does not define the field, it is assumed to be mergeable.
    90 
    91 
    92 
    93 ---++ ObjectMethod *getField* <tt>($name) -> $fieldDefinition</tt>
    94 
    95    * =$name= - name of a form field (value of the =name= attribute)
    96 
    97 Returns a =TWiki::Form::FieldDefinition=, or undef if the form does not
    98 define the field.
    99 
   100 
   101 
   102 ---++ ObjectMethod *getFields* <tt>() -> \@fields</tt>
   103 
   104 Return a list containing references to field name/value pairs.
   105 Each entry in the list has a {name} field and a {value} field. It may
   106 have other fields as well, which caller should ignore. The
   107 returned list should be treated as *read only* (must not be written to).
   108 
   109