Home > Docs > Filters and hooks

Filters and hooks

Here is everything that you can hook into:

petitioner_send_ty_email

Filter that decides if the thank you email/confirmation email should be sent.

Args:

$should_send_ty_email (bool) Whether to send the thank you email.

$filter_args (array) The arguments passed to the filter. (form_id, submission_id, user_name)

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;
} );

petitioner_send_to_representative

Filter that decides if the thank you email/confirmation email should be sent.

Args:

$should_send_to_rep (bool) Whether to send the thank you email.

$filter_args (array) The arguments passed to the filter. (form_id, submission_id, user_name)

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;
} );

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.

Args:

$submission_id (int) The ID of the processed submission.

$form_id (int) The ID of the form associated with the submission.

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)
} );

petitioner_get_styled_message

Filters the styled email message content. This filter allows modification of the final HTML content of the email message.

Args:

$final_html (string) The final HTML content of the email message.

$message (string) The original unstyled message content.

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;
} );

av_petitioner_form_fields, av_petitioner_form_fields_admin

Filter to modify the form fields before rendering in the admin panel. One is called in the admin panel, the other on the frontend of the site.

Args:

$form_fields (array) Array of form fields.

$form_id (int) ID of the form being rendered.

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');
     }
   }
} );

av_petitioner_field_order

Filter to modify the order of form fields before rendering. This allows plugins or themes to reorder the fields displayed in the form. The values in the array should match the keys in the `$form_fields` array. Any missing or extra keys will be ignored during the rendering process.

Args:

$order (array) Array of field keys in the desired display order.

$form_id (int) ID of the form being rendered.

Usage:

add_filter('av_petitioner_field_order', function($order, $form_id) {
 	return ['fname', 'lname', 'email', 'country', 'submit'];
});

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.

Args:

$extra_attributes (string) Extra attributes to be added to the field markup.

$field (array) The field array itself

Usage:

add_filter('av_petitioner_get_field_attributes', function($attributes, $field) {
   if ($type === 'tel') {
		$attributes .= ' pattern="[0-9\s\-\(\)]*" title="Please enter a valid phone number"';
   }
  
  return $attributes;
}, 10, 4);

av_petitioner_submission_data_pre_save

Filter the form submission data before it is saved. This allows modification of the submission data (e.g. sanitization, additional metadata) before the submission is created and stored.

Args:

$data (array) Associative array of submission data (field values and metadata).

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, 4);

JavaScript event

Petitioner also comes with a frontend event for watching form submissions. Here is how to use it:

document.addEventListener("petitionerFormSubmit", function (e) {
  // your code here
});

Here are a few ways you can use it:

Redirect to a thank you page

document.addEventListener("petitionerFormSubmit", function (e) {
   window.location = 'https://yoursite.com/thanks/' // replace with your url
});

Use for various conversion events

This code includes a conversion event for GA4,

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",
    });
  }

  // 3. Google Tag Manager
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    event: "petitioner_form_submit", // this name will trigger your GTM tags
    formName: "Petitioner Form",
  });
});