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

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