.. ==================================================
.. FOR YOUR INFORMATION
.. --------------------------------------------------
.. -*- coding: utf-8 -*- with BOM.
.. include:: ../../Includes.txt
.. _cobj-form:
FORM
^^^^
.. note::
The following only applies, if the system extension "form" (which
comes with TYPO3 since version 4.6) is *not* installed. If it is, things
work as described in the documentation inside the system extension.
This object provides a way to create forms. Example::
textarea: Label | [* = required][field name =] textarea[,cols,rows,"wrap= [e.g. "OFF"]"] | [defaultdata] | Special evaluation configuration (see note below)
input: Label | [* = required][field name =] input[,size,max] | [defaultdata] | Special evaluation configuration (see note below)
password: Label | [* = required][field name =] input[,size,max] | [defaultdata]
file: Label | [* = required][field name (*1)=] file[,size]
check: Label | [* = required][field name =]check | [checked=1]
select: Label | [* = required][field name =]select[,size (int/"auto"), "m"=multiple] | label [=value] , ...
radio: Label | [* = required][field name =]radio | label [=value] , ...
hidden: |[field name =]hidden | value
submit: Label |[field name =]submit | Caption
reset: Label |[field name =]reset | Caption
label: Label | label | Label value
property: [Internal, see below]
.. _cobj-form-preselected-item:
Preselected item with type "select" and "radio":
""""""""""""""""""""""""""""""""""""""""""""""""
This is an example, where "Brown" is the preselected item of a
selector box::
Haircolor: | *haircolor=select| Blue=blue , Red=red , *Brown=brown
You can enter multiple items to be preselected by placing an asterisk
in front of each preselected item.
.. _cobj-form-property-override:
Property override:
""""""""""""""""""
This can be done with the following properties from the table below:
type, locationData, goodMess, badMess, emailMess
syntax::
|[property] =property | value
(\*1) (field name for files)
In order for files to be attached the mails, you must use the field
names:
*attachment, attachment1, ... , attachment10*
.. _cobj-form-displaying-the-form:
Displaying the form:
""""""""""""""""""""
**You must set the property "layout".** If you do not set it, the
form will not be rendered! For more information see the example and
the table below.
Example:
~~~~~~~~
::
temp.mailform = FORM
temp.mailform {
dataArray {
10.label = Name:
10.type = name=input
20.label = Nachricht:
20.type = nachricht=textarea,40,10
100.type = submit=submit
100.value = Absenden
}
recipient = info@example.com
layout =
###LABEL### ###FIELD###
}
.. _cobj-form-return-email:
Correct return-email:
"""""""""""""""""""""
In order for the mails to be attached with the email address of the
people that submits the mails, please use the field name "email", e.g::
Email: | *email=input |
.. _cobj-form-evaluation:
Special evaluation
""""""""""""""""""
By prefixing a "\*" before the field name of most types you can have
the value of the field required. The check is done in JavaScript; It
will only submit the form if this field is filled in.
Alternatively you can evaluate a field value against a regular
expression or as an email address for certain types (textarea,
password, input).
This is done by specifying the "Special evaluation configuration" for
those types as part 4 in the configuration line (see examples above).
The special evaluation types are divided by a semicolon (":").
The first part defines the evaluation **keyword**. Current options
are "EREG" (for regular expression) and "EMAIL" (for evaluation to an
email address).
If the "EREG" keyword is specified the 2 :sup:`nd` and 3 :sup:`rd`
parts are error message and regular expression respectively.
Examples:
~~~~~~~~~
::
Your address: | address=textarea,40,10 | | EREG : Only enter the characters A to Z : ^[a-zA-Z]*$
Your email: | *email=input | | EMAIL
.. ### BEGIN~OF~TABLE ###
.. container:: table-row
Property
data
Data type
string /:ref:`stdWrap `
Description
This is the data that sets up the form. See above.
"\|\|" can be used instead of line breaks
.. container:: table-row
Property
dataArray
Data type
*(array of form elements)*
Description
This is an alternative way to define the form-fields. Instead of using
the syntax with vertical separator bars suggested by the .data
property, you can define the elements in regular TypoScript style
arrays.
.dataArray is *added* to the input in .data if any.
Every entry in the dataArray is numeric and has three main properties,
*label*, *type*, *value* and *required*. All of them have
stdWrap properties.
There is an alternative property to .value, which is .valueArray. This
is also an array in the same style with numeric entries which has
properties *label*, *value* and *selected*. All three of these
properties have stdWrap properties.
**Example:** ::
dataArray {
10.label = Name:
10.type = name=input
10.value = [Enter name]
10.required = 1
20.label = Eyecolor
20.type = eyecolor=select
20.valueArray {
10.label = Blue
10.value = 1
20.label = Red
20.value = 2
20.selected = 1
}
40.type = submit=submit
40.value = Submit
}
This is the same as this line in the .data property::
Name: | *name=input | [Enter name]
Eyecolor: | eyecolor=select | Blue=1, *Red=2
| submit=submit | Submit
**Why do it this way?** Good question, but doing it this way has a
tremendous advantage, because labels are all separated from the codes.
In addition it's much easier to pull out or insert new elements in the
form.
Inserting an email-field after the name field would be like this::
dataArray {
15.label = Email:
15.type = input
15.value = your@email.com
15.specialEval = EMAIL
}
Or translating the form to danish (setting config.language to 'dk')::
dataArray {
10.label.lang.dk = Navn:
10.value.lang.dk = [Indtast dit navn]
20.label.lang.dk = Øjenfarve
20.valueArray {
10.label.lang.dk = Blå
20.label.lang.dk = Rød
}
40.value.lang.dk = Send
}
.. container:: table-row
Property
radioWrap
Data type
:ref:`->stdWrap `
Description
Wraps the labels for radio buttons.
.. container:: table-row
Property
radioWrap.accessibilityWrap
Data type
:ref:`wrap ` /:ref:`stdWrap `
Description
Defines how radio buttons are wrapped when accessibility mode is
turned on (see below "accessibility" property).
Default
.. container:: table-row
Property
radioInputWrap
Data type
:ref:`->stdWrap `
Description
Wraps the input element and label of a radio button.
.. container:: table-row
Property
type
Data type
integer, string
Description
Type (action="" of the form):
**Integer:** This is regarded to be a page in TYPO3.
**String:** This is regarded to be a normal URL (e.g. "formmail.php"
or "fe\_tce\_db.php").
**Empty:** The current page is chosen.
**Note:** If type is integer or empty, the form will be submitted to a
page in TYPO3 and if this page has a value for target/no\_cache, then
this will be used instead of the default target/no\_cache below.
**Note:** If the redirect-value is set, the redirect-target overrides
the target set by the action-url.
**Note:** May be overridden by the property override feature of the
formdata (see above).
.. container:: table-row
Property
target
Data type
:ref:`target ` /:ref:`stdWrap `
Description
Default target of the form.
.. container:: table-row
Property
method
Data type
form-method /:ref:`stdWrap `
Description
**Example:**
GET
Default
POST
.. container:: table-row
Property
no\_cache
Data type
string /:ref:`stdWrap `
Description
Default no\_cache-option.
.. container:: table-row
Property
noValueInsert
Data type
boolean /:ref:`stdWrap `
Description
By default values that are submitted to the same page (and thereby
same form, e.g. at search forms) are re-inserted in the form instead
of any default-data that might be set up.
This, however, applies ONLY if the "no\_cache=1" is set! (a page being
cached may not include user-specific defaults in the fields of
course...)
If you set this flag, "noValueInsert", the content will always be the
default content.
.. container:: table-row
Property
compensateFieldWidth
Data type
double /:ref:`stdWrap `
Description
Overriding option to the config-value of the same name. See "CONFIG"
above.
.. container:: table-row
Property
locationData
Data type
boolean / string /:ref:`stdWrap `
Description
If this value is true, then a hidden-field called "locationData" is
added to the form. This field will be loaded with a value like this:
[page id]:[current record table]:[current record id]
For example, if a formfield is inserted on page with uid = "100", as a
page-content item from the table "tt\_content" with id "120", then the
value would be "100:tt\_content:120".
The value is use by e.g. the cObject SEARCHRESULT. If the value
$GLOBALS['HTTP\_POST\_VARS']['locationData'] is detected here, the
search is done as if it was performed on this page! This is very
useful if you want a search functionality implemented on a page with
the "stype" field set to "L1" which means that the search is carried
out from the first level in the rootline.
Suppose you want the search to submit to a dedicated search page where
ever. This page will then know - because of locationData - that the
search was submitted from another place on the website.
If "locationData" is not only true but also set to "HTTP\_POST\_VARS"
then the value will insert the content of
$GLOBALS['HTTP\_POST\_VARS']['locationData'] instead of the true
location data of the page. This should be done with search-fields as
this will carry the initial searching start point with.
**Note:** May be overridden by the property override feature of the
formdata (see above)
.. container:: table-row
Property
redirect
Data type
string /:ref:`stdWrap `
Description
URL to redirect to (generates the hidden field "redirect")
**Integer:** This is regarded to be a page in TYPO3.
**String:** This is regarded to be a normal URL.
**Empty:** The current page is chosen.
**Note:** If this value is set, the target of this overrides the
target of the "type".
.. container:: table-row
Property
recipient
Data type
*(list of strings)* /:ref:`stdWrap `
Description
Email recipient of the formmail content (generates the hiddenfield
"recipient")
Default
No email
.. container:: table-row
Property
goodMess
Data type
string /:ref:`stdWrap `
Description
Message for the form evaluation function in case of correctly filled
form.
**Note:** May be overridden by the property override feature of the
formdata (see above).
Default
No message
.. container:: table-row
Property
badMess
Data type
string /:ref:`stdWrap `
Description
Message for the form evaluation in case of missing required fields.
This message is shown above the list of fields.
**Note:** May be overridden by the property override feature of the
formdata (see above).
Default
No message
.. container:: table-row
Property
emailMess
Data type
string /:ref:`stdWrap `
Description
Message if a field evaluated to be an email address did not validate.
**Note:** May be overridden by the property override feature of the
formdata (see above).
.. container:: table-row
Property
image
Data type
:ref:`->IMAGE ` (cObject)
Description
If this is a valid image, the submit button is rendered as this image.
**Note:** CurrentValue is set to the caption-label before generating
the image.
.. container:: table-row
Property
layout
Data type
string
Description
This defines how the label and the field are placed towards each
other.
**This property is mandatory; you must set it!** Otherwise the form
will not be rendered.
**Example:**
This substitutes the marker "###FIELD###" with the field data and the
marker "###LABEL###' with label data. ::
layout =
###FIELD###
###LABEL###
You can also use the marker ###COMMENT### which is ALSO the label
value inserted, but wrapped in .commentWrap stdWrap-properties (see
below).
.. container:: table-row
Property
fieldWrap
Data type
:ref:`->stdWrap `
Description
Field: Wraps the fields
.. container:: table-row
Property
labelWrap
Data type
:ref:`->stdWrap `
Description
Labels: Wraps the label
.. container:: table-row
Property
commentWrap
Data type
:ref:`->stdWrap `
Description
Comments: Wrap for comments IF you use ###COMMENT###
.. container:: table-row
Property
REQ
Data type
boolean /:ref:`stdWrap `
Description
Defines if required-fields should be checked and marked up.
.. container:: table-row
Property
REQ.fieldWrap
Data type
:ref:`->stdWrap `
Description
Field: Wraps the fields, but for required fields
Default
the "fieldWrap"-property
.. container:: table-row
Property
REQ.labelWrap
Data type
:ref:`->stdWrap `
Description
Labels: Wraps the label, but for required fields
Default
the "labelWrap"-property
.. container:: table-row
Property
REQ.layout
Data type
string /:ref:`stdWrap `
Description
The same as "layout" above, but for required fields
Default
the "layout"-property
.. container:: table-row
Property
COMMENT.layout
Data type
string /:ref:`stdWrap `
Description
Alternative layout for comments.
Default
the "layout"-property
.. container:: table-row
Property
CHECK.layout
Data type
string /:ref:`stdWrap `
Description
Alternative layout for checkboxes
Default
the "layout"-property
.. container:: table-row
Property
RADIO.layout
Data type
string /:ref:`stdWrap `
Description
Alternative layout for radio buttons
Default
the "layout"-property
.. container:: table-row
Property
LABEL.layout
Data type
string /:ref:`stdWrap `
Description
Alternative layout for label types
Default
the "layout"-property
.. container:: table-row
Property
stdWrap
Data type
:ref:`->stdWrap `
Description
Wraps the whole form (before form tag is added)
.. container:: table-row
Property
hiddenFields
Data type
*(array of cObjects)*
Description
Used to set hiddenFields from TS.
**Example:** ::
hiddenFields.pid = TEXT
hiddenFields.pid.value = 2
This makes a hidden-field with the name "pid" and value "2".
Available sub-property:
**stdWrap**, see :ref:`->stdWrap `.
.. container:: table-row
Property
params
Data type
form-element tag parameters /:ref:`stdWrap `
Description
Extra parameters to form elements.
**Example:** ::
params = style="width:200px;"
params.textarea = style="width:300px;"
params.check =
This sets the default to 200 px width, but excludes check-boxes and
sets textareas to 300.
**stdWrap** is available for the sub-properties, e.g. params.tagname.
.. container:: table-row
Property
wrapFieldName
Data type
:ref:`wrap ` /:ref:`stdWrap `
Description
This wraps the field names before they are applied to the form-field
tags.
**Example:**
If value is *tx\_myextension[input][ \| ]* then the field name
"email" would be wrapped to this value:
*tx\_myextension[input][email]*
.. container:: table-row
Property
noWrapAttr
Data type
boolean /:ref:`stdWrap `
Description
If this value is true then all wrap attributes of textarea elements
are suppressed. This is needed for XHTML-compliancy.
The wrap attributes can also be disabled on a per-field basis by using
the special keyword "disabled" as the value of the wrap attribute.
.. container:: table-row
Property
arrayReturnMode
Data type
boolean /:ref:`stdWrap `
Description
If set, the