data/TWiki/TWikiFormFieldDefinitionDotPm.txt
changeset 0 414e01d06fd5
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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