data/TWiki/TWikiFormDotPm.txt,v
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 head	1.5;
       
     2 access;
       
     3 symbols;
       
     4 locks; strict;
       
     5 comment	@# @;
       
     6 
       
     7 
       
     8 1.5
       
     9 date	2008.01.22.03.21.35;	author TWikiContributor;	state Exp;
       
    10 branches;
       
    11 next	1.4;
       
    12 
       
    13 1.4
       
    14 date	2007.01.16.04.11.58;	author TWikiContributor;	state Exp;
       
    15 branches;
       
    16 next	1.3;
       
    17 
       
    18 1.3
       
    19 date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
       
    20 branches;
       
    21 next	1.2;
       
    22 
       
    23 1.2
       
    24 date	2006.04.01.05.55.39;	author TWikiContributor;	state Exp;
       
    25 branches;
       
    26 next	1.1;
       
    27 
       
    28 1.1
       
    29 date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
       
    30 branches;
       
    31 next	;
       
    32 
       
    33 
       
    34 desc
       
    35 @new-topic
       
    36 @
       
    37 
       
    38 
       
    39 1.5
       
    40 log
       
    41 @buildrelease
       
    42 @
       
    43 text
       
    44 @---+ Package =TWiki::Form=
       
    45 
       
    46 Object representing a single form definition.
       
    47 
       
    48 Form definitions are mainly used to control rendering of a form for
       
    49 editing, though there is some application login there that handles
       
    50 transferring values between edits and saves.
       
    51 
       
    52 A form definition consists of a TWiki::Form object, which has a list
       
    53 of field definitions. Each field definition is an object of a type
       
    54 derived from TWiki::Form::FieldDefinition. These objects are responsible
       
    55 for the actual syntax and semantics of the field type. Form definitions
       
    56 are parsed from TWiki tables, and the types are mapped by name to a
       
    57 class declared in TWiki::Form::* - for example, the =text= type is mapped
       
    58 to =TWiki::Form::Text= and the =checkbox= type to =TWiki::Form::Checkbox=.
       
    59 
       
    60 The =TWiki::Form::FieldDefinition= class declares default behaviours for
       
    61 types that accept a single value in their definitions. The
       
    62 =TWiki::Form::ListFieldDefinition= extends this for types that have lists
       
    63 of possible values.
       
    64 
       
    65 
       
    66 %TOC%
       
    67 
       
    68 ---++ ClassMethod *new* <tt>($session,$web,$form,$def)</tt>
       
    69 
       
    70 Looks up a form in the session object or, if it hasn't been read yet,
       
    71 reads it frm the form definition topic on disc.
       
    72    * $web - default web to recover form from, if $form doesn't specify a web
       
    73    * =$form= - topic name to read form definition from
       
    74    * =$def= - optional. a reference to a list of field definitions. if present,
       
    75               these definitions will be used, rather than those in =$form=.
       
    76 
       
    77 May throw TWiki::OopsException
       
    78 
       
    79 
       
    80 
       
    81 ---++ ObjectMethod *finish* <tt>()</tt>
       
    82 Break circular references.
       
    83 
       
    84 
       
    85 
       
    86 ---++ StaticMethod *fieldTitle2FieldName* <tt>($title) -> $name</tt>
       
    87 Chop out all except A-Za-z0-9_. from a field name to create a
       
    88 valid "name" for storing in meta-data
       
    89 
       
    90 
       
    91 
       
    92 ---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta) -> $html</tt>
       
    93 
       
    94    * =$web= the web of the topic being rendered
       
    95    * =$topic= the topic being rendered
       
    96    * =$meta= the meta data for the form
       
    97 
       
    98 Render the form fields for entry during an edit session, using data values
       
    99 from $meta
       
   100 
       
   101 
       
   102 
       
   103 ---++ ObjectMethod *renderHidden* <tt>($meta) -> $html</tt>
       
   104 
       
   105 Render form fields found in the meta as hidden inputs, so they pass
       
   106 through edits untouched.
       
   107 
       
   108 
       
   109 
       
   110 ---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject) -> ($seen,\@@missing)</tt>
       
   111 
       
   112 Extract new values for form fields from a query.
       
   113 
       
   114    * =$query= - the query
       
   115    * =$metaObject= - the meta object that is storing the form values
       
   116 
       
   117 For each field, if there is a value in the query, use it.
       
   118 Otherwise if there is already entry for the field in the meta, keep it.
       
   119 
       
   120 Returns the number of fields which had values provided by the query,
       
   121 and a references to an array of the names of mandatory fields that were
       
   122 missing from the query.
       
   123 
       
   124 
       
   125 
       
   126 ---++ ObjectMethod *isTextMergeable* <tt>($name) -> $boolean</tt>
       
   127 
       
   128    * =$name= - name of a form field (value of the =name= attribute)
       
   129 
       
   130 Returns true if the type of the named field allows it to be text-merged.
       
   131 
       
   132 If the form does not define the field, it is assumed to be mergeable.
       
   133 
       
   134 
       
   135 
       
   136 ---++ ObjectMethod *getField* <tt>($name) -> $fieldDefinition</tt>
       
   137 
       
   138    * =$name= - name of a form field (value of the =name= attribute)
       
   139 
       
   140 Returns a =TWiki::Form::FieldDefinition=, or undef if the form does not
       
   141 define the field.
       
   142 
       
   143 
       
   144 
       
   145 ---++ ObjectMethod *getFields* <tt>() -> \@@fields</tt>
       
   146 
       
   147 Return a list containing references to field name/value pairs.
       
   148 Each entry in the list has a {name} field and a {value} field. It may
       
   149 have other fields as well, which caller should ignore. The
       
   150 returned list should be treated as *read only* (must not be written to).
       
   151 
       
   152 
       
   153 @
       
   154 
       
   155 
       
   156 1.4
       
   157 log
       
   158 @buildrelease
       
   159 @
       
   160 text
       
   161 @d5 17
       
   162 d27 2
       
   163 d38 3
       
   164 a40 1
       
   165 ---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta) -> $html</tt>
       
   166 a41 3
       
   167    * =$web= the web of the topic being rendered
       
   168    * =$topic= the topic being rendered
       
   169    * =$meta= the meta data for the form
       
   170 d43 3
       
   171 a45 2
       
   172 Render the form fields for entry during an edit session, using data values
       
   173 from $meta
       
   174 d49 1
       
   175 a49 1
       
   176 ---++ ObjectMethod *renderFieldForEdit* <tt>($fieldDef,$web,$topic,$value) -> $html</tt>
       
   177 a50 1
       
   178    * =$fieldDef= the field being rendered
       
   179 d53 1
       
   180 a53 1
       
   181    * =$value= the current value of the field
       
   182 d55 2
       
   183 a56 5
       
   184 Render a single form field for entry during an edit session, using data values
       
   185 from $meta. Plugins can provide a handler that extends the set of supported
       
   186 types
       
   187 
       
   188 SMELL: this should be a method on a field class
       
   189 a66 6
       
   190 ---++ ObjectMethod *cgiName* <tt>($field) -> $string</tt>
       
   191 
       
   192 Generate the 'name' of the CGI parameter used to represent a field.
       
   193 
       
   194 
       
   195 
       
   196 d77 2
       
   197 a78 2
       
   198 Returns the number of fields which had values provided by the query, 
       
   199 and a references to an array of the names of mandatory fields that were 
       
   200 d93 1
       
   201 a93 1
       
   202 ---++ ObjectMethod *getField* <tt>($name) -> \%row</tt>
       
   203 d97 2
       
   204 a98 1
       
   205 Returns the field, or undef if the form does not define the field.
       
   206 a109 11
       
   207 
       
   208 ---++ StaticMethod *renderForDisplay* <tt>($templates,$meta)</tt>
       
   209 
       
   210    * =$templates= ref to templates singleton
       
   211    * =$meta= - meta object containing the form to be rendered
       
   212 
       
   213 Static because we want to be able to do this without a form definition.
       
   214 
       
   215 SMELL: Why? Is reading the form topic such a big burden?
       
   216 
       
   217 
       
   218 @
       
   219 
       
   220 
       
   221 1.3
       
   222 log
       
   223 @buildrelease
       
   224 @
       
   225 text
       
   226 @d8 1
       
   227 a8 1
       
   228 ---++ ClassMethod *new* <tt>($session,$web,$form)</tt>
       
   229 d12 2
       
   230 d20 1
       
   231 d31 1
       
   232 a41 1
       
   233 SMELL: JSCalendarContrib ought to provide a 'date' handler.
       
   234 d46 1
       
   235 d53 1
       
   236 d59 1
       
   237 d61 1
       
   238 d68 3
       
   239 a70 1
       
   240 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.
       
   241 d75 1
       
   242 d77 1
       
   243 d85 1
       
   244 d87 1
       
   245 d93 1
       
   246 d102 1
       
   247 d105 1
       
   248 @
       
   249 
       
   250 
       
   251 1.2
       
   252 log
       
   253 @buildrelease
       
   254 @
       
   255 text
       
   256 @d17 1
       
   257 a17 1
       
   258 ---++ ObjectMethod *renderForEdit* <tt>($web,$topic,$meta,$useDefaults) -> $html</tt>
       
   259 a20 1
       
   260    * =$useDefaults= if true, will use default values from the form definition if no other value is given
       
   261 d42 1
       
   262 a42 3
       
   263 ---++ ObjectMethod *renderHidden* <tt>($meta,$useDefaults) -> $html</tt>
       
   264    * =$useDefaults= if true, will use default values from the form definition if no other value is given
       
   265 
       
   266 d53 1
       
   267 a53 1
       
   268 ---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject,$initialiseMissing) -> ($seen,\@@missing)</tt>
       
   269 a56 1
       
   270    * =$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 ''.
       
   271 d79 8
       
   272 @
       
   273 
       
   274 
       
   275 1.1
       
   276 log
       
   277 @buildrelease
       
   278 @
       
   279 text
       
   280 @d56 1
       
   281 a56 1
       
   282 ---++ ObjectMethod *getFieldValuesFromQuery* <tt>($query,$metaObject,$handleMandatory) -> $metaObject</tt>
       
   283 d60 1
       
   284 a60 1
       
   285    * =$handleMandatory= - if set, will throw an OopsException if any mandatory fields are absent from the query.
       
   286 d64 2
       
   287 a65 1
       
   288 Otherwise, if $handleMandatory, initialise the field to '' and set it in the meta.
       
   289 @