PerlDoc

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

internal package Foswiki::Form is a Foswiki::Meta

Object representing a single form definition.

Form definitions are mainly used to control rendering of a form for editing, though there is some application login there that handles transferring values between edits and saves.

A form definition consists of a Foswiki::Form object, which has a list of field definitions. Each field definition is an object of a type derived from Foswiki::Form::FieldDefinition. These objects are responsible for the actual syntax and semantics of the field type. Form definitions are parsed from Foswiki tables, and the types are mapped by name to a class declared in Foswiki::Form::* - for example, the text type is mapped to Foswiki::Form::Text and the checkbox type to Foswiki::Form::Checkbox.

The Foswiki::Form::FieldDefinition class declares default behaviours for types that accept a single value in their definitions. The Foswiki::Form::ListFieldDefinition extends this for types that have lists of possible values.

ClassMethod new ( $session, $web, $topic, \@def )

Looks up a form in the session object or, if it hasn't been read yet, reads it from the form definition topic on disc.

• $web - default web to recover form from, if $form doesn't specify a web
• $topic - name of the topic that contains the form definition
• \@def - optional. A reference to a list of field definitions. If present, these definitions will be used, rather than any read from the form definition topic.

May throw Foswiki::OopsException if the web and form are not valid for use as a form name, or if \@def is not given and the form does not exist in the database. May throw Foswiki::AccessControlException if the form schema in the database is protected against view.

ObjectMethod finish()

Break circular references.

StaticMethod getAvailableForms( $metaObject ) → @forms

Get a list of the names of forms that are available for use in the given topic. $metaObject can be a topic or a web.

StaticMethod fieldTitle2FieldName($title) → $name

Chop out all except \w. from a field name to create a valid "name" for storing in meta-data

ObjectMethod renderForEdit( $topicObject ) → $html

• $topicObject the topic being rendered

Render the form fields for entry during an edit session, using data values from $meta

ObjectMethod renderHidden( $topicObject ) → $html

Render form fields found in the meta as hidden inputs, so they pass through edits untouched.

ObjectMethod getFieldValuesFromQuery($query, $topicObject) → ( $seen, \@missing )

Extract new values for form fields from a query.

• $query - the query
• $topicObject - the meta object that is storing the form values

For each field, if there is a value in the query, use it. Otherwise if there is already entry for the field in the meta, keep it.

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.

ObjectMethod isTextMergeable( $name ) → $boolean

• $name - name of a form field (value of the name attribute)

Returns true if the type of the named field allows it to be text-merged.

If the form does not define the field, it is assumed to be mergeable.

ObjectMethod getField( $name ) → $fieldDefinition

• $name - name of a form field (value of the name attribute)

Returns a Foswiki::Form::FieldDefinition, or undef if the form does not define the field.

ObjectMethod getFields() → \@fields

Return a list containing references to field name/value pairs. Each entry in the list has a {name} field and a {value} field. It may have other fields as well, which caller should ignore. The returned list should be treated as read only (must not be written to).