internal package Foswiki::Form::FieldDefinition

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

internal package Foswiki::Form::FieldDefinition

Base class of all field definition classes.

Type-specific classes are derived from this class to define specific per-type behaviours. This class also provides default behaviours for when a specific type cannot be loaded.

ClassMethod new(%...)

Construct a new FieldDefinition. Parameters are passed in a hash. See Form.pm for how it is called. Subclasses should pass @_ on to this class.

ObjectMethod finish()

Break circular references.

isEditable() -> $boolean

Is the field type editable? Labels aren't, for example. Subclasses may need to redefine this.

isMultiValued() -> $boolean

Is the field type multi-valued (i.e. does it store multiple values)? Subclasses may need to redefine this.

isTextMergeable() -> $boolean

Is this field type mergeable using a conventional text merge?

isMandatory() -> $boolean

Is this field mandatory (required)?

renderForEdit( $topicObject, $value ) -> ($col0html, $col1html)

$topicObject - the topic being edited Render the field for editing. Returns two chunks of HTML; the $col0html is appended to the HTML for the first column in the form table, and the $col1html is used as the content of the second column.

cssClasses(@classes) -> $classes

Construct a list of the CSS classes for the form field. Adds additional class specifiers related to the attributes of the field e.g mandatory. Pass it a list of the other classnames you want on the field.

getDefaultValue() -> $value

Try and get a sensible default value for the field from the values stored in the form definition. The result should be a value string.

Some subclasses may not support the definition of defaults in the form definition. In that case this method should return undef.

renderHidden($meta) -> $html

Render the form in $meta as a set of hidden fields.

ObjectMethod populateMetaDataFromQuery( $query, $meta, $old ) → ($bValid, $bPresent)

Given a CGI $query, a $meta object, and an array of $old field entries, then populate the $meta with a row for this field definition, taking the content from the query if it's there, otherwise from $old or failing that, from the default defined for the type. Refuses to update mandatory fields that have an empty value.

Return $bValid true if the value in $meta was updated (either from the query or from a default in the form. Return $bPresent true if a value was present in the query (even it was undef)

ObjectMethod createMetaKeyValues( $query, $meta, $keyvalues ) → $keyvalues

Create meta key/value pairs hash, to be overridden by subclasses. Default implementation passes all inputs unchanged.

ObjectMethod renderForDisplay($format, $value, $attrs) → $html

Render the field for display, under the control of $attrs.

(protected) means the resulting string is run through Foswiki::Render::protectFormFieldValue.

• format - the format to be expanded. The following tokens are available:
  • $title - title of the form field. if this is not available from the value, then the default title is taken from the form field definition.
  • $value - expanded to the (protected) value of the form field before mapping
  • =$value(display) - expanded to the (protected) value of the form field after mapping
  • $attributes - from the field definition
  • $type - from the field definition
  • $size - from the field definition
  • $definingTopic - topic in which the field is defined
• $value - the scalar value of the field
• $attrs - attributes. Fields used are:
  • showhidden - set to override H attribute
  • newline - replace newlines with this (default <br>)
  • bar - replace vbar with this (default &#124)
  • break - boolean, set to hyphenate
  • protectdollar - set to escape $
  • usetitle - if set, use this for the title rather than the title from the form definition

ObjectMethod getDisplayValue($value) → $html

Given a value for this form field, return the mapped value suitable for display. This is used when a form field must be displayed using a different format to the way the value is stored.

The default does nothing.