feat: port AJAX form submission from premium to core (#835)

- Migrates AJAX form submission from premium to core via REST API.
- Replaces static 'Loading button text' with animated dots.
- Merges AJAX JS logic directly into core forms.js bundle.
- Includes backwards compatibility checks to prevent conflicts with older premium versions.

Author: faisalahammad

assets/src/js/forms.js

@@ -85,3 +85,123 @@ mc4wp.forms = forms
 
 // expose mc4wp object globally
 window.mc4wp = mc4wp
+
+// Initialize AJAX form submission if configured
+// The mc4wp_ajax_vars global is localized by PHP only when AJAX is enabled
+// and the premium AJAX module is not active.
+const ajaxConfig = window.mc4wp_ajax_vars
+if (typeof ajaxConfig !== 'undefined' && !ajaxConfig.inited) {
+  const Loader = require('./forms/ajax-form-loader.js')
+  let busy = false
+
+  /**
+   * Handle AJAX response data and update the form accordingly.
+   *
+   * @param {object} form  The mc4wp Form object
+   * @param {object} response  Parsed JSON response from REST API
+   */
+  function handleResponseData (form, response) {
+    forms.trigger('submitted', [form, null])
+
+    if (response.error) {
+      form.setResponse(response.error.message)
+      forms.trigger('error', [form, response.error.errors])
+    } else if (response.code && response.message) {
+      form.setResponse(`<div class="mc4wp-alert mc4wp-error"><p>${response.message}</p></div>`)
+      forms.trigger('error', [form, [response.code]])
+    } else {
+      const data = form.getData()
+
+      forms.trigger('success', [form, data])
+      forms.trigger(response.data.event, [form, data])
+
+      // for BC: always trigger "subscribed" event when firing "updated_subscriber" event
+      if (response.data.event === 'updated_subscriber') {
+        forms.trigger('subscribed', [form, data, true])
+      }
+
+      if (response.data.hide_fields) {
+        form.element.querySelector('.mc4wp-form-fields').style.display = 'none'
+      }
+
+      form.setResponse(response.data.message)
+      form.element.reset()
+
+      if (response.data.redirect_to) {
+        window.location.href = response.data.redirect_to
+      }
+    }
+  }
+
+  /**
+   * Submits the given form over AJAX using the REST API endpoint.
+   *
+   * @param {object} form  The mc4wp Form object
+   */
+  function ajaxSubmit (form) {
+    if (busy) {
+      return
+    }
+
+    const loader = new Loader(form.element, ajaxConfig.loading_character)
+    loader.start()
+
+    form.setResponse('')
+    busy = true
+
+    const request = new XMLHttpRequest()
+    request.onreadystatechange = function () {
+      if (request.readyState >= XMLHttpRequest.DONE) {
+        loader.stop()
+        busy = false
+
+        if (request.status >= 200 && request.status < 500) {
+          try {
+            const data = JSON.parse(request.responseText)
+            handleResponseData(form, data)
+          } catch (e) {
+            // eslint-disable-next-line no-console
+            console.error(`Mailchimp for WordPress: failed to parse response: "${e}"`)
+            form.setResponse(`<div class="mc4wp-alert mc4wp-error"><p>${ajaxConfig.error_text}</p></div>`)
+          }
+        } else {
+          // eslint-disable-next-line no-console
+          console.error(`Mailchimp for WordPress: request error: "${request.responseText}"`)
+        }
+      }
+    }
+    request.open('POST', ajaxConfig.ajax_url, true)
+    request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded')
+    request.setRequestHeader('Accept', 'application/json')
+    request.send(form.getSerializedData())
+  }
+
+  /**
+   * Intercepts form submissions for AJAX-enabled forms.
+   *
+   * @param {object} form  The mc4wp Form object
+   * @param {Event} evt    The original submit event
+   */
+  function maybeSubmitOverAjax (form, evt) {
+    if (form.element.getAttribute('class').indexOf('mc4wp-ajax') < 0) {
+      return
+    }
+
+    if (document.activeElement && document.activeElement.tagName === 'INPUT') {
+      document.activeElement.blur()
+    }
+
+    try {
+      ajaxSubmit(form)
+    } catch (e) {
+      // eslint-disable-next-line no-console
+      console.error(e)
+      return
+    }
+
+    evt.preventDefault()
+  }
+
+  forms.on('submit', maybeSubmitOverAjax)
+  ajaxConfig.inited = true
+}

assets/src/js/forms/ajax-form-loader.js

@@ -0,0 +1,84 @@
+/**
+ * @param {HTMLInputElement} button
+ * @returns {string}
+ */
+function getButtonText (button) {
+  return button.innerHTML ? button.innerHTML : button.value
+}
+
+/**
+ * @param {HTMLInputElement} button
+ * @param {string} text
+ */
+function setButtonText (button, text) {
+  if (button.innerHTML) {
+    button.innerHTML = text
+  } else {
+    button.value = text
+  }
+}
+
+/**
+ * Constructs a new loader, which manipulates the form's button to show a loading indicator.
+ *
+ * @param {HTMLFormElement} formEl
+ * @param {string} char
+ * @constructor
+ */
+function Loader (formEl, char) {
+  this.formEl = formEl
+  this.button = formEl.querySelector('input[type="submit"], button[type="submit"]')
+  this.char = char ?? '\u00B7'
+  if (this.button) {
+    this.originalButton = this.button.cloneNode(true)
+  }
+}
+
+/**
+ * Starts the loading indicator
+ */
+Loader.prototype.start = function () {
+  const { button, formEl, char } = this
+  if (button) {
+    const loadingText = this.button.getAttribute('data-loading-text')
+    if (loadingText) {
+      setButtonText(button, loadingText)
+    } else {
+      button.style.width = window.getComputedStyle(this.button).width
+      setButtonText(button, char)
+      this.loadingInterval = window.setInterval(this.tick.bind(this), 500)
+    }
+  } else {
+    formEl.style.opacity = '0.5'
+  }
+
+  formEl.className += ' mc4wp-loading'
+}
+
+/**
+ * Stops the loading indicator
+ */
+Loader.prototype.stop = function () {
+  const { button, originalButton, formEl, loadingInterval } = this
+  if (this.button) {
+    button.style.width = originalButton.style.width
+    const text = getButtonText(originalButton)
+    setButtonText(button, text)
+    window.clearInterval(loadingInterval)
+  } else {
+    formEl.style.opacity = ''
+  }
+
+  formEl.className = formEl.className.replace('mc4wp-loading', '')
+}
+
+/**
+ * Represents a single step in the loading indicator
+ */
+Loader.prototype.tick = function () {
+  const { button, char } = this
+  const text = getButtonText(button)
+  setButtonText(button, text.length >= 5 ? char : `${text} ${char}`)
+}
+
+module.exports = Loader

config/default-form-settings.php

@@ -1,6 +1,7 @@
 <?php
 
 return [
+    'ajax'               => 1,
     'css'                => 0,
     'double_optin'       => 1,
     'hide_after_success' => 0,

includes/forms/class-asset-manager.php

@@ -18,6 +18,16 @@ class MC4WP_Form_Asset_Manager
      */
     private $load_typo_checker = false;
 
+    /**
+     * @var bool Flag to determine whether AJAX form script should be enqueued.
+     */
+    private $load_ajax = false;
+
+    /**
+     * @var string Error text from first AJAX-enabled form, used as fallback in JavaScript.
+     */
+    private $ajax_error_text = '';
+
     /**
      * Add hooks
      */
@@ -168,6 +178,12 @@ public function before_output_form($form)
         $this->print_dummy_javascript();
         $this->load_scripts = true;
 
+        // check if this form has AJAX enabled (skip if premium AJAX module is active)
+        if (! empty($form->settings['ajax']) && ! $this->load_ajax && ! class_exists('MC4WP_AJAX_Forms')) {
+            $this->load_ajax = true;
+            $this->ajax_error_text = $form->get_message('error');
+        }
+
         // check if this form has typo checker enabled
         if (! empty($form->settings['email_typo_check'])) {
             $this->load_typo_checker = true;
@@ -230,6 +246,27 @@ public function load_scripts()
             wp_localize_script('mc4wp-forms-submitted', 'mc4wp_submitted_form', $submitted_form_data);
         }
 
+        // maybe load AJAX forms script
+        if ($this->load_ajax) {
+            // default loading character (bullet)
+            $character = '•';
+
+            /**
+             * Filters the loading character used for AJAX form requests.
+             *
+             * @since 4.13.0
+             *
+             * @param string $character The loading character.
+             */
+            $loading_character = (string) apply_filters('mc4wp_forms_ajax_loading_character', $character);
+
+            wp_localize_script('mc4wp-forms-api', 'mc4wp_ajax_vars', [
+                'loading_character' => $loading_character,
+                'ajax_url'          => rest_url('mc4wp/v1/form'),
+                'error_text'        => $this->ajax_error_text,
+            ]);
+        }
+
         // print inline scripts
         echo '<script>';
         echo '(function() {';

includes/forms/class-form-element.php

@@ -362,6 +362,11 @@ protected function get_css_classes()
             $classes[] = 'mc4wp-form-' . $form->settings['css'];
         }
 
+        // add AJAX class if enabled
+        if (! empty($form->settings['ajax'])) {
+            $classes[] = 'mc4wp-ajax';
+        }
+
         // add classes from config array
         if (! empty($this->config['element_class'])) {
             $classes = array_merge($classes, explode(' ', $this->config['element_class']));

includes/forms/class-form-manager.php

@@ -141,6 +141,8 @@ public function register_endpoint()
      * Process requests to the form endpoint.
      *
      * A listener checks every request for a form submit, so we just need to fetch the listener and get its status.
+     *
+     * @return WP_REST_Response|WP_Error
      */
     public function handle_endpoint()
     {
@@ -156,18 +158,30 @@ public function handle_endpoint()
         }
 
         if ($form->has_errors()) {
-            $message_key = $form->errors[0];
-            $message     = $form->get_message($message_key);
-            return new WP_Error(
-                $message_key,
-                $message,
+            return new WP_REST_Response(
                 [
-                'status' => 400,
-                ]
+                    'error' => [
+                        'type'    => $form->errors[0],
+                        'message' => $form->get_response_html(),
+                        'errors'  => $form->errors,
+                    ],
+                ],
+                400
             );
         }
 
-        return new WP_REST_Response(true, 200);
+        $data = [
+            'event'       => $form->last_event,
+            'message'     => $form->get_response_html(),
+            'hide_fields' => (bool) $form->settings['hide_after_success'],
+        ];
+
+        $redirect_url = $form->get_redirect_url();
+        if (! empty($redirect_url)) {
+            $data['redirect_to'] = $redirect_url;
+        }
+
+        return new WP_REST_Response([ 'data' => $data ], 200);
     }
 
     /**

includes/forms/views/tabs/form-settings.php

@@ -175,6 +175,30 @@
         </td>
     </tr>
 
+    <?php
+    // Only show AJAX settings if the premium AJAX module is not active, to avoid duplicate settings.
+    if (! class_exists('MC4WP_AJAX_Forms')) {
+        ?>
+        <tr valign="top">
+            <th scope="row"><?php echo esc_html__('Enable AJAX form submission?', 'mailchimp-for-wp'); ?></th>
+            <td class="nowrap">
+                <label>
+                    <input type="radio" name="mc4wp_form[settings][ajax]" value="1" <?php checked($opts['ajax'], 1); ?> />&rlm;
+                    <?php echo esc_html__('Yes', 'mailchimp-for-wp'); ?>
+                </label> &nbsp;
+                <label>
+                    <input type="radio" name="mc4wp_form[settings][ajax]" value="0" <?php checked($opts['ajax'], 0); ?> />&rlm;
+                    <?php echo esc_html__('No', 'mailchimp-for-wp'); ?>
+                </label>
+                <p class="description">
+                    <?php echo esc_html__('Select "yes" if you want to use AJAX (JavaScript) to submit forms.', 'mailchimp-for-wp'); ?>
+                </p>
+            </td>
+        </tr>
+        <?php
+    }
+    ?>
+
     <?php do_action('mc4wp_admin_form_after_behaviour_settings_rows', $opts, $form); ?>
 
 </table>