Joomla Plugin Events

Developers can extend Convert Forms functionality by listening to certain events within a Joomla Plugin. Below you can find the list with the supported events.

Form

onConvertFormsFormBeforeRender

Fires before the form’s HTML is rendered. This is rather useful when you want to manipulate the form’s object and modify a form option such as the width, the background color, or even the thank-you message.

Parameters

• &$form: (array) The form’s information object. Passed by reference.

Return Value

None. Results are returned by modifying the referenced arguments.

Example

public function onConvertFormsFormBeforeRender(&$form)
{
   // your code here
}

onConvertFormsFormAfterRender

Fires when the form’s final HTML layout is ready and before is added to the page. This is rather useful when you want to make modifications to the form’s HTML layout like prepend some texts or change an HTML attribute.

Parameters

• &$html: (string) The form’s final HTML layout. Passed by reference.
• $form: (array) The form’s information object.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsFormAfterRender(&$html)
{
   // your code here
}

onConvertFormsExport

Fires once for each form you export, right before Convert Forms writes the export file. Add properties to the form object and they go into the file with it. Pair it with onConvertFormsImport to restore that data when someone imports the file. The Tasks plugin uses this pair to carry a form’s tasks and connections.

Parameters

• &$form: (object) The form as stored in the database. Passed by reference.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsExport(&$form)
{
	$form->myextension = [
		'color' => 'blue'
	];
}

onConvertFormsImport

Fires once for each form after it’s imported and saved. The form object holds everything from the export file, including the properties you added in onConvertFormsExport, and its id is the new form’s ID.

Parameters

• $form: (object) The imported form. Arrays and objects you added on export come back as arrays.

Return Value

None.

Examples

public function onConvertFormsImport($form)
{
	if (!isset($form->myextension))
	{
		return;
	}

	$color = $form->myextension['color'];

	// Save $color for the new form, $form->id
}

onConvertFormsDuplicate

Fires after you duplicate a form and Convert Forms saves the copy. Use it to copy the data your extension stores for each form over to the new copy. The Tasks plugin copies a form’s tasks this way.

Parameters

• $newFormId: (int) The copy’s ID.
• $originalFormId: (int) The ID of the form you duplicated.

Return Value

None.

Examples

public function onConvertFormsDuplicate($newFormId, $originalFormId)
{
	// your code here
}

Tasks

onConvertFormsTaskBeforeRun

Fires right before each of the form’s tasks runs, once per task. Smart Tags in the task’s settings are already replaced, so you see the exact values the task will send. Use it to change a task’s settings for this submission, or to skip the task.

It fires for every task, even disabled ones and ones whose conditions won’t pass. Convert Forms checks state and conditions after this event, so whatever you set there decides whether the task runs.

Parameters

• $event: (object) Carries the task and the submission. Changes you make to its properties stick, so there’s no need to pass it by reference.
  • $event→task: (array) The task about to run. app names the app (e.g. mailchimp), options holds its settings, and state is 1 when the task is enabled.
  • $event→submission: (object) The submission information object.

Return Value

None. Results are returned by modifying the $event object.

Examples

Skip the Mailchimp task when the “newsletter” checkbox is unticked

public function onConvertFormsTaskBeforeRun($event)
{
	if ($event->task['app'] == 'mailchimp' && empty($event->submission->prepared_fields['newsletter']->value))
	{
		$event->task['state'] = 0;
	}
}

onConvertFormsTaskAfterRun

Fires right after each of the form’s tasks runs, once per task. Use it to read what the task returned, log the outcome, or pass the response on to another system.

It doesn’t fire for skipped tasks (disabled, or their conditions didn’t pass). It also doesn’t fire when a task fails with Silent Fail turned off, since that error stops the remaining tasks.

Parameters

• $event: (object) The same object onConvertFormsTaskBeforeRun receives, plus the task’s result.
  • $event→task: (array) The task that ran.
  • $event→submission: (object) The submission information object.
  • $event→result: (array) The outcome: success (boolean), errors (an array of error messages) and response (what the app returned).

Return Value

None.

Examples

public function onConvertFormsTaskAfterRun($event)
{
	if (!$event->result['success'])
	{
		// The task failed. $event->result['errors'] lists why.
	}
}

Submission

onConvertFormsSubmissionValidate

This event fires almost immediately after the form’s submit button is clicked and the form is about to validate the submitted data. This area is rather useful when you need to perform your own custom validations and display an error message to the user. Any modifications to the $data variable performed here will be reflected in the submission entry.

Parameters

• &$data: (array) The submitted data as appears in the $_POST variable. Passed by reference.
• &$error: (string) The error message to display.
• $form: (array) The form’s information object.

Return Value

Boolean. The result will affect the saving process.

Examples

public function onConvertFormsSubmissionValidate(&$data, &$error, $form)
{
   // your code here
}

onConvertFormsSubmissionBeforeSave

Fires when the validation checks pass and before the submitted data is stored in the database. If a validation error occurs during submission this event won’t fire. This event enables you to edit the submitted data and change the value of any field.

If you’re doing form processing and need to be able to return an error and prevent form processing, use the onConvertFormsSubmissionValidate event instead.

Parameters

• &$data: (array) The submitted data

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsSubmissionBeforeSave(&$data)
{
   // your code here
}

onConvertFormsSubmissionAfterSavePrepare

This event is called right after the submission is saved into the database and before all actions and addons have been executed. It only fires if the submission was successful and it did not contain any errors. An example use case would be to manipulate the uploaded files data (i.e. move them to a different folder) and this would ensure the PDF generated and/or the emails sent would have the updated data.

Parameters

• &$submission: (object) The submission information object.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsSubmissionAfterSavePrepare(&$submission)
{
   // your code here
}

onConvertFormsSubmissionAfterSave

This event is called at the very end after the submission is saved into the database and all actions and addons have been executed. It only fires if the submission was successful and it did not contain any errors. An example use case would be making an API call to an external service.

Parameters

• &$submission: (object) The submission information object.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsSubmissionAfterSave(&$submission)
{
   // your code here
}

onConvertFormsError

Fires when a form submission fails, for example when a required field is empty, a spam check blocks the submission, or a task fails. Use it to log errors or alert someone. The Convert Forms - Error Logger plugin uses this event to write errors to the Joomla log.

Parameters

• $error: (string) The error message.
• $category: (string) The error category, for example spam when a spam check blocked the submission, or Submit for other submission errors.
• $form_id: (int) The form’s ID.
• $data: (array) The submitted data, or null when there’s none.

Return Value

None.

Examples

public function onConvertFormsError($error, $category, $form_id, $data = null)
{
	// your code here
}

Fields

onConvertFormsFieldBeforeRender

Fires before a field is rendered in the form. This is rather useful when you would like to change a field property, like the Label or the Placeholder.

Parameters

• &$field: (object) The field object. Passed by reference.
• $form: (array) The form information object.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsFieldBeforeRender(&$field)
{
   // your code here
}

onConvertFormsFieldAfterRender

Fires after a field is rendered in the form. This is rather useful when you would like to change the HTML layout of the field.

Parameters

• &$html: (string) The field’s HTML layout. Passed by reference.
• $field: (object) The field information object.
• $form: (array) The form information object.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsFieldAfterRender(&$html, $field)
{
   // your code here
}

onConvertFormsFileUpload

Fires by the File Upload field after the uploaded file has been moved into its destination folder. With this event, you can rename the file, move it to another folder, resize an image or even upload it to a cloud storage service such as Google Drive or Amazon S3.

Parameters

• &$filepath: (string) The absolute file path where the file is stored. Passed by reference.
• $data: (array) The form submitted data.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

Move file to a custom folder

public function onConvertFormsFileUpload(&$filepath, $data)
{
	$newFilepath = JPATH_SITE . '/images/myCustomFolder/' . basename($filepath);

	// Move file to the new folder and return the new filename
	$filepath = NRFramework\File::move($filepath, $newFilepath);
}

onConvertFormsFieldSignatureStore

Fires by the Signature field just after the file has been moved into its destination folder. With this event, you can rename the file, or move it to a different location.

Parameters

• &$filepath: (string) The absolute file path where the file is stored. Passed by reference.
• $data: (array) The form submitted data.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

Move file to a custom folder

public function onConvertFormsFieldSignatureStore(&$filepath, $data)
{
	$newFilepath = JPATH_SITE . '/images/myCustomFolder/' . basename($filepath);

	// Move file to the new folder and return the new filename
	$filepath = NRFramework\File::move($filepath, $newFilepath);
}

Other

onConvertFormsPDFFileName

This event is called right before the PDF file is generated, allowing you customize the PDF File Name. It only fires if the submission was successful and it did not contain any errors. An example use case would be to manipulate the PDF File Name and remove the unique hash added by default on each PDF file name.

Parameters

• &$pdf_file_name: (string) The PDF file name, without the .pdf extension. Passed by reference.
• $submission: (object) The submission information object.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsPDFFileName(&$pdf_file_name, $submission)
{
	$pdf_file_name = 'new_name';
}

How to rename the PDF file to contain the submission ID

Go into your form → Behavior → PHP Scripts → Form Process and add:

$app->registerEvent('onConvertFormsPDFFileName', function(&$data) {
     // Initialize variables
     $pdf_filename = $data->getArgument(0);
     $submission = $data->getArgument(1);

     // Modify the filename
     $pdf_filename = 'prefix_{submission.id}';

     // Set the updated value back to the $data object
     $data->setArgument(0, $pdf_filename);
});

You can utilize Smart Tags within the $pdf_filename variable.

Advanced: How to rename the PDF file via the submission object

Apart from using Smart Tags, you can also use the $submission variable that provides access to all submission details, including the field values.

Example of using the $submission object to create the PDF file name:

$app->registerEvent('onConvertFormsPDFFileName', function(&$data) {
     // Initialize variables
     $pdf_filename = $data->getArgument(0);
     $submission = $data->getArgument(1);

     // Modify the filename
     $hidden_field_value = $submission->prepared_fields['HIDDEN_FIELD_NAME']->value;
     $pdf_filename = 'prefix_' . $hidden_field_value . '_' . $submission->id;

     // Set the updated value back to the $data object
     $data->setArgument(0, $pdf_filename);
});

• Replace "HIDDEN_FIELD_NAME" with your Hidden Field → Field Name value.

The final PDF file name should look like "prefix_{HIDDEN FIELD NAME}_{SUBMISSION ID}.pdf"

onConvertFormsCronTask

Fires when a CRON task is initialized by the endpoint URL. A CRON Task can be initialized by visiting the following URL

http://www.site.com?option=com_convertforms&task=cron&command=COMMAND_NAME&secret=SECRET_KEY

Parameters

• $task: (string) The name of the task as defined in the command parameter in the CRON endpoint URL.
• $options: (array) Task options. time_limit holds the number of seconds a long-running task should stop after (currently 10).

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

public function onConvertFormsCronTask($task, $options)
{
   // your code here
}