PHP 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.

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 onConvertFormsAfterRender(&$html)
{
   // your code here
}

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
}

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: (object) The PDF file name.
• &$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"

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
}

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: (array) 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);
}

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
}

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.

Return Value

None. Results are returned by modifying the referenced arguments.

Examples

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