Poper Javascript Event Blockers API

Poper's Event Blockers empower you to create custom validations and perform advanced checks for your forms within popups, widgets, and embeds.
This functionality adds an extra layer of control, allowing you to control your forms to specific requirements and enhance user experience.

Understanding Event Blockers:

Event Trigger: Poper utilizes the poper_before_submit_form event. This event fires before a form within a popup is submitted, providing an opportunity to intervene.
Listening for the Event: Use document.addEventListener to listen for the poper_before_submit_form event and execute your custom validation logic.
Event Details: The event object provides valuable details through event.detail, including:
- poperId: Unique identifier of the popup/widget/embed. For example, if your editor URL is https://app.poper.ai/popup/1234?stage=design, the poperId is 1234.
- formData: Key-value pairs representing user input from the form. The keys correspond to the "Input ID" defined for each input field in the popup editor.
- validationPromises: An array where you push your custom validation promises to control form submission.
- toast: A function to display toast messages within the popup for user feedback on validation errors.

Using Event Blockers for Custom Validation:

Here's how to create a custom validation using Event Blockers:

JavaScript

document.addEventListener('poper_before_submit_form', (event) => {
  const { poperId, formData, validationPromises, toast } = event.detail;

  // Example: Validate email domain for a specific popup (poperId 19)
  if (poperId === 19) {
    validationPromises.push(
      new Promise(async (resolve, reject) => {
        try {
          const isValid = formData?.Email?.includes("@latracal.com");

          if (isValid) {
            resolve(); // Validation successful
          } else {
            toast.error("Email is not from latracal.com");
            reject('Validation failed'); // Validation failed, prevent form submission
          }
        } catch (error) {
          reject(error); // Handle any errors during validation
        }
      })
    );
  }
});

Explanation:

We listen for the poper_before_submit_form event.
Inside the event listener, we access the poperId, formData, validationPromises, and toast objects from the event.detail.
We check if the poperId matches our desired popup (in this case, 19).
If it's the desired popup, we create a new Promise object.
Inside the Promise, we perform our validation logic (checking if email contains "@latracal.com").
If the validation is successful, we resolve the Promise, allowing form submission to proceed.
If the validation fails, we display an error message using the toast function and reject the Promise, preventing form submission.

Additional Use Cases:

Event Blockers allow for various functionalities beyond basic form validation:

Server-Side Validation: You can use asynchronous tasks within the Promise to communicate with your server and perform more complex validation checks.
Conditional Logic: Employ the poperId to implement different validation rules for specific popups based on their purpose.
Data Formatting: Use the formData object to manipulate user input before submission, ensuring data meets your requirements.

Finding Input IDs:

To locate the Input ID for a specific input field:

Open the Popup Editor: Navigate to the popup you want to modify in your Poper dashboard.

Select the Input Field: Click on the input field you want to assign an ID to.

Access Field Settings: In the left-hand side panel, you'll find a section for input field settings.

Locate the "Input ID" Field: Within the settings, look for a field labeled "Input ID." Enter a unique identifier for the field here.

By leveraging Event Blockers, you can significantly enhance form security, improve data accuracy, and provide a better user experience by offering clear and specific error messages. Remember to test your custom validations thoroughly to ensure they function as expected.