doc Quickform

Table of content

No such droplet: TableOfContent?to=3

Quickform Intro

The quickform modules allows you to easily create a contact form for your website, based on a form template.
Several form templates are included in the quickform package, which can be used as a base for your own template.

Note that the information below are valid starting with Quickform version 2.0. Earlier versions does not covers the below described functionality or only partially.

If you have any questions referring to this addon please visit the addons forum .

Quickform in action

When a quickform form is shown in the frontend, the form data can be entered and submitted.
With submit, a mail is send to the mail address defined in the quickform settings, containing all available form fields with entered values, and same is also saved in the database. It is also possible to send a mail copy to contact requestor, see below.

Quickform settings

Selection of the frontend form:
Allows you to select the language dependend form template, either one from the quickform package or one of your ownes.
After save it is also possible to modify your template directly inside the backend.
Templates are saved in modules/quickform/templates/XX/ folder, whereas XX stands for the abbreviation of the current page language (e.g. en for english).
In case you have a multi language page with a contact form on each, you need to have a quickform template for each of your languages.
Within the quickform packages, templates in english (en), german (de), french (fr) and dutch (nl) are delivered.
In case you want to have a form template in a different language, you need to create the respective language folder with at least 1 template manually directly on the server first.
For more info about quickform templates please see below.
Email receiver:
This is the mail address which receives the submitted quickform form mails.
Email subject:
The mail subject for the quickform form mails, received by the Email receiver as well (if defined) as copy to the contact requestor.
Success page:
The page to be shown after the quickform form has been submitted. Alternativly a default success message can be shown.

Thank you for filling out this form.
We will contact you ASAP.

Quickform buttons

Spam Check Settings
Open the setting page for the Spam check.
For more information about this settings please check below.
Modul Info
Open a page with information about the quickform module.
Help
Open this documentation in a new browser tab.
Modify Template
Allows the modification of the currently selected template.
Note this feature is available only after settings has been saved.
For more info about quickform templates please see below.
Inbox | additional own defined groups
All quickform forms requests are listed in group "Inbox".
To show the content of such a group, press the button with the respective group name.
However, messages can be moved into other groups (with a name defined by yourself) like "done" or "archive" or " t.b.d." or whatever else you want.
To move a message (or all messages shown) into another existing group, click on the "move" button (see below) and select the group you want as target.
To move a message (or all messages shown) into a new group, click first on the "move" button (see below) and afterwards on the "+" Button appearing. Then enter the name of the new group and confirm.
In case all messages of an existing group (e.g. group "t.b.d") are moved into another group (e.g. "done"), the empty group is automatically removed from the group list.

While showing messages inside a group, additional buttons are available:

X
Close the currently shown group.
10 | 25 | 50 | 75 | 100
Defines the number of messages to be shown within a group.
Note that this setting is saved and used for all available groups for all users with access to this page & module.
Mail view | Table view
Defines the information shown in the messages list. Try it out to see the differences.
Note that this setting is saved and used for all available groups for all users with access to this page & module.
Please note also that this has no impact in the mail generation in the frontend.
Delete all messages shown / Delete this message
Deletes all messages shown (depending on the selected number of messages to be shown) or only the current message.
Move all messages shown / Move this message
Messages can be bundled together into groups. The default group for new incoming messages is the group "Inbox". New Groups can be created on the fly by pressing the "Move" button, then the "+" button and entering a new group name.
Show/hide all messages sent / Show/hide message sent
Shows (or hide) for all messages shown (depending on the selected number of messages to be shown) or only the current message, the mail generated in frontend after quickform form submit, which has been send to defined Email receiver.

Spam Check Settings

With quickform v2 a honeypot functionality has been included, in order to reduce the possible spam received from spambots.

Please note that neither Captcha's nor Honeypot's are able to avoid spam completly.

More information about honeypot can be found here on wikipedia.

Idea of Honeypots

Create a non visible field for frontend users (but hopefully visible and noticed by spambots). When field is filled, something went wrong and form entry is handled as spam.

Settings

Use Honeypot functionality
OFF = no honeypot logic is used
ON = the flags listed below are taken into account
Spam logging in TEMP table in the database
For a proper handling of spam detection, the ip and browser fingerprints are saved in TEMP table in database.
With each form request, all DB entries related to quickform and older than 1 hour are deleted.
With quickform v2, setting this flag ON or OFF does not have any valuable effect. When ON and spam check failed, just a counter is increased.
This flag has not been used yet to fully extend but might be used in future for additional checks.
Minimum number of seconds (0 - 60) for form data entry
defines the minimum time in seconds which have to be passed between the preparation of the screen and the submit receive. When below this time, the form entry is handled as spam.
Idea behind is that most spams comes from spambots, which are much faster than humans.
In case number of seconds is set to 0, this check is not executed.
HoneyPot field / comma separated field list
a dummy field label or label list to be used as a honeypot field. In case of label list, each time the form is shown in frontend, randomly 1 field label out of the list is choosen.
It is proposed to use field labels which also might be used as normal fields, like address, age, city, street, etc.
Please do not use labels used already in your template!
Also please do not use spaces or strange characters in your names ...
Action on error
In case the form entry has been detected as spam, the action to occur has to be defined here.
Either to show another page or show a default message:

Oops, unfortunately an error has occurred. Please try again later.

Use Honeypot in template

To use a honeypot field in your template, you can crosscheck the honeypot template delivered with quickform module package.
At it's just a bit of code.

{# --- Honeypot id, must be hidden. This is required field when honeypot functionality is used --- #}
	< input type="hidden" name="index" value="{{ HONEYPOT_INDEX }}" />

{# --- Honeypot field, should be hidden. Can be placed anywhere in the form --- #}
{% if HONEYPOT_FIELD %}
	< label class="something_hidden">{{ HONEYPOT_FIELD|capitalize }}
		< input type="text" 
			class="something_hidden"
			name="qf_{{ HONEYPOT_FIELD }}"
			id="{{ HONEYPOT_FIELD }}"
			value="{{ _context[HONEYPOT_FIELD|upper] }}"
		/>
	< /label >
{% endif %}

In addition you need a CSS class which hides the honeypot label and the field. For security reason I would not call it "HIDDEN" or "HONEYPOT" ;-)

Edit Template

A quickform template can be modified directly inside the backend via the "Modify Template" button or with a editor of your choice on the server.

It is not recommended to update any templates having a name starting with "qf_" !

Templates having names starting with "qf_" are part of the quickform module package
and might be overwritten with future quickform module updates
or upcoming LEPTON releases.

Within the backend functionality to modify a template, any updates of quickform own templates are not possible. However you can save them inside the template editor with your own name (not starting with "qf_" !

Field names

All relevant field names should be start with "qf_".
Only such fields appear in the mail.

Required fields

Requirement checks can be done directly inside the template using tag required="required". However, it is highly recommended that required checks are also done at server side due to injections. Due to, required fields have to be named specially starting with "qf_r_".

< input name="qf_r_email" id="email" required="required" value="{{ EMAIL }}" />

Note that it might be very helpfull towards frontend user to indicate, that a field is required. For example with a * like

< label >E-Mail < span class="required" >*< /span >< /label >

Values

In case of server side validation fails, the form is populated again with all values entered so far. The value is provided within a TWIG variable, named with the input field name in uppercase, without "qf_" and "r_" elements.

A field named "qf_r_email" gets therefore the value in variable {{ EMAIL }}.

data-label & data-value

Sometimes it is helpfull to show a different label or value in form than in mail. When defining a data-label and/or a data-value tag in an input field, this label and/or value is used in the mail instead.

Think about mobile devices

When defining a template, think also about mobile devices and the support for different mobile keyboards depending on the needed input value. Like tel, email, numbers or text. Search the web for "html form inputmode" for details.

Honeypot

To use honeypot in your template, please check chapter Spam Settings above.

Captcha

To use captchas, enable them in admintools/captcha & advanced spam protection first.

Add something like the following code into your template before submit button and you are done:

< div class="{{ CAPTCHA_CLASS }} full" >
	< label for="captcha">Spam protection < span class="required" >*< /span >
		< div class="grouping {{ CAPTCHA_ERROR }}" >
			{{ CAPTCHA }}
		< /div >
	< /label >
< /div >

Google captcha

If you want to add Google Recaptcha spam protection please read the documentation.

Further spam protection

For further spam protection possibilities please check chapter Spam Check Settings above.

Error class

In case of required value fails at server side validation, a TWIG variable is available, named with the input field name in uppercase, without "qf_" and "r_" elements, extended with "_ERROR".

A field named "qf_r_email" gets therefore the error in variable {{ EMAIL_ERROR }} with value "missing".

In case of no errors, the error variable is either not available or empty.

Such missing errors are handled in the quickform default frontend.css with

.quickform .missing {
	border: 1px solid #ff4136 !important;
}

Email Copy to requestor

With form submit, a mail is send to the email address defined in the quickform settings, see above.

In order to send also a mail to form requestor, you need to define a dedicated input field named "qf_cc_mail" or "qf_r_cc_mail", in addition to an requestor email input field, named "qf_email" or "qf_r_email". When email field is not available or empty, no mail is send to form requestor.

This cc_mail input field can be a hidden or checkbox field, with any value except empty and "-".

See following chapter about the possible mail body handling.

Emails

Email to quickform admin

When a quickform form is submitted in frontend, a mail is send to the email address specified in the quickform settings.

The mail template used must be located in the modules/quickform/templates/backend folder.
The first one found in list below is used:

email_(page_language.lte (e.g. email_de.lte)
email_(default language).lte (e.g. email_en.lte)
email.lte
qf_email.lte

The above specified sequence allows you to define your own and language specific email.

Note that the mail template "qf_email.lte" is part of the quickform module packaage and might be overwritten with future releases.

Please note also that email templates can only be modified directly on the server, not via backend.

Email to quickform requestor

In case the quickform form contains the email and the cc_mail field (see above in chapter Edit Template) exist and contains a valid value, an email could also be send to the defined email address in the form.

The mail template used must be located in the modules/quickform/templates/backend folder.
The first one found in list below is used:

cc_mail_(page_language.lte (e.g. cc_mail_de.lte)
cc_mail_(default language).lte (e.g. cc_mail_en.lte)
cc_mail.lte
email_(page_language.lte (e.g. email_de.lte)
email_(default language).lte (e.g. email_en.lte)
email.lte
qf_email.lte

The above specified sequence allows you to define your own and language specific email with either same or different customer related mail content

Note that the mail template "qf_email.lte" is part of the quickform module packaage and might be overwritten with future releases.

Please note also that email templates can only be modified directly on the server, not via backend.

Rules for creating your own email template

When creating your own email template(s), please follow the rules listed below, as otherwise a proper display in backend list (mainly table view) can not be guaranteed:

The field values are loaded in dynamically depending on the quickform form template you use. When hardcoding the single fields yourself, the responability for loosing new fields in case of template changes is by yourself
Each field - value pair has to be in its own table rowfield label :field value
There should be only 2 columns per field value row
The complete list of field value pairs have to be wrapped by atag having id 'emailcontent'
All the involved tags in this mandatory part can have additional attributes or styles
The param names for LABEL and VALUE can be adapted

The mandatory minimum therefore is:

< table id="emailcontent" >
  {% for LABEL,VALUE in field_values %}
    < tr >< td >{{ LABEL }}:< /td >< td >{{ VALUE }}< /td >
  {% endfor %}
< /table >

File upload in Quickform

Starting with Quickform v2, file upload is no longer supported.

In case File upload is required, please migrate to module mpform.

Custom Frontend Class

Intro

The Custom Frontend Class allows website admin to extend the frontend functionality of quickform module.

Please note that this file will not be delivered with the quickform module package
and due also not overwritten in future releases.

Class file name & content

Create a file named "quickform_custom_frontend.php" in folder "modules/quickform/classes" with a content like:

class quickform_custom_frontend {
	public $qfcfe_data = array();
	public static $instance;

	/**
	 *  Return the instance of this class.
	 *
	 */
	public static function getInstance()
	{
		if (null === static::$instance)
		{
			static::$instance = new static();
			static::$instance->initialize();
		}
		return static::$instance;
	}

	/**
	 *  set the data during initialization
	 *  unchanged for historical reasons. qfcfe_data can be used in the templates
	 */
	public function initialize ()
	{
		$this->qfcfe_data = array( 'field1' => 'value1', 'field2' => 'value12 );
	} // end function

	/**
	 *  set the data on show request
	 *
	 * @param	array		array with template field info, see documentation
	 * @param	array	&	array with form field values, field name = field value
	 * @return	int		0/False = an error occured
	 *				1/True  = success
	 */
	public function set_page_values( $template_fields, &$page_values )
	{
		$page_values[ 'NAME'] = "HUGO";
		return True;
	} // end function
} //end class

Use in frontend quickform template

All data variables set in the quickform custom frontend class can be used in the quickform template either with (when use within initialization)

{{ oQCFE.qfcfe_data.field1 }}

where as "field1" stands as an example for the field in the return value array.

Or when setting data values in function "set_page_values" simply with

{{ NAME }}"

It is also possible to use both data settings in parallel, depending on your requirements.

The function "set_page_values" is supported with Quickform v2 onwards, whereas the data setting during initialization exists also in earlier versions.

Extend Quickform custom frontend class with data validation

The quickform custom frontend class can also be extended with a custom specific data validation, which occur after form has been submitted and basic checks has been made (required fields, honeypot check).

To use the custom specific validation, add following function into your quickform custom frontend class and adapt to your needs:

 	/**
	 *  validate the data
	 *
	 * @param	array		array with template field info, see documentation
	 * @param	array	&	array with form field values, field name = field value
	 * @return	int		0/False = an error occured
	 *				1/True  = success
	 *				<0 = a valid page id (multiplied by -1) to go to
	 */
	public function validate( $template_fields, &$page_values )
	{
		if ( array_key_exists( "NAME", $page_values ))
		{
			if ( $page_values[ 'NAME'] <> "HUGO" )
			{
				// format the error message box
				$page_values["MESSAGE_CLASS"]	= "error";
				// the error text shown in the error message box
				$page_values["STATUSMESSAGE"]	= "First name must be HUGO";
				// set a dedicated class on the field having the error
				// Syntax: fieldname in uppercase + "_ERROR"
				$page_values["NAME_ERROR"]	= "missing";
				// return as an error
				return False;
			}
		}
		return True;
	} // end function

Extend Quickform custom frontend class with data settings for mail template

Incase you want to use your own mail template (see previous chapter), and the default values

field_values ( a label => value pair of all frontend template fields)
settings (the quickform settings)
MOD_QUICKFORM (the default translations)

does not fit your wishes, you can enhance the template values list by adding the ollowing function into your quickform custom frontend class and adapt to your needs:

/**
* load additional values to the mail template
*
* @param	array		array with template field info, see documentation
* @param	array	&	array with form field values, field name = field value
* @return	none
*/
public function set_mail_values( $template_fields, &$template_values )
{
	$template_values[ 'NAME'] = "HUGO";
	 return;
} // end function

$template_fields

The $template_fields array is set in function get_template_fields in quickform class.

Depending on the form field setup, the array contain 1 subarray per form field, having the fieldname as the subarray key.
Each subarray contain the following key=>value pairs:

key	value	example
name	the full form field name	qf_r_firstname
id	the stripped/cleaned form field name in uppercase	FIRSTNAME
submit	contain true if form field name starts with "qf_", false otherwise	True
required	contain true if field is defined as required by having a form field name starting with "qf_r_", false otherwise	True
value	the form field value set in the template, if available	""
type	the form field type if detectable	TEXT
data-label	the value of the tag data-label if tag is available. Otherwise same content as in id. Used in mails only	First Name
data-value	the value of the tag "data-value" if tag is available. Used in mails only instead of the "value" value	./.

doc Quickform

Table of content

Quickform Intro

Quickform in action

Quickform settings

Selection of the frontend form:

Email receiver:

Email subject:

Success page:

Quickform buttons

Spam Check Settings

Modul Info

Help

Modify Template

Inbox | additional own defined groups

X

10 | 25 | 50 | 75 | 100

Mail view | Table view

Delete all messages shown / Delete this message

Move all messages shown / Move this message

Show/hide all messages sent / Show/hide message sent

Spam Check Settings

Idea of Honeypots

Settings

Use Honeypot functionality

Spam logging in TEMP table in the database

Minimum number of seconds (0 - 60) for form data entry

HoneyPot field / comma separated field list

Action on error

Use Honeypot in template

Edit Template

Field names

Required fields

Values

data-label & data-value

Think about mobile devices

Honeypot

Captcha

Google captcha

Further spam protection

Error class

Email Copy to requestor

Emails

Email to quickform admin

Email to quickform requestor

Rules for creating your own email template

File upload in Quickform

Custom Frontend Class

Intro

Class file name & content

Use in frontend quickform template

Extend Quickform custom frontend class with data validation

Extend Quickform custom frontend class with data settings for mail template

$template_fields