README

Contains functionality for handling form submissions in the contao frontend.

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.

-> Click here for a diagram visualizing the interaction between the modules formhybrid, formhybrid_list, frontendedit and submissions.

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:

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:

Config Callbacks

Additional eval dca config parameters

Frontend Form

We recommend to use Contao Frontendedit. If you can't or need more advanced options:

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):

Hooks

JavaScript Events

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

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

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:

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.

Customization

Add custom submit label

Add your label to $GLOBALS['TL_LANG']['MSC']['formhybrid']['submitLabels'].

heimrichhannot / contao-formhybrid

Maintainers

Details