Filters and hooks
Here is everything that you can hook into:
🔧 Filters
av_petitioner_info_edit
Filter to modify petitioner data that is sent to the edit screen for a specific petition form.
Parameters
- array
$petitioner_info— Array of the data - int
$form_id— ID of the form being rendered
Example Usage
add_filter('av_petitioner_info_edit', function($petitioner_info, $form_id) {
// Modify the data sent to the edit screen
$petitioner_info['custom_field'] = 'custom_value';
return $petitioner_info;
}, 10, 2);av_petitioner_info_settings
Filter to modify petitioner data that is sent to the global settings screen.
Parameters
- array
$petitioner_info— Array of the data
Example Usage
add_filter('av_petitioner_info_settings', function($petitioner_info) {
// Modify the data sent to the settings screen
$petitioner_info['custom_setting'] = 'custom_value';
return $petitioner_info;
});petitioner_send_ty_email
Filter that decides if the thank you email/confirmation email should be sent.
Parameters
- bool
$should_send_ty_email— Whether to send the thank you email - array
$filter_args— The arguments passed to the filter (form_id, submission_id, user_name)
Example Usage
add_filter('petitioner_send_ty_email', function($should_send, $args) {
if (isset($args['user_name'])) {
$should_send = !preg_match('/^(unwanted|string|here)/i', $args['user_name']);
}
return $should_send;
}, 10, 2);petitioner_send_to_representative
Filter that decides if the email should be sent to the representative.
Parameters
- bool
$should_send_to_rep— Whether to send to representative - array
$filter_args— The arguments passed to the filter (form_id, submission_id, user_name)
Example Usage
add_filter('petitioner_send_to_representative', function($should_send, $args) {
if (isset($args['submission_id'])) {
$should_send = $args['submission_id'] !== 123; // prevent sending for a specific form
}
return $should_send;
}, 10, 2);petitioner_get_styled_message
Filters the styled email message content. This filter allows modification of the final HTML content of the email message.
Parameters
- string
$final_html— The final HTML content of the email message - string
$message— The original unstyled message content
Example Usage
add_filter('petitioner_get_styled_message', function($final_html, $message) {
$final_html = '
<div style="background-color: black; padding: 48px 8px; text-align: center;">
<table role="presentation" border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width: 600px; margin: 0 auto; background: #ffffff; border-radius: 6px; overflow: hidden;">
<tr>
<td style="padding: 24px; font-family: Arial, sans-serif; font-size: 16px; color: #333333; text-align: left;">
' . $message . '
</td>
</tr>
</table>
</div>';
return $final_html;
}, 10, 2);av_petitioner_form_fields, av_petitioner_form_fields_admin
Filter to modify the form fields before rendering. One is called in the admin panel, the other on the frontend of the site.
Parameters
- array
$form_fields— Array of form fields - int
$form_id— ID of the form being rendered
Example Usage
add_filter('av_petitioner_form_fields', function($form_fields, $form_id) {
if($form_id == 1){
// Decode if string
if (is_string($form_fields)) {
$form_fields = json_decode($form_fields, true);
}
if (empty($form_fields) || !is_array($form_fields)) {
$form_fields['fname']['label'] = __('Modified label', 'textdomain');
}
}
return $form_fields;
}, 10, 2);av_petitioner_field_order
Filter to modify the order of form fields before rendering. The values in the array should match the keys in the $form_fields array.
Parameters
- array
$order— Array of field keys in the desired display order - int
$form_id— ID of the form being rendered
Example Usage
add_filter('av_petitioner_field_order', function($order, $form_id) {
return ['fname', 'lname', 'email', 'country', 'submit'];
}, 10, 2);av_petitioner_get_field_attributes
Filter to add extra HTML attributes to form fields. This can be used to add attributes like pattern, title, maxlength, etc.
Parameters
- string
$extra_attributes— Extra attributes to be added to the field markup - array
$field— The field array itself
Example Usage
add_filter('av_petitioner_get_field_attributes', function($attributes, $field) {
if ($field['type'] === 'tel') {
$attributes .= ' pattern="[0-9\s\-\(\)]*" title="Please enter a valid phone number"';
}
return $attributes;
}, 10, 2);av_petitioner_submission_data_pre_save
Filter the form submission data before it is saved. This allows modification of the submission data before storage.
Parameters
- array
$data— Associative array of submission data (field values and metadata)
Example Usage
add_filter('av_petitioner_submission_data_pre_save', function($data) {
if($data['form_id'] === 1){
$data['lname'] = ''; // remove last names for a specific form
}
return $data;
}, 10, 1);av_petitioner_labels_defaults
Filter to modify the default labels for the plugin.
Parameters
- array
$defaults— Array of default labels
Example Usage
// Keep default labels as is but modify the "Goal" label
add_filter('av_petitioner_labels_defaults', function ($defaults) {
return array_merge($defaults, [
'goal' => 'Goaaaaaal'
]);
});av_petitioner_mailer_settings
Filter the mailer settings before sending emails. This allows modification of the mailer settings (e.g. adding/removing recipients) before the emails are sent.
Parameters
- array
$mailer_settings— Associative array of mailer settings - array
$data— Associative array of submission data
Example Usage
add_filter('av_petitioner_mailer_settings', function($mailer_settings, $data) {
// Add additional CC recipient
$mailer_settings['target_cc_emails'] .= ', [email protected]';
// Modify the subject based on country
if ($data['country'] === 'US') {
$mailer_settings['subject'] = 'US Petition: ' . $mailer_settings['subject'];
}
return $mailer_settings;
}, 10, 2);av_petitioner_confirmation_mailer_settings
Filter the mailer settings before sending emails for email confirmations. This allows modification of the mailer settings before the emails are sent.
Parameters
- array
$mailer_settings— Associative array of mailer settings - object
$submission— Submission data object
Example Usage
add_filter('av_petitioner_confirmation_mailer_settings', function($mailer_settings, $submission) {
// Add additional CC recipient
$mailer_settings['target_cc_emails'] .= ', [email protected]';
// Modify the subject based on country
if ($submission->country === 'US') {
$mailer_settings['subject'] = 'US Petition: ' . $mailer_settings['subject'];
}
return $mailer_settings;
}, 10, 2);âš¡ Actions
petitioner_after_submission
Fires an action after a submission is processed. This hook allows developers to perform custom actions or extend functionality after a submission has been successfully handled.
Parameters
- int
$submission_id— The ID of the processed submission - int
$form_id— The ID of the form associated with the submission
Example Usage
add_action('petitioner_after_submission', function($submission_id, $form_id) {
// retrieve details about the submission (name, email, etc)
$submission = AV_Petitioner_Submissions_Model::get_submission_by_id($submission_id);
// once you have the details, use it however your like
// below is a dummy function you could make to send data to your CRM
send_to_your_crm($submission->email, $submission);
}, 10, 2);📱 JavaScript Events
Petitioner also comes with a frontend event for watching form submissions.
petitionerFormSubmit
Basic event listener setup:
document.addEventListener("petitionerFormSubmit", function (e) {
// your code here
});Example: Redirect to Thank You Page
document.addEventListener("petitionerFormSubmit", function (e) {
window.location = 'https://yoursite.com/thanks/' // replace with your url
});Example: Conversion Tracking
Includes conversion events for GA4, Google Ads, Facebook Pixel, and Google Tag Manager:
document.addEventListener("petitionerFormSubmit", function (e) {
// 1. Google Analytics 4 (GA4) Event
if (typeof gtag === "function") {
gtag("event", "petition_form_submit", {
event_category: "Petition",
event_label: "Petitioner Form",
value: 1,
});
}
// 2. Google Ads Conversion Tracking
// Replace with your real Conversion ID and Label
if (typeof gtag === "function") {
gtag("event", "conversion", {
send_to: "AW-XXXXXXXXXX/XXXXXXXXXXXX", // Your Google Ads ID/Label
value: 1.0,
currency: "USD",
});
}
// 3. Facebook Pixel (Meta) Event
if (typeof fbq === "function") {
fbq("track", "Lead", {
content_name: "Petitioner Form",
value: 1.0,
currency: "USD",
});
}
// 4. Google Tag Manager
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: "petitioner_form_submit", // this name will trigger your GTM tags
formName: "Petitioner Form",
});
});