data/TWiki/TWikiFormFieldDefinitionDotPm.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::FieldDefinition=
     2 
     3 Base class of all field definition classes.
     4 
     5 Type-specific classes are derived from this class to define specific
     6 per-type behaviours. This class also provides default behaviours for when
     7 a specific type cannot be loaded.
     8 
     9 
    10 %TOC%
    11 
    12 ---++ ClassMethod *new* <tt>(%...)</tt>
    13 
    14 Construct a new FieldDefinition. Parameters are passed in a hash. See
    15 Form.pm for how it is called. Subclasses should pass @_ on to this class.
    16 
    17 
    18 
    19 ---++ ObjectMethod *finish* <tt>()</tt>
    20 Break circular references.
    21 
    22 
    23 
    24 ---++ isEditable() -> $boolean
    25 
    26 Is the field type editable? Labels aren't, for example. Subclasses may need
    27 to redefine this.
    28 
    29 
    30 ---++ isMultiValued() -> $boolean
    31 
    32 Is the field type multi-valued (i.e. does it store multiple values)?
    33 Subclasses may need to redefine this.
    34 
    35 
    36 ---++ isTextMergeable() -> $boolean
    37 
    38 Is this field type mergeable using a conventional text merge?
    39 
    40 
    41 ---++ isMandatory() -> $boolean
    42 
    43 Is this field mandatory (required)?
    44 
    45 
    46 ---++ renderForEdit( $web, $topic, $value ) -> ($col0html, $col1html)
    47    =$web= - the web containing the topic being edited
    48    =$topic= - the topic being edited
    49 Render the field for editing. Returns two chunks of HTML; the
    50 =$col0html= is appended to the HTML for the first column in the
    51 form table, and the =$col1html= is used as the content of the second column.
    52 
    53 
    54 ---++ cssClasses(@classes) -> $classes
    55 Construct a list of the CSS classes for the form field. Adds additional
    56 class specifiers related to the attributes of the field e.g mandatory.
    57 Pass it a list of the other classnames you want on the field.
    58 
    59 
    60 ---++ getDefaultValue() -> $value
    61 Try and get a sensible default value for the field from the
    62 values stored in the form definition. The result should be
    63 a value string.
    64 
    65 Some subclasses may not support the definition of defaults in
    66 the form definition. In that case this method should return =undef=.
    67 
    68 
    69 ---++ renderHidden($meta) -> $html
    70 Render the form in =$meta= as a set of hidden fields.
    71 
    72 
    73 ---++ populateMetaDataFromQuery( $query, $meta, $old ) -> ($bValid, $bPresent)
    74 
    75 Given a CGI =$query=, a =$meta= object, and an array of =$old= field entries,
    76 then populate the $meta with a row for this field definition, taking the
    77 content from the query if it's there, otherwise from $old or failing that,
    78 from the default defined for the type. Refuses to update mandatory fields
    79 that have an empty value.
    80 
    81 Return $bValid true if the value in $meta was updated (either from the
    82 query or from a default in the form.
    83 Return $bPresent true if a value was present in the query (even it was undef)
    84 
    85 
    86 ---++ ObjectMethod *renderForDisplay* <tt>($format,$attrs) -> $html</tt>
    87 
    88 Render the field for display, under the control of $attrs.
    89 
    90 The following vars in $format are expanded:
    91    $title - title of the form field
    92    $value - expanded to the *protected* value of the form field
    93 
    94 The value is protected by TWiki::Render::protectFormFieldValue.
    95 
    96