Wednesday , 26 July 2017
Home / Programming / WordPress / Plugins / WordPress Admin Forms – WordPress Plugin Tutorial
WordPress Admin Forms
WordPress Admin Forms

WordPress Admin Forms – WordPress Plugin Tutorial

This post is part of the WordPress Plugin tutorial series. To find a link to all tutorials in order, then please click here.

This will be our most complex plugin yet. We’ll be doing a couple of things we’ve done before and so some things will be skipped. In this tutorial, we’ll learn how to create WordPress admin forms. This will allow users to change the data for your options. Before, we’ve been updating the information in the code. This isn’t user friendly. So, let’s create a user friendly interface for our users.

First, let’s break down what we’re going to do when a user activates our plugin and starts using it.

  1. Check the WordPress Version
  2. Add the options with an array
  3. Add a submenu to the settings menu
  4. Display a form that displays the current value for the youtube username and allow the user to update this username.
  5. Process the form and update the value with the inputted value.
  6. Redirect user back to the form page

WordPress Admin Forms

Pretty simple once broken down. Let’s create a new plugin called wpHTMLDisplayEx. Our main plugin file will look like this.

Nothing new here, but we’re doing a couple of things. We first check the WordPress version. We then create the option jk_op_array which will hold an array of values.  We then include 3 files. Create these files and and leave them blank. We’ll go over each one. We then create an action hook, that’ll hook into the menu so we can add our submenu.

In our menu.inc.php file, add this bit of code.

Very simple here, we simply add a submenu item under the settings menu.  The function that will take care of displaying the page is jk_display_contents. This function will be created in the display-options.inc.php file. Let’s create this file and add this bit of code.

Alright, a couple of things to go over here. The very first thing we do is grab the options and create an array. The variable storing our array is named $options.

We then create a div and apply the class wrap. You must create this div as the class wrap is an actual class defined by WordPress and most pages in the WordPress dashboard is wrapped by the same div. So, we’re just following a norm in the WordPress community. The next couple of lines are simple HTML code.  A couple of things to take a look at.

Our form is sending out data to admin-post.php. This is where you should send all your data. We create a hidden field named action with the value jk_save_youtube_option. This value is important as we’ll be able to process the form. More about this later. Next, we use the wp_nonce_field() function. This function is extremely useful and prevents your form from being submitted by a user other than an admin. It’s a security measure.  It simply creates a hidden field that will only be present in the form. We  can check for this value when we process this form. We pass in a name for this field that should be unique.

Lastly, we create the input field for the youtube user name. We echo out the current value of the youtube username in the options array.  That’s it! We’e covered the first 4  steps. The last 2 are to process the form and redirect the user.

Before we can process the form, add this hook in our main plugin file.

Notice the name of the action hook we want to hook into. It corresponds to the input hidden value in our form. To hook into a post WordPress uses admin_post_ and then we append our hidden value from our display-options.inc.php file. This is how you’ll know if the form is submitted by hooking into it.  Our function process_jk_youtube_options() will process the form data. Our file process.php will contain our function.

This function runs when the form is submitted. We first check if the user can actually submit this form by using the current_user_can() function and passing in what capability the can perform. If they can’t, then we use the wp_die() function to kill the script. If all checks out, we then check if the nonce field was also submitted. The check_admin_referer() function does this for us. We pass in the name we passed in when we created the nonce field. If all checks out, then the code continues to run. If it returns false, the function will take care of killing the page for us and preventing the rest of the code from being executed.

We now grab the options array value and store them in a value. We then check if the POST data was sent and then update the options value jk_op_yt_username. The sanitize_text_field() function will check  and sanitize the POST data for us. More information can be found here.

Lastly we update the options and then redirect the user. The wp_redirect() function is a WordPress function that will redirect the user. We pass in the admins_url() function and inside that function we add the path relative the admin url.

Let’s do 1 last thing. You’ll notice in our redirect URL we added the m=1. It’s always good to notify our users that the settings have been successfully updated. So, in our dispay-options.inc.php file, let’s add this code under the <h2> tags.

This simple code simply outputs a success message. Let’s activate our plugin and if you did everything right. You should be able to update the option and see a success message like so.

WordPress Admin Forms
WordPress Admin Forms

About Jasko Koyn

Check Also

WordPress Meta Boxes

WordPress Meta Boxes – WordPress Plugin Tutorial

WordPress meta boxes are used to display certain information or options in a page. It’s …

9 comments

  1. Hey Jasko,

    big thanks to you! Great tutorial – it helped me a lot and saved me a ton of time and frustration.

    Appreciate it!

    Regards,
    Markus

  2. You save my day!
  3. Hi, nice article for a newbie developper on wp, but are you sure that by doing:

    wp_nonce_field( ‘jk_op_verify’ );

    in your form (to active CSRF protection), the token is well inserted ?

    By checking the doc, the function seems to not print the CSRF token if you not provide true to the 4th argument. So don’t you should do ‘echo wp_nonce_field( ‘jk_op_verify’ );’ ?

    Doc: https://developer.wordpress.org/reference/functions/wp_nonce_field/

    However this article helped me a lot !

  4. Very Good Article, Very Cool Blog. Thank You.
  5. Hello,

    Love the tute. Everything worked up until the form submission. All code triple checked.

    Error shows up in console: “NetworkError: 403 Forbidden – http://mydomain…/wp-admin/admin-post.php

    Won’t post.

  6. P.S. I checked actual file system permissions on that file and they are properly set.
  7. OK, figured it out for the folks following this post behind me. You MUST esc_url_raw the redirected url like this:

    wp_redirect(admin_url( esc_url_raw(‘options-general.php?page=yourpluginname/inc/menus.inc.php_display_contents&m=1’) ) );

    That will work.

Leave a Reply

Your email address will not be published. Required fields are marked *

ULTIMATE WORDPRESS DEVELOPMENT COURSE
Want to learn how to create your own custom WordPress plugins and themes? Check out my course!
Get 93% off my course. You'll also learn how to integrate WooCommerce and BuddyPress into your projects. This is a limited time offer
Yes, I would like to get 93% off your course!
No Thanks!
close-link