Plugin development with Visforms custom plugin events
Individual business logic
In the past, feature requests were repeatedly brought to us that stemmed from the need for a very individual business logic. Examples of this are defining individual submit handlers or specific actions on the form data that are to be carried out after the form has been successfully submitted. Or the immediate export of the data to a continuously updated server-side text file in order to connect third-party systems. Unfortunately, it makes no sense to implement such individual features directly in the core of Visforms.
Extensive event system
With Visforms Version 3.2.0 we have introduced a comprehensive event system that accompanies all important process steps in the form lifetime and data processing. Since then, it has been possible to extend the Visforms core with any custom plugins that can implement such individual features. Another advantage is that these individually developed plugins are not overwritten by updates to the Visforms core.
Note: If you need such an individual feature but are not able to implement it yourself, we would be happy to develop an individual Visforms custom plugin for you. We'd love to create an offer for you. Just send us a description of the desired functionality.
Event list
- onVisformsBeforeHtmlPrepare
- onVisformsAfterHtmlPrepare
- onVisformsAfterCustomtextPrepare
- onVisformsFormPrepare
- onVisformsEditFormPrepare
- onVisformsBeforeFormSave
- onVisformsAfterFormSave
- onVisformsEmailPrepare
- onVisformsBeforeSuccessAction
- onVisfieldBeforeCreate
onVisformsBeforeHtmlPrepare
The HTML code, which represents a complete form field with all formatting, is generated entirely in the Visforms code. It is passed to the form view as a final, ready-made HTML string. The exact structure of the HTML code depends on
- the field type,
- the parameters set in the field definition and
- the selected form layout.
The onVisformsBeforeHtmlPrepare event can be used to change field parameters just before starting to create the final HTML code.
Parameter:
- String $context: com_visforms.field
- Object $field: reference to the field object
- String $layout: visforms, btdefault, bthorizontal or multicolumn
onVisformsAfterHtmlPrepare
The onVisformsAfterHtmlPrepare event is triggered after the HTML code is generated and before it is passed to the form view. It can be used to post-process the final finished HTML string.
Parameter:
- String $context: com_visforms.field
- Object $field: reference to the field object
- String $html: Reference to the HTML string
- String $layout: visforms, btdefault, bthorizontal or multicolumn
onVisformsAfterCustomtextPrepare
The onVisformsAfterCustomtextPrepare event is triggered after the HTML code for the “custom text” has been generated. It can be used to post-process the final finished HTML string.
Parameter:
- String $context: com_visforms.field
- String $html: Reference to the HTML string
- String $layout: visforms, btdefault, bthorizontal or multicolumn
onVisformsFormPrepare
The onVisformsFormPrepare event is triggered in the form view just before the final generation of the HTML of the form is started. This final generation of the HTML of the form takes place with the help of the so-called layouts and their layout-specific files, which are subject to an overwriting mechanism, the so-called ‘overrides’.
The event can be used, among other things, to insert individual JavaScript code into the form. The form parameters can also be changed at this point in order to adjust the layout of the form.
Parameter:
- String $context:
- com_visforms.form: Form is displayed via a menu
- mod_visforms.form: form is displayed by a module
- plg_vfformview.form: Form is displayed by Content Plugin - Visforms Form View
- Object $visforms: reference to the form object
- Object $menu_params: Reference to the menu parameters.
The parameter contains all administrative settings of the menu with which the form was called.
onVisformsEditFormPrepare
The onVisformsEditFormPrepare event is triggered in the form edit view before the form is finally displayed. Among other things, it can be used to insert individual JavaScript code into the form. The form parameters can also be changed at this point in order to adjust the layout of the form.
Parameter:
- String $context: com_visforms.form
- Object $visforms: reference to the Form object
- Object $menu_params: reference to menu parameters.
The parameter contains all administrative settings of the menu with which the form was called.
onVisformsBeforeFormSave
The onVisformsBeforeFormSave event is triggered before the submitted form data is saved to the database.
Parameter:
- String $context: com_visforms.form
- Object $visforms: reference to the Form object
- Array $fields: reference to field objects
Implementation Details
The onVisformsBeforeFormSave event is triggered from the VisformsController after the form has been submitted.
After submitting the form at the very end, there is still a redirect. The redirect takes place on the success page, the start page or back to the form. The exact target depends on what has been configured in the form on the “Result” tab. A test within your own development, which simply outputs a debug text with the PHP “echo” function, therefore never reaches the user interface.
It is therefore not possible to test with the PHP “echo” function for this event at this point whether the event is basically triggered.
The Joomla message queue must be used here as an alternative:
$app->enqueueMessage('message');
onVisformsAfterFormSave
The onVisformsAfterFormSave event is triggered after the submitted form data has been saved.
Parameter:
- String $context: com_visforms.form
- Object $visforms: reference to the form object
- Array $fields: reference to field objects
onVisformsEmailPrepare
The onVisformsEmailPrepare event is triggered twice with different context:
- before the result mail is sent and
- before the email is sent to the user.
The event can be used to run custom code that modifies the email or to attach a file to the email.
Parameter:
- String $context: com_visforms.form.receiptmail or com_visforms.form.resultmail
- Object $mail: reference to the mailer object
- Object $visforms: reference to the form object
onVisformsBeforeSuccessAction
The onVisformsBeforeSuccessAction event is triggered twice with different context just before the redirect action occurs.
Parameter:
- String $context: com_visforms.form
- Object $visforms: reference to the form object
- Array $fields: reference to field objects
onVisfieldBeforeCreate
The onVisfieldBeforeCreate event is triggered for each field in the form immediately after the field configuration has been loaded. All configuration values of the $field object can be modified early here, even before they are evaluated by the Visforms code itself. Changes to the field configuration in this event handler always have the desired effect.
Parameter:
- String $context: com_visforms.field
- Array $field: reference to the field object