Tuesday , 18 June 2019
Home / Programming / WordPress / Plugins / WordPress Settings API Part 2 – WordPress Plugin Tutorial
WordPress Settings API
WordPress Settings API

WordPress Settings API Part 2 – 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.

In our previous tutorial, I explained what the settings API is and how useful it is. I also  gave some code to help us get started. In this part, we’ll be discussing how to use the WordPress Settings API with the same plugin we crated in our last tutorial.

We’ll mainly be working in our display-admin.inc.php file for this tutorial. You should have 2 empty functions named jk_social_display_settings() and jk_social_init_register_settings(). 

WordPress Settings API

Let’s update our jk_social_display_settings() to this.

A couple of things here, we first wrap our content inside the <div class=”wrap”><div>. It’s important you do this whenever you’re creating content inside the admin panel. Next we use the screen_icon() function which is simply a function WordPress creates that will display an icon. You can of course, use your own, but for this tutorial, WordPress’s default icon works.

Next we create a form that will send POST data to the options.php. This is where you want to send your POST data. In our form we call 3 important functions for our form to work with the WordPress settings API. The first function is settings_field() This function is absolutely important because it echoes out a couple of hidden fields for security reasons. It takes care of outputting nonce fields, action, adds a group for our settings API. This is referred to as our options group. The options group name depends on the string you pass into the function. This name can be anything you want, but it must be unique. In our case, we name it jk_social_plugin_options.

The do_settings_sections() is what will display our fields created by the WordPress settings API. It accepts 1 string and this string is the name of the page it’ll appear in. In our case, we use the __FILE__ magic constant to keep things unique and simple. Lastly, we use the submit_button() function which will output our submit button. We could just write it in HTML, but this function is shorter to write and easier to remember.

Let’s take a look at our jk_social_init_register_settings() function and add this bit of code inside of it.

Alright, we have 1 simple function to remember. This function is very important because it’ll allow the data submitted in our form to update our options. Let me explain, the first parameter MUST correspond with the name you used in the settings_fields(). This tells WordPress that any data from this form will update our options and nothing else. This is a security feature that will prevent any outside data from changing the options. The next parameter is what option this form will update. In our case, it’s the option we created on activation of our plugin which is jk_social_data.

When we created out options, we stored them in an array instead of separate options. If we had created 3 separate options, we would have to use the register_settings() function 3 times.

So far, we’ve added security and told WordPress that’ll we be updating the jk_social_data option when we submit this form.

Sections and Fields

The settings API is fairly simple so far. All we need to do now is display sections and fields. Sections are parts of a farm that help separate and identify the part of the form. For example, we could have a section specifically for YouTube settings and another section for Facebook settings. This makes it easier for your users to find and update your settings.  Fields are the individual field inputs you see in your forms such as text areas, check boxes, etc. You can have multiple fields in 1 section.

Let’s look at some code on how to add a section to our form. This bit of code should be inside the jk_social_init_register_settings() and under your register_settings() function.

Notice that I put comments to show where each section is. We only have 1 section, but we’ll be adding more soon. The add_settings_section() adds a section for our form. It has 4 parameters which are all required. The first parameter is the unique id for this input. You can set this to whatever you want, but it should be easy to remember. The next parameter accepts a human readable name for this section. This will displayed in our form. The next parameter is the function that should be called when this section is added. We’ll learn more about this function later. Our 4th parameter is the page that this belongs to. The argument in this parameter MUST match the same argument passed in the do_settings_sections() function.

Let’s define the function we called for in the add_settings_section() function.

This is fairly simple to understand. We’re echoing out some details about this section for our users to know. I also added the comment [S1] for us to know this is section 1 in our form. If you haven’t already, activate your plugin and take a look at what we’ve done so far.

Let’s update our jk_social_init_register_settings() function to this.

As you can see we’re introducing a new function called add_settings_field(). It takes in 5 arguments. The first parameter is the unique ID for this field. This can be whatever you want. The next parameter takes in a human readable name to be displayed in our form. The 3rd parameter is the function to call. This function will handle displaying our input field. The 4th parameter is the page this belongs to. This must correspond to the string passed in the do_settings_section() function. The last parameter is which section this belongs to. This must be the ID we passed in the first parameter when we create a section. In our case, this would be youtube_settings.

Let’s now create the function that will display our field. We must define this function that we called for when we added the field. Add this bit of code.

Nothing much going on here, but some things to take in. First, we grab the option jk_social_data and store it in a variable. We then echo out a regular input text field and the original value for our YouTube username.  You may notice that the name attribute equals jk_social_data[jk_social_youtube_username].  The reason for this is because we want to tell WordPress which option we’re updating. Since we’re using an array, we must also define which key in the array we want to update.

We’re done! Refresh your page and try updating your plugin. All should work. We’re done. No need to redirect, validate, sanitize, update and secure data. WordPress takes care of it all. All we have to do is display it with the right information. When we created this option, our array had 3 different values. Let’s update your file to allow our user to update arrays. We’ll also be separating these by sections so we can get some practice in . Here’s what your file should look like.

We’re doing nothing new here. We’re just copying and pasting code. Changing some values here and there. I also commented which function belonged to which section and which field. That’s it! In our next tutorial, we’ll learn a couple more thing about the settings API to wrap things up.

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 …

Leave a Reply

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.