This project is no longer maintained and no further public releases are planned.

No further support will be given.

Feel free to fork the git repository.

General Options

Any component and complete component arrays can be disabled via TypoScript.

Version added

1.0.0

TypoScript path

plugin.Tx_Formhandler.settings copy to clipboard

Example code

plugin.Tx_Formhandler.settings {
  validators {
    1 {
      class = Validator_Default
      disable = 1
      config.fieldConf {
        company.errorCheck.1 = required
        name.errorCheck.1 = required
      }
    }
  }

  finishers {
    disable = TEXT
    disable {
      value = 1
      if.isTrue.data = GP:test
    }
    1.class = Finisher_Mail
    1.config {
      admin {
        to_email = email@example.tld
        subject = TEXT
        subject.data = LLL:fileadmin/templates/ext/formhandler/lang.xml:email_admin_subject
        sender_email = email@example.tld
        attachment = picture
      }
      user {
        to_email = email
        subject = TEXT
        subject.data = LLL:fileadmin/templates/ext/formhandler/lang.xml:email_user_subject
        sender_email = email@example.tld
      }
    }
    2.class = Finisher_SubmittedOK
    2.config {
      returns = 1
    }
  }
}

Properties

.templateFile

Path to template file or template code

Data type

String / cObj

Version added

1.0.0

.masterTemplateFile

Path to master template file.

A master template can be used to predefine HTML code for various form fields or email templates. These predefined snippets can be used in the template file by just adding a marker there.

Data type

String / cObj / Array

Version added

1.0.0

Example code

#single master template
masterTemplateFile = fileadmin/templates/formmaster.html

#use a cObject
masterTemplateFile = TEXT
masterTemplateFile {
  value = fileadmin/mymastertemplate.html
}

#multiple master templates
masterTemplateFile {
  1 = fileadmin/templates/formmaster.html
  2 = fileadmin/templates/master_for_contactform.html
}

#use cObjects for multiple master templates
masterTemplateFile {
  1 = TEXT
  1.value = fileadmin/templates/formmaster.html
  2 = fileadmin/templates/master_for_contactform.html
}

.langFile

Path to language files

Data type

String | cObj | Array

Version added

1.0.0

Example code

#single lang file
langFile = fileadmin/lang/shared.xml

#use a cObject
langFile = TEXT
langFile.value = fileadmin/lang/shared.xml

#multiple lang files
langFile {
  1 = fileadmin/lang/shared.xml
  2 = fileadmin/lang/forms/mailformxy.xml
}

#use cObjects for multiple lang files
langFile {
  1 = TEXT
  1.value = fileadmin/lang/shared.xml
  2 = fileadmin/lang/forms/mailformxy.xml
}

.cssFile

Path to stylesheet file(s).

Since version 1.7.0 it is possible to specify various attributes for the tag. Have a look at "includeCSS" in the TSref to see possible settings. This requires TYPO3 version 6.0 or higher.

Data type

String | Array

Version added

1.0.0

Example code

cssFile = fileadmin/css/forms.css

cssFile {
  1 = fileadmin/css/forms.css
  2 = fileadmin/css/contactform.css
}

.jsFile

Path to JavaScript file(s).

Since version 1.7.0 it is possible to specify various attributes for the tag. Have a look at "includeJS" in the TSref to see possible settings. This requires TYPO3 version 6.0 or higher.

Data type

String | Array

Version added

1.0.0

Example code

jsFile = fileadmin/js/jquery.js

jsFile {
  1 = fileadmin/js/jquery.js
  2 = fileadmin/js/jquery_plugin.js
}

.jsFileFooter

Path to JavaScript file(s).

The same as ".jsFile", but the files are added before the closing BODY tag.

Data type

String | Array

Version added

2.0.0

Example code

jsFile = fileadmin/js/jquery.js

jsFile {
  1 = fileadmin/js/jquery.js
  2 = fileadmin/js/jquery_plugin.js
}

.view

Class name of the view to be used.

Similar to all other components like Finishers or PreProcessors, the setting "class" is mandatory to be set. You can set a configuration for the component in the section "config". See example code below.

Data type

String | cObj

Default value

Tx_Formhandler_View_Default

Version added

1.0.0

Example code

view {
  class = View_Form
  config {

  }
}

.controller

Class name of the controller to be used

Data type

String | cObj

Default value

Tx_Formhandler_Controller_Default

Version added

1.0.0

.formID

Value of the id attribute of the form tag. This is mandatory, if you use enableFileRemoval and have more than one form on a page.

Without formID the JavaScript code to remove a file from the uploaded files list submits the first form on the page.

Data type

String | cObj

Version added

1.0.0

.uniqueFormID

Specify your own unique form ID. If nothing is configured, Formhandler will generate a random hash for each form.

The unique form ID is used to store session values for each form so that they do not conflict with each other.

The drawback of a random hash is that you cannot access the session values in TypoScript without a custom userFunc.

Data type

String | cObj

Default value

Unique hash generated by Formhandler

Version added

1.0.0

.formValuesPrefix

Prefix of form fields. Use this if you use a prefix for your forms to avoid conflicts with other plugins. Settings this option you will be able to use only the fieldname in all markers and do not need to add prefix.

NOTE: It is highly recommended to use this setting!

Data type

String | cObj

Version added

1.0.0

Example code

<input type="text" name="formhandler[email]" value="###value_email###" />
 
<!-- Or use a marker in your HTML -->
<input type="text" name="###formValuesPrefix###[email]" value="###value_email###" />

.debug

Toggle debug mode, which will print debug messages to screen

Data type

Boolean | cObj

Version added

1.0.0

.disableConfigValidation

Formhandler will check if all needed classes are used in TypoScript for the values entered in Flexform. If you have your own components using the Flexform values, you can disable this check using disableConfigValidation = 1

Data type

Boolean | cObj

Version added

1.0.0

.disableWrapInBaseClass

Set this option to "1" to disable the default wrap with a DIV with class "Tx-Formhandler".

Data type

Boolean | cObj

Version added

1.1.0

.disableEncodingFields

Formhandler calls "htmlspecialchars" on each value before writing it into ###value_[fieldname]### markers.

Configure a comma separated list of field names which should not be encoded.

Data type

Comma separated list | cObj

Version added

1.7.0

.ajax

Configure an AjaxHandler that handles AJAX validation and AJAX based removal of uploaded files.

Data type

Array

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {
  ajax {
    class = AjaxHandler_JQuery
    config {
      ...
    }
  }
}

.requiredSign

Enter some text which will be used to substitute markers like ###required_[fieldname]###.

Data type

String | cObj

Default value

*

Version added

1.0.0

.requiredMarker

Allows to set a class name or similar for required fields. If set, the markers ###requiredMarker_[fieldname]### are replaced with the configured value. Useful to add required="required" attributes for required fields.

Data type

String | cObj

Version added

1.7.0

.singleErrorTemplate.totalWrap

Enter something to be wrapped around the error messages of a single form field.

Data type

Wrap

Version added

1.0.0

.singleErrorTemplate.singleWrap

Enter something to be wrapped around each error message of a single form field.

Data type

Wrap

Version added

1.0.0

.singleErrorTemplate.addDefaultMessage

Adds the error message found in 'error_[fieldname]' in the language file at any time.

Data type

Boolean | cObj

Version added

1.0.0

.errorListTemplate.totalWrap

Enter something to be wrapped around the error message list of all form fields.

Data type

Wrap

Version added

1.0.0

.errorListTemplate.singleWrap

Enter something to be wrapped around the error messages of a single form field in the list of all form fields.

Data type

Wrap

Version added

1.0.0

.singleFileMarkerTemplate.totalWrap

Enter something to be wrapped around the full list of filenames in a file marker for a single form field.

Data type

Wrap

Version added

1.0.0

.singleFileMarkerTemplate.singleWrap

Enter something to be wrapped around each filename in a file marker for a single form field. This wrap includes the remove link or the thumbnail.

Data type

Wrap

Version added

1.0.0

.singleFileMarkerTemplate.filenameWrap

Enter something to be wrapped around each filename in a file marker for a single form field. This wrap doesn't include the remove link or the thumbnail.

Data type

Wrap

Version added

1.4.0

.singleFileMarkerTemplate.showThumbnails

Shows thumbnail of uploaded file instead of filename. Set to 2 to display thumbnail and filename.

Data type

Integer (0,1,2)

Version added

1.0.0

.singleFileMarkerTemplate.image

IMAGE object for thumbnail generation. Image.file gets inserted by Formhandler

Data type

IMAGE

Version added

1.0.0

.totalFilesMarkerTemplate.totalWrap

Enter something to be wrapped around the full list of filenames in a file marker for all form fields.

Data type

Wrap

Version added

1.0.0

.totalFilesMarkerTemplate.singleWrap

Enter something to be wrapped around each filename in a file marker for all form fields. This wrap includes the remove link or the thumbnail.

Data type

Wrap

Version added

1.0.0

.totalFilesMarkerTemplate.filenameWrap

Enter something to be wrapped around each filename in a file marker for all form fields. This wrap doesn't include the remove link or the thumbnail.

Data type

Wrap

Version added

1.4.0

.totalFilesMarkerTemplate.showThumbnails

Shows thumbnail of uploaded file instead of filename. Set to 2 to display thumbnail and filename.

Data type

Integer (0,1,2)

Version added

1.0.0

.files.uploadFolder

Path to a custom upload folder.

Data type

String | cObj

Default value

uploads/formhandler/tmp

Version added

1.0.0

Important

Since version 1.4.0 you can specify different upload folders for different form fields!

Example code

uploadFolder = uploads/formhandler/

#since version 1.4.0
uploadFolder {
  #For all upload fields
  default = uploads/formhandler/

  #Files uploaded using the fields "pictures" or "documents" have different upload folders.
  pictures = uploads/pics/
  documents = uploads/media/
}

.files.enableAjaxFileRemoval

You need to use an AjaxHandler for this feature.

Adds a remove link to every filename in ###[fieldname]_uploadedFiles### and ###total_uploadedFiles###. Unfortunately other markers like ###[fieldname]_fileCount### will not be updated at the moment.

Data type

Boolean | cObj

Version added

1.0.0

.files.enableFileRemoval

Enables file removal without using an AjaxHandler. It will just display an “X” or anything entered in files.customRemovalText next to a file name of an uploaded file, so the user can remove it.

Without formID the JavaScript code to remove a file from the uploaded files list submits the first form on the page.

Data type

Boolean | cObj

Version added

1.0.0

.files.customRemovalText

Enter a custom text shown as the text of the remove link. Used in combination with files.enableAjaxFileRemoval and files.enableFileRemoval.

Data type

String | cObj

Default value

X

Version added

1.0.0

.files.search

Comma separated list of characters to replace in file names of uploaded files.

Useful in combination with files.replace.

Data type

String | cObj

Default value

Space character and %20

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {
  files {
    search = ä,ö,ü
    replace = ae,oe,ue
  }
}

.files.search.separator

Custom separator for several search patterns.

Data type

String | cObj

Default value

,

Version added

2.1.0

Example code

plugin.Tx_Formhandler.settings {
  files {
    search = ä|ö|ü
    search.separator = |
    replace = ae,oe,ue
  }
}

.files.replace

Comma separated list of characters to use as a replacement for the characters configured in files.search.

Data type

String | cObj

Default value

-

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {
  files {
    search = ä,ö,ü
    replace = ae,oe,ue
  }
}

.files.replace.separator

Custom separator for replacements.

The separator for replacements is inherited from files.search.separator, so you do not need to set it twice for search and replace.

Data type

String | cObj

Default value

,

Version added

2.1.0

.files.usePregReplace

Uses preg_replace to search and replace string in a filename in favor of a simple str_replace.

Data type

Boolean | cObj

Version added

1.4.0

Example code

files {
	usePregReplace = 1
	search = /[^A-Za-z0-9_.-]/
	replace = 
}

.files.uploadedFilesWithSameName

Specify how to deal with files with the same name being uploaded.

The possible values are:

ignore Default value. Files with the same name are ignored, no upload is done.
replace Files with the same name replace the existing ones.
append Files with the same name are appended to the list of uploaded files.

Data type

String | cObj

Default value

ignore

Version added

1.4.0

.markers.[markername]

Define your own custom markers and fill them using TypoScript.

Data type

Array

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {
  markers {
    myCustomMarker = TEXT
    myCustomMarker.value = Hello world
  }
}

.checkBoxFields

Comma seperated list of field names which contain checkbox values. This is needed for multipage forms in order to ensure correct submission of these values from step to step. Please enter all checkbox field names in here. Set this option per step.

Data type

String | cObj

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {

  # Checkbox fields in step 1
  1.checkBoxFields = interests, hobbies

  # Checkbox fields in step 2
  2.checkBoxFields = work_experience,accounts
}

.templateSuffix

With a templateSuffix you can define different template subparts for the same form step or email.
It can be used in combination with the setting if to define different routes through the form depending on the user input.

Have a look at “How to set up a multi step form with conditions” for details.

Data type

String | cObj

Version added

1.0.0

.checkBoxUncheckedValue

Lets you define values for unchecked checkboxes listed in checkBoxFields.

Data type

String | Array

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {

  # Default value for ALL checkboxes
  checkBoxUncheckedValue = no

  # Default value for a specific checkbox
  checkBoxUncheckedValue.myCheckBox = yes
}

.addErrorAnchors

If you use ###error### and error markers for each field, you can enable
this settings to add anchor links to each message in ###error###. The
anchors will point to the messages in ###error_[fieldname]###.

Data type

Boolean | cObj

Version added

1.0.0

.predef

Predefine form settings and make them selectable in plugin record.
Have a look at the section “How to use predefined forms

Data type

Array

Version added

1.0.0

.isErrorMarker

Configure replacements for ###is_error_[fieldname]### markers.

Data type

Array

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {
  isErrorMarker {
    global = Global message if an error occurred (filled into ###is_error###)
    default = class=”error” (filled into ###is_error_[fieldname]###
    field1 = TEXT
    field1.value = Some message (filled into ###is_error_field1###)
  }
}

.isSuccessMarker

Configure replacements for ###is_success_[fieldname]### markers.

Data type

Array

Version added

2.3.0

Example code

plugin.Tx_Formhandler.settings {
  isSuccessMarker {
    default = class="valid" #(filled into ###is_success_[fieldname]###
    field1 = TEXT
    field1.value = class="field1-valid" #(filled into ###is_success_field1###)
  }
}

.fillValueMarkersBeforeLangMarkers

If set to 1, the value markers (###value_[field]###) are replaced before the language markers (###LLL:[field]###).

Data type

Boolean | cObj

Version added

1.0.0

.arrayValueSeparator

Say you are using a checkbox array named "cb", then the marker ###value_cb### will contain a comma separated list of the selected values. Use this option to specifiy your own separator.

Data type

String | cObj

Version added

1.0.0

Example code

plugin.Tx_Formhandler.settings {
  arrayValueSeparator = |
}

.if

Define several conditions to change the behaviour of the form depending on user input.
These conditions can be used to show different form output or do different validation depending on what the user entered or selected before.

Have a look at “How to set up a multistep form with conditions” for details.

Data type

Array

Version added

1.0.0

.skipView

Skip all HTML output and call only the components in this order:

  1. PreProcessors
  2. InitInterceptors
  3. Validators
  4. SaveInterceptors
  5. Finishers

Use this if you want to use Formhandler for data processing only, e.g. to validate a generated auth code.

Data type

Integer - cObj

Version added

1.0.0

.usePredef

This option is useful if you call Formhandler inside your own plugin or with TypoScript. Setting this option to the key of a predefined form, Formhandler will use the configuration of the predefined form allthough it was called in PHP and therefore no plugin record or flexform data exists.

Data type

String

Version added

1.0.0

Example code

page.2 < plugin.tx_formhandler_pi1
page.2.usePredef = myContactForm.

.useDefaultStepBarStyles

If you use the marker ###step_bar### to insert an automatically created step bar, you can choose to use some default styles or choose to add your own styling.

Data type

Boolean | cObj

Version added

1.0.0

.stepbar_color

If you use the marker ###step_bar### to insert an automatically created step bar, you can specify the color of it.

Data type

String | cObj

Default value

#EAEAEA

Version added

1.0.0

.allowStepJumps

Formhandler only allows to go one steps ahead or back at a time. Enable this to allow jumping back and forth through steps. Only steps, that the user visited before are allowed. Use the setting "disableStepCheck" to allow all steps. You can use the markers ###submit_step_[stepnumber]### to create your submit buttons.

Data type

Boolean

Version added

1.5.0

Important

Use with care!

.disableStepCheck

If "allowStepJumps" is set to 1, use this setting to allow jumping to steps the user hasn't visited before, e.g. jumping from step 1 directly to step 4.

Data type

Boolean

Version added

1.5.0

.mailer

Since version 2.0.1 the mailer can be set globally, not only in the configuration of Finisher_Mail.

Check out the setting in the configuration of Finisher_Mail for more information.

Data type

Array

Default value

mailer { class = Mailer_HtmlMail }

Version added

2.0.1

Example code

mailer {
  class = Mailer_HtmlMail
}

mailer {
  class = Mailer_TYPO3Mailer
}