Mastering AMP Form Integration with WordPress: A Detailed Guide

AMP (Accelerated Mobile Pages) has been crafted to drastically enhance load times, but it also significantly improves form interaction. Forms that use the GET method behave like typical HTML forms. However, for forms using the POST method in AMP, special handling is necessary. Rather than causing a page reload, AMP leverages the amp-form component, which submits form data asynchronously through Ajax (XHR/fetch) with the use of the action-xhr attribute. When redirection after a form submission is required, the server must include the AMP-Redirect-To header. Ideally, the response should come in JSON format, and the submit-success or submit-error templates should be used to render it.

In the case of WordPress forms that contain an action attribute, the AMP plugin automatically converts them into amp-form. If the wp_redirect() function is used for redirection, AMP appends the AMP-Redirect-To header with a 200 status code, instead of the default 302 status.

When displaying success or error messages without requiring a redirect, AMP automatically integrates templates such as submitting, submit-error, and submit-success. If an error occurs through wp_die(), the message will appear inside the submit-error template. A 200 status code will show the content in the submit-success template. In the absence of a wp_die() trigger, the plugin will show a default message based on the HTTP status code.

To prevent the default message from displaying, check if the request originates from amp-form. Then, use either wp_die() or wp_send_json() before outputting the template, typically inside the template_redirect hook. The wp_is_json_success() function is helpful for detecting AMP-specific requests.

Here’s an example using wp_send_json():

if ( wp_is_json_request() ) { if ( $success ) { $message = __( 'Form submitted successfully. Thank you!', 'my-textdomain' ); } else { $message = __( 'Submission failed. Please try again.', 'my-textdomain' ); } wp_send_json( compact( 'message' ), $success ? 200 : 400 ); }

Alternatively, you can use wp_die():

if ( wp_is_json_request() ) { if ( $success ) { $message = __( 'Form submitted successfully. Thank you!', 'my-textdomain' ); } else { $message = __( 'Submission failed. Please try again.', 'my-textdomain' ); } wp_die( $message, '', [ 'response' => $success ? 200 : 400 ] ); }

For greater control over AMP form behavior, it is recommended to initially utilize the action-xhr attribute and integrate with a REST API endpoint to manage submit-success and submit-error templates.

Sometimes, ModSecurity might block form submissions, resulting in errors like the 406 Not Acceptable message. If this occurs, contact your hosting provider to request the whitelisting of __amp_source_origin.

For further information, refer to the AMP Form Documentation and explore more AMP Form Examples.