Follow

Handling form submissions in WordPress

You are planning to write a brilliant plugin. Its’ got a form from which you collect data from the user and register them to your website

In your plugin, to generate the form, you are probably using a shortcode. When the user hits that submit button you’ve to submit that data to the server and register him. There are multiple ways to do this.

We will look at two of these methods, their merits and demerits.

Handling POST/GET data in WP Shortcode:

We can handle the submitted data in the shortcode’s callback function.
Example :
There is a shortcode for a registration page. The page has a form with its method attribute set to “POST”. It has an email and password field.
On submission, the form data is sent to the server. The same shortcode hook will be triggered because by default the form is submitted to the same page.
In the callback hook / method we can check if the post data ($_POST) is set and then process the data.

We will render the form from the above function. The form will be present in our register-form.php. Think of it as a view / template file.

In the above example the shortcode is handling the POST requests and sending the response.

Advantages in the above method:

• Displaying error messages in the form is easy in case of a validation error.
• Relatively easier to setup and develop.

Drawbacks in above method:

• We can’t redirect from the shortcode since by the time the shortcodes run, headers have already been sent to the browser.
• We can’t log the user in after they register, since that requires sending of Cookies which have to be sent along with the header.
• If there are many forms in the page, we need to check which form’s request was submitted.
• We can’t show response in another page (the only way is by echoing JavaScript to redirect to another page).

The admin_post and admin_ajax hooks

The admin_post hook

This hook allows you to create custom handlers for your own GET and POST form submissions and requests. The admin_post hook follows the format “admin_post_$youraction“, where $youraction is your GET or POST request’s ‘action’ parameter.

Example
If you needed to create a request or form handler for an “my_plugin_register_user” action request, you would create a hook like this:

The above hook will be triggered when we submit this registration form. Notice that we keep the action attribute in a hidden field, which will help WordPress route this function to our hook.

NOTE : The action of the form should be always admin-post.php. To echo the path of this file, we will admin_url() function. The path will be – http://{{your-website}}/wp-admin/admin-post.php

The email, password values can be accessed in the hook from $_GET, $_POST or $_REQUEST. If you want to redirect to login page on successful submission, we can do that in that in the hook.

In the above code we’ve also used something called nonce. WordPress nonces can help strengthen the security of the website.

The process is a fairly simple two-step affair:
1. Generate a nonce at the origin of an action (placing it in a link or as a hidden field in a form)
2. Validate it at the target.

To generate a nonce field we use wp_nonce_field. This will generate 2 hidden fields.

The value of the 1st field will be generated using 1st parameter of the function. Here the 1st parameter is ‘register-user’. 2nd parameter will be the name of the hidden field.

The nonce can be verified by wp_verify_nonce(). If the nonce is not valid, that means the action is not intended. We can handle it according to the context.

Handling logged in/non logged in users :

Using admin-post hook we can implement separate functionality for logged in and non-logged in user. We can register two different functions to trigger when the user is either logged in or not logged in. WordPress will determine at runtime whether the user is logged in and trigger the appropriate function.

If we did this in a shortcode we’d have to have a is_user_logged_in() check, but here WordPress takes care of it for us.

The admin_ajax hook

This hook allows you to create custom handlers for your own custom AJAX requests. It is similar in usage with the admin_post hooks. The wp_ajax hook follows the format “wp_ajax_$youraction“, where $youraction is your AJAX request’s ‘action’ property.

Example
If you need to add an AJAX based handler for a “my_plugin_register_user” request, you would create a hook like this:

To make the AJAX call secure, we are using something called ajax_nonce. This will create a nonce for the AJAX call. We are localizing those values to use those in our script using wp_localize_script.

In the above function we used check_ajax_referer function to check if nonce is valid.
If the nonce is not set or incorrect, then check_ajax_referrer() will cause the AJAX call to die, protecting the AJAX call from invalid requests.

Using the above example, any time an AJAX request is sent to WordPress, and the request’s ‘action’ property is set to ‘register_user’, this hook will be automatically executed. For example, the following code would execute the above hook.

The AJAX request can be handled by admin-ajax.php. The URL where the data should be submitted – http://{{your-website}}/wp-admin/admin-ajax.php

Advantages in the above method(s):

• Redirection to another page is possible.
• Can login the user in this hook, since headers have not yet been sent.
• Using individual actions for individual forms, it is easier to have a single page containing multiple forms.
• Comparatively faster since less processing happens and inputs are processed earlier in the WP page life cycle.
• Better separation of code.

Disadvantages in the above methods(s):

• Displaying error messages in case of validation errors is trickier than it is for shortcodes.

So, when to use what?

Although the two approaches can be used interchangeably, admin-post hooks were built by WordPress to handle form submissions. Shortcodes make sense when your plugin is small but if you intend to provide user login, perform redirections, set cookie’s then admin hooks are the way to go.

Our recommendation would be to use both, use the shortcodes to handle loading of the view, based on attributes passed by the user, whereas use the wp_action hooks to handle the data submitted by the user. This also introduces a nice separation of code, where the core business logic stays in the admin_post hook, whereas the view and view related logic is taken care by the shortcode.

Since your business logic is in the admin_hook, the view is in the shortcode and they both trigger as part of a different request, you’ll have to find a way to send errors with user submitted data from the admin_hook to the shortcode so that you can tell the user about them in the view. WordPress’ transients provide a way to handle this problem.

About the author:

Prasanna works at Osmosys as a PHP developer. She is a Computer Science Graduate from JNTU Vijayanagaram, with over 2 years of PHP and wordpress experience. You can find her on facebook @pulukurthi.prasanna

Are you interested? follow us and get notified of new posts

4 thoughts on “Handling form submissions in WordPress

  1. Pingback: Handling form submissions in WordPress — Osmosee’s Blog | harikrishnagutti
  2. Akshay Kelotra
    at 11:14 am

    How can we handle server side validation and show errors on the form using admin-post method?

    1. admin user
      at 9:13 am

      Hi Akshay,
      We can add validations on server side. If the validation fails, we can store the errors in the session and redirect to the same page. Based on the session variables we display the validation errors in the form. We should then unset the session variables after rendering the page.

Leave A Reply

13 + 12 =