heimrichhannot/contao-formhybrid

Contains functionality for handling form submissions in the contao frontend.

Tuesday, July 3, 2018
by digitales@heimrich-hannot.de
Repository
5 Watchers
1 Stars
3,504 Installations

PHP
13 Dependents
1 Suggesters
0 Forks
2 Open issues
100 Versions
16 % Grown

The README.md

Formhybrid

Contains functionality for handling form submissions in the contao frontend., _(*1)

Usage is simple: Include the default palette (_FORMHYBRID_PALETTE_DEFAULT_) in config.php into your module's tl_module file and remove the fields you don't need for your module., _(*2)

-> Click here for a diagram visualizing the interaction between the modules formhybrid, formhybrid_list, frontendedit and submissions., _(*3)

Features

form validation
transforming of special field's values depending on their dca properties (e.g. date)
ajax handling
store submissions using submissions module if necessary
optIn entity activation and notification handling
optOut entity handling

Usage

Install

With composer and Contao 4 Managed Edition:, _(*4)

composer require heimrichhannot/contao-formhybrid ~2.8

Palette handling

permanentFields must be declared within editableFields in order to get right field position
a field declared in editableFields whose selector isnt active or is not part of editable fields itself is removed from the final field set
fields from active selectors that are not within editableFields are removed from final fields

Inserttags

{{form::FIELDNAME}} returns the formatted value from the field (select value instead of key)
{{form_value::FIELDNAME}} returns the value of the field
{{form_submission::FIELDNAME}} returns "field-label : formated field value"
{{if}}
{{elseif}}
{{else}}
{{endif}}

Developers

Notification center tokens

Formhybrid is notification center ready. It is possible to send 2 E-Mails on Form Submission to the sender (confirmation notification) and one to receiver (submission notification). The following tokens are provided for usage:, _(*5)

Tag	Example	Description
##formsubmission_all##	Firstname: Max\	Contains the complete submission (contains also hidden form values like tstamp) formated as label and value.
Lastname: Mustermann\
Zeitstempel: 1458030977
##formsubmission##	Firstname: Max\	Contains the complete submission (without hidden fields) formatted as label and value.
Lastname: Mustermann
##form_submission_*##	##form_submission_country## -> Country: Germany	Contains the submission of a single field formatted as label and value (value takes options into consideration and return its corresponding value).
##form_value_*##	##form_value_country## -> de	Contains submitted value of a field (no value is transformed by its reference).
##form_plain_*##	Input:

Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas., _(*6)

\ | Strips html entities from the submitted value (helpful for plain text e-mails and tinymce textareas) | | | Output: -> ##form_value_text## -> Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. | | | ##form_*## | ##form_county## -> Germany | Contains the formatted value of the submission (value takes options into consideration and return its corresponding value). | | ##opt_in_token## | ##opt_in_token## -> [TOKEN] / Generates only the opt-in the token. | ##opt_in_link## | ##opt_in_link## -> http://mywebsite.com/linkto-form?token=[TOKEN] | Generates the opt-in activation link., _(*7)

Config Callbacks

Type	Description
onload_callback	Add a 3rd parameter with boolean true to your onload_callbacks to run through them in frontend mode.

Additional eval dca config parameters

Key | Default | Example | Description , _(*8)

allowedTags \| null \|

<, _(*9)

p> | Allow specific html tags inside input that will not be escaped (allowHtml must be true). allowHtml will be true by default if preserveTags, rte is set true within eval config., _(*10)

Frontend Form

We recommend to use Contao Frontendedit. If you can't or need more advanced options:, _(*11)

Create a module and add all palette fields you want (see config.php FORMHYBRID_PALETTE_DEFAULT and tl_module.php)
add following code to your module::compile() method to render the form

use HeimrichHannot\FormHybrid\Form;

[...]
    $objForm = new Form($this);
    $this->Template->form = $objForm->generate();
[...]

More advanced configurations can be archived by extending the Form class and overwrite methods. Following methods are availiable to overwrite (no complete list, see Form and DC_Hybrid classes):, _(*12)

Method	Description
abstract void compile()	Called before rendering the form. Must be implementet.
void onSubmitCallback(\DataContainer $dc)	Called after submitting the form, before writing to the database and sending confirmations).
void onUpdateCallback($objItem, \DataContainer $objDc, $blnJustCreated, $arrOriginalRow = null)	Called after submit, if data record already exist.
void afterSubmitCallback(\DataContainer $dc)	Called after submitting the form and after saving enitity and sending confirmations.
void afterActivationCallback(\DataContainer $dc)	Called after successful opt in.
void afterUnsubscribeCallback(\DataContainer $dc)	Called after successful opt out.
bool sendOptInNotification(\NotificationCenter\Model\Message $objMessage, $arrSubmissionData, $arrToken)	Default: true
bool sendSubmissionNotification(\NotificationCenter\Model\Message $objMessage, &$arrSubmissionData, &$arrToken)	Default: true
bool sendSubmissionEmail($objEmail, &$arrRecipient, &$arrSubmissionData)	Default: true
void onSendSubmissionEmailCallback($objEmail, $arrRecipient, $arrSubmissionData)	Called in sendSubmissionEmail()
bool sendConfirmationNotification(\NotificationCenter\Model\Message $objMessage, &$arrSubmissionData, &$arrToken)	Default: true
bool sendConfirmationEmail($objEmail, &$arrRecipient, &$arrSubmissionData)	Default: true

Hooks

Name	Parameter	Description
formhybridBeforeCreateNotifications	array &$submissionData, Form $currentForm	Do custom logic before sending notification. You can manipulate the submission data or send custom notifications.
formhybridOnCreateInstance	Form $form, $varConfig = null, $id = 0	Is called in the form constructor and allows to change configs or do actions on every form init.
formhybridBeforeCreateWidget	FormhybridBeforeCreateWidgetEvent $event	Is called before widget class constructor is called. You can change widget config and widget class in the event class.
formhybridBeforeRenderForm	FormhybridBeforeRenderFormEvent $event	Is called before the form template is rendered and can be used to modify data or work with the data before rendering.
formhybridModifyAsyncFormSubmitResponse	FormhybridModifyAsyncFormSubmitResponseEvent $event	Modify the response data before returning the form ajax response.

JavaScript Events

Event	Descripiton
formhybrid_ajax_complete	Dispatched after successful async form submit
formhybridToggleSubpaletteComplete	Dispatched after subpalette toggled

Opt in handling

FormHybrid comes with build in opt-in handling. Following steps are required to use it: * add formHybridAddOptIn to your modules palette * add \HeimrichHannot\FormHybrid\FormHybrid::addOptInFieldToTable([TABLE_NAME]) at the end of your entity dca file and update your database * create an opt in notification in notification center and provide ##opt_in_link## inside text or html, _(*13)

Opt out handling

FormHybrid comes with build in opt-out handling. After calling the opt-out link the entity will be deleted. Following steps are required to use it: * add formHybridAddOptOut to your modules palette and activate it in module configuration * add \HeimrichHannot\FormHybrid\FormHybrid::addOptOutFieldToTable([TABLE_NAME]) at the end of your entity dca file and update your database * call HeimrichHannot\FormHybrid\TokenGenerator in your notification generation code with the opt-out-token from the database, to generate the opt-out-email-token and -url. * add opt_out_token and opt_out_link to your notification center tokens and call them in your messages, _(*14)

Attention: If you enhance already existing data with opt-out-handling, tokens are not automatically generated for existing entries and unsubscription is not possible for existing entries! You need to check if the entry already has an token in your code, before generating opt-out link! Example:, _(*15)

if ($module->formHybridAddOptOut && !$recipientsModel->optOutToken)
{
    $recipientsModel->optOutToken = Form::generateUniqueToken();
    $recipientsModel->save();
}

Dublicate entity flag

Set Form::isDuplicateEntityError to true, to stop before saving and throw error message., _(*16)

Customization

Add custom submit label

Add your label to $GLOBALS['TL_LANG']['MSC']['formhybrid']['submitLabels']., _(*17)

The Versions

03/07 2018

dev-master

9999999-dev https://github.com/heimrichhannot/contao-formhybrid

Contains functionality for handling form submissions in the contao frontend.

contao-module contao-formhybrid

Contains functionality for handling form submissions in the contao frontend.

heimrichhannot/contao-formhybrid

The README.md

Formhybrid

Features

Usage

Install

Palette handling

Inserttags

Developers

Notification center tokens

Config Callbacks

Additional eval dca config parameters

Frontend Form

Hooks

JavaScript Events

Opt in handling

Opt out handling

Dublicate entity flag

Customization

Add custom submit label

The Versions

dev-master

The Requires

by Heimrich & Hannot

3.2.2

The Requires

by Heimrich & Hannot

3.2.1

The Requires

by Heimrich & Hannot

3.2.0

The Requires

by Heimrich & Hannot

3.1.0

The Requires

by Heimrich & Hannot

3.0.6

The Requires

by Heimrich & Hannot

3.0.5

The Requires

by Heimrich & Hannot

3.0.4

The Requires

by Heimrich & Hannot

3.0.3

The Requires

by Heimrich & Hannot

v2.x-dev

The Requires

by Heimrich & Hannot

2.10.10

The Requires

by Heimrich & Hannot

2.10.9

The Requires

by Heimrich & Hannot

3.0.2

The Requires

by Heimrich & Hannot

3.0.1

The Requires

by Heimrich & Hannot

3.0.0

The Requires

by Heimrich & Hannot

2.10.8

The Requires

by Heimrich & Hannot

2.10.7

The Requires

by Heimrich & Hannot

2.10.6

The Requires

by Heimrich & Hannot

2.10.5

The Requires

by Heimrich & Hannot