PHPackages heimrichhannot/contao-formhybrid - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. heimrichhannot/contao-formhybrid ActiveContao-module[Utility & Helpers](/categories/utility) heimrichhannot/contao-formhybrid ================================ Contains functionality for handling form submissions in the contao frontend. 3.26.0(2mo ago)210.6k16LGPL-3.0-or-laterPHPPHP ^8.1CI failing Since Feb 5Pushed 2mo ago5 watchersCompare [ Source](https://github.com/heimrichhannot/contao-formhybrid)[ Packagist](https://packagist.org/packages/heimrichhannot/contao-formhybrid)[ Docs](https://github.com/heimrichhannot/contao-formhybrid)[ RSS](/packages/heimrichhannot-contao-formhybrid/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (22)Versions (395)Used By (16) Formhybrid ========== [](#formhybrid) 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](docs/formhybrid.png) for a diagram visualizing the interaction between the modules [formhybrid](https://github.com/heimrichhannot/contao-formhybrid), [formhybrid\_list](https://github.com/heimrichhannot/contao-formhybrid_list), [frontendedit](https://github.com/heimrichhannot/contao-frontendedit) and [submissions](https://github.com/heimrichhannot/contao-submissions). Features -------- [](#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 ----- [](#usage) ### Install [](#install) With composer and Contao 4 Managed Edition: ``` composer require heimrichhannot/contao-formhybrid ~2.8 ``` ### Palette handling [](#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 [](#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 ---------- [](#developers) ### Notification center tokens [](#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: TagExampleDescription\##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: GermanyContains 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## -> deContains 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. \\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## -> GermanyContains 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\]](http://mywebsite.com/linkto-form?token=%5BTOKEN%5D)Generates the opt-in activation link.### Config Callbacks [](#config-callbacks) TypeDescriptiononload\_callbackAdd a 3rd parameter with boolean true to your onload\_callbacks to run through them in frontend mode.### Additional eval dca config parameters [](#additional-eval-dca-config-parameters) KeyDefaultExampleDescriptionallowedTagsnull 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.### Frontend Form [](#frontend-form) We recommend to use [Contao Frontendedit](https://github.com/heimrichhannot/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): MethodDescriptionabstract 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: truebool sendSubmissionNotification(\\NotificationCenter\\Model\\Message $objMessage, &$arrSubmissionData, &$arrToken)Default: truebool sendSubmissionEmail($objEmail, &$arrRecipient, &$arrSubmissionData)Default: truevoid onSendSubmissionEmailCallback($objEmail, $arrRecipient, $arrSubmissionData)Called in sendSubmissionEmail()bool sendConfirmationNotification(\\NotificationCenter\\Model\\Message $objMessage, &$arrSubmissionData, &$arrToken)Default: truebool sendConfirmationEmail($objEmail, &$arrRecipient, &$arrSubmissionData)Default: true### Hooks [](#hooks) NameParameterDescriptionformhybridBeforeCreateNotificationsarray &$submissionData, Form $currentFormDo custom logic before sending notification. You can manipulate the submission data or send custom notifications.formhybridOnCreateInstanceForm $form, $varConfig = null, $id = 0Is called in the form constructor and allows to change configs or do actions on every form init.formhybridBeforeCreateWidgetFormhybridBeforeCreateWidgetEvent $eventIs called before widget class constructor is called. You can change widget config and widget class in the event class.formhybridBeforeRenderFormFormhybridBeforeRenderFormEvent $eventIs called before the form template is rendered and can be used to modify data or work with the data before rendering.formhybridModifyAsyncFormSubmitResponseFormhybridModifyAsyncFormSubmitResponseEvent $eventModify the response data before returning the form ajax response.### JavaScript Events [](#javascript-events) EventDescripitonformhybrid\_ajax\_completeDispatched after successful async form submitformhybridToggleSubpaletteCompleteDispatched after subpalette toggled### Opt in handling [](#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 [](#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 [](#dublicate-entity-flag) Set `Form::isDuplicateEntityError` to true, to stop before saving and throw error message. Customization ------------- [](#customization) ### Add custom submit label [](#add-custom-submit-label) Add your label to `$GLOBALS['TL_LANG']['MSC']['formhybrid']['submitLabels']`. ### Health Score 60 — FairBetter than 99% of packages Maintenance86 Actively maintained with recent releases Popularity26 Limited adoption so far Community25 Small or concentrated contributor base Maturity91 Battle-tested with a long release history Bus Factor1 Top contributor holds 62.1% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~10 days Recently: every ~269 days Total 394 Last Release 70d ago Major Versions 1.1.16 → 2.0.02015-08-10 2.10.8 → 3.0.02018-02-06 2.10.10 → 3.0.32018-03-02 v2.x-dev → 3.4.02018-09-19 PHP version history (6 changes)2.5.25PHP >=5.4.0, <7 2.8.0PHP ~5.4 || ~7.0 3.15.0PHP ~5.6 || ~7.0 3.20.0PHP ~5.6 || ~7.0 || ^8.0 3.23.0PHP ^7.0 || ^8.0 3.26.0PHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/28ad3224d8727b622ebd229840eea6b9dbcb83eb0bd609e6ce65b614830ff538?d=identicon)[digitales@heimrich-hannot.de](/maintainers/digitales@heimrich-hannot.de) --- Top Contributors [![koertho](https://avatars.githubusercontent.com/u/12064642?v=4)](https://github.com/koertho "koertho (59 commits)")[![nafetagrats](https://avatars.githubusercontent.com/u/5796948?v=4)](https://github.com/nafetagrats "nafetagrats (18 commits)")[![Defcon0](https://avatars.githubusercontent.com/u/1485098?v=4)](https://github.com/Defcon0 "Defcon0 (10 commits)")[![vvohh](https://avatars.githubusercontent.com/u/75325799?v=4)](https://github.com/vvohh "vvohh (2 commits)")[![maku05](https://avatars.githubusercontent.com/u/10884265?v=4)](https://github.com/maku05 "maku05 (2 commits)")[![ericges](https://avatars.githubusercontent.com/u/25957923?v=4)](https://github.com/ericges "ericges (2 commits)")[![matzke](https://avatars.githubusercontent.com/u/192946?v=4)](https://github.com/matzke "matzke (2 commits)") --- Tags modulecontaoformdeveloper ### Embed Badge ![Health badge](/badges/heimrichhannot-contao-formhybrid/health.svg) ``` [![Health](https://phpackages.com/badges/heimrichhannot-contao-formhybrid/health.svg)](https://phpackages.com/packages/heimrichhannot-contao-formhybrid) ``` ### Alternatives [inspiredminds/contao-fieldset-duplication Contao extension to allow the duplication of form fieldsets in the front end by the user for additional input fields. 158.2k1](/packages/inspiredminds-contao-fieldset-duplication) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)