{"id":20961881,"url":"https://github.com/heimrichhannot/contao-formhybrid","last_synced_at":"2026-03-02T16:01:29.807Z","repository":{"id":26887227,"uuid":"30348174","full_name":"heimrichhannot/contao-formhybrid","owner":"heimrichhannot","description":"A form helper module for contao. Makes form creation for module developer a bit easier and reusable.","archived":false,"fork":false,"pushed_at":"2024-12-04T12:02:10.000Z","size":1012,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-05-17T19:48:29.639Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heimrichhannot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-05T09:44:32.000Z","updated_at":"2024-12-04T12:02:06.000Z","dependencies_parsed_at":"2024-05-27T11:36:51.446Z","dependency_job_id":null,"html_url":"https://github.com/heimrichhannot/contao-formhybrid","commit_stats":{"total_commits":472,"total_committers":13,"mean_commits":36.30769230769231,"dds":0.5932203389830508,"last_synced_commit":"8edb3498ac039006b8980c96f9603dfb7fbccecb"},"previous_names":[],"tags_count":393,"template":false,"template_full_name":null,"purl":"pkg:github/heimrichhannot/contao-formhybrid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-formhybrid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-formhybrid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-formhybrid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-formhybrid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heimrichhannot","download_url":"https://codeload.github.com/heimrichhannot/contao-formhybrid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heimrichhannot%2Fcontao-formhybrid/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260730213,"owners_count":23053632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T02:18:06.236Z","updated_at":"2026-03-02T16:01:29.664Z","avatar_url":"https://github.com/heimrichhannot.png","language":"PHP","readme":"# Formhybrid\n\nContains functionality for handling form submissions in the contao frontend.\n\nUsage 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.\n\n-\u003e 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).\n\n## Features\n\n- form validation\n- transforming of special field's values depending on their dca properties (e.g. date)\n- ajax handling\n- store submissions using submissions module if necessary\n- optIn entity activation and notification handling\n- optOut entity handling\n\n## Usage\n\n### Install\n\nWith composer and Contao 4 Managed Edition: \n\n```\ncomposer require heimrichhannot/contao-formhybrid ~2.8\n```\n\n### Palette handling\n- permanentFields must be declared within editableFields in order to get right field position\n- a field declared in editableFields whose selector isnt active or is not part of editable fields itself is removed from the final field set\n- fields from active selectors that are not within editableFields are removed from final fields\n\n### Inserttags\n\n- {{form::FIELDNAME}} returns the formatted value from the field (select value instead of key)\n- {{form_value::FIELDNAME}} returns the value of the field\n- {{form_submission::FIELDNAME}} returns \"field-label : formated field value\"\n- {{if}}\n- {{elseif}}\n- {{else}}\n- {{endif}}\n\n## Developers\n\n### Notification center tokens\n\nFormhybrid 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).\nThe following tokens are provided for usage:\n\n| Tag   |      Example      |  Description |\n|----------|:-------------:|------:|\n| ##formsubmission_all## \t|  Firstname: Max\\ | Contains the complete submission (contains also hidden form values like tstamp) formated as label and value.  |\n|       \t\t\t\t\t\t\t\t\t|  Lastname: Mustermann\\ | |\n|       \t\t\t\t\t\t\t\t\t|  Zeitstempel: 1458030977 | |\n| ##formsubmission## |  Firstname: Max\\ | Contains the complete submission (without hidden fields) formatted as label and value.  |\n|                    |  Lastname: Mustermann | |\n| ##form_submission_*## | ##form_submission_country## -\u003e Country: Germany | Contains the submission of a single field formatted as label and value (value takes options into consideration and return its corresponding value). |\n| ##form_value_*## | ##form_value_country## -\u003e de  | Contains submitted value of a field (no value is transformed by its  reference). |\n| ##form_plain_*## | Input: \u003cp\u003ePellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.\u003c/p\u003e \\ | Strips html entities from the submitted value (helpful for plain text e-mails and tinymce textareas) |\n|       \t\t\t\t\t | Output: -\u003e ##form_value_text## -\u003e Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. | |\n| ##form_*## | ##form_county## -\u003e Germany | Contains the formatted value of the submission  (value takes options into consideration and return its corresponding value). |\n| ##opt_in_token## | ##opt_in_token## -\u003e [TOKEN] / Generates only the opt-in the token. \n| ##opt_in_link## | ##opt_in_link## -\u003e http://mywebsite.com/linkto-form?token=[TOKEN] | Generates the opt-in activation link.\n\n\n\n### Config Callbacks\n\nType | Description\n---- | -----------\nonload_callback | Add a 3rd parameter with boolean true to your onload_callbacks to run through them in frontend mode.  \n\n\n### Additional eval dca config parameters\n\n\nKey          | Default | Example | Description\n|------------|:-------------:|:-------------:|------:|\n|allowedTags | null | \u003cbr\u003e\u003cspan\u003e\u003cp\u003e | 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.\n\n### Frontend Form\nWe recommend to use [Contao Frontendedit](https://github.com/heimrichhannot/contao-frontendedit). If you can't or need more advanced options:\n\n* Create a module and add all palette fields you want (see config.php FORMHYBRID_PALETTE_DEFAULT and tl_module.php)\n* add following code to your module::compile() method to render the form \n\n```\nuse HeimrichHannot\\FormHybrid\\Form;\n\n[...]\n    $objForm = new Form($this);\n    $this-\u003eTemplate-\u003eform = $objForm-\u003egenerate();\n[...]\n```\n\nMore advanced configurations can be archived by extending the Form class and overwrite methods.\nFollowing methods are availiable to overwrite (no complete list, see Form and DC_Hybrid classes):\n\n|Method                                     |Description|\n|-------------------------------------------|-----------|\n|abstract void compile()                         |Called before rendering the form. Must be implementet.|\n|void onSubmitCallback(\\DataContainer $dc)       |Called after submitting the form, before writing to the database and sending confirmations).|\n|void onUpdateCallback($objItem, \\DataContainer $objDc, $blnJustCreated, $arrOriginalRow = null)|Called after submit, if data record already exist.|\n|void afterSubmitCallback(\\DataContainer $dc)    |Called after submitting the form and after saving enitity and sending confirmations.|\n|void afterActivationCallback(\\DataContainer $dc)|Called after successful opt in.|\n|void afterUnsubscribeCallback(\\DataContainer $dc)|Called after successful opt out.|\n|bool sendOptInNotification(\\NotificationCenter\\Model\\Message $objMessage, $arrSubmissionData, $arrToken)|Default: true|\n|bool sendSubmissionNotification(\\NotificationCenter\\Model\\Message $objMessage, \u0026$arrSubmissionData, \u0026$arrToken)|Default: true|\n|bool sendSubmissionEmail($objEmail, \u0026$arrRecipient, \u0026$arrSubmissionData) |Default: true|\n|void onSendSubmissionEmailCallback($objEmail, $arrRecipient, $arrSubmissionData)|Called in sendSubmissionEmail()|\n|bool sendConfirmationNotification(\\NotificationCenter\\Model\\Message $objMessage, \u0026$arrSubmissionData, \u0026$arrToken)|Default: true|\n|bool sendConfirmationEmail($objEmail, \u0026$arrRecipient, \u0026$arrSubmissionData)|Default: true|\n\n### Hooks\n\nName | Parameter | Description\n---- | --------- | -----------\nformhybridBeforeCreateNotifications | array \u0026$submissionData, Form $currentForm | Do custom logic before sending notification. You can manipulate the submission data or send custom notifications.\nformhybridOnCreateInstance | Form $form, $varConfig = null, $id = 0 | Is called in the form constructor and allows to change configs or do actions on every form init.\nformhybridBeforeCreateWidget | FormhybridBeforeCreateWidgetEvent $event | Is called before widget class constructor is called. You can change widget config and widget class in the event class.\nformhybridBeforeRenderForm | FormhybridBeforeRenderFormEvent $event | Is called before the form template is rendered and can be used to modify data or work with the data before rendering.\nformhybridModifyAsyncFormSubmitResponse | FormhybridModifyAsyncFormSubmitResponseEvent $event | Modify the response data before returning the form ajax response.\n\n### JavaScript Events\n\nEvent | Descripiton\n----- | -----------\nformhybrid_ajax_complete | Dispatched after successful async form submit\nformhybridToggleSubpaletteComplete | Dispatched after subpalette toggled\n\n### Opt in handling\nFormHybrid comes with build in opt-in handling. Following steps are required to use it: \n* add `formHybridAddOptIn` to your modules palette\n* add `\\HeimrichHannot\\FormHybrid\\FormHybrid::addOptInFieldToTable([TABLE_NAME])` at the end of your entity dca file and update your database\n* create an opt in notification in notification center and provide `##opt_in_link##` inside text or html\n \n### Opt out handling ###\nFormHybrid 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:\n* add `formHybridAddOptOut` to your modules palette and activate it in module configuration\n* add `\\HeimrichHannot\\FormHybrid\\FormHybrid::addOptOutFieldToTable([TABLE_NAME])` at the end of your entity dca file and update your database\n* 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.\n* add `opt_out_token` and `opt_out_link` to your notification center tokens and call them in your messages\n\n\u003e 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:\n\n```php\nif ($module-\u003eformHybridAddOptOut \u0026\u0026 !$recipientsModel-\u003eoptOutToken)\n{\n    $recipientsModel-\u003eoptOutToken = Form::generateUniqueToken();\n    $recipientsModel-\u003esave();\n}\n```\n\n### Dublicate entity flag\n\nSet `Form::isDuplicateEntityError` to true, to stop before saving and throw error message.\n\n## Customization\n\n### Add custom submit label\n\nAdd your label to `$GLOBALS['TL_LANG']['MSC']['formhybrid']['submitLabels']`.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheimrichhannot%2Fcontao-formhybrid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheimrichhannot%2Fcontao-formhybrid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheimrichhannot%2Fcontao-formhybrid/lists"}