FREELessons: 13Length: 1.7 hours

Next lesson playing in 5 seconds

  • Overview
  • Transcript

2.2 Creating a Settings Section and Field

WordPress has something called the “Settings API”. This allows us to create settings, store them in the database, create sections for grouping those settings, and create fields for displaying them. Let’s get started.

2.2 Creating a Settings Section and Field

WordPress has something called the settings API and this allows us to create settings and store them in the database. It also allows us to create sections for grouping those settings and also create controls or fields for displaying those settings. So let's begin. And we'll start by tapping into some existing WordPress functionality to register our settings. We're gonna use the admin_init hook to load a custom function. I'm gonna go right here. What I like to do in these files is just separate each individual section by a three or five blank lines. That way, it's much easier to scan. So in here, I'm gonna say add_action just like we did above to create our menu. We're gonna say admin_init and this is the hook that we're gonna use. And we're gonna load a function called ap_init_settings. Now, whenever you're using functions like this make sure they have a unique name, just so you don't run into conflicts with function names from WordPress or even other installed plugins. What I usually do is say, ap, just prefix all these functions with ap_ AP stands for my name, but you're free to do anything you want really. Just make sure that these functions have more unique names. Now, let's go ahead and create this ap_init_settings function. I'm gonna say function ap_init_settings. Don't have any parameters for it. And this function I'm gonna write a little comment here. It will register and add, settings, sections, and fields. First of all, let's register a general setting. Now, what you can do basically have two ways, you can either register a setting for each field or you can register a general setting and all the field values will go into that setting. It's a process called serialization. I thinks it's called serialization. Basically, you need to serialized those values to go into your one setting. So, to register our general setting, we're gonna say, register_setting(), this is a WordPress function. And we're gonna pass in ap_options, this is the name of my setting. And then oops, the second parameter is also ap_options. And I'm gonna show you why that is in just a little bit. So these two are the same and finally the third parameter is called ap_options_validate. Now let's take a look at this register_setting function in the WordPress codex. register_setting receives an $option_group, an $option_name and a $sanitize_callback. So the $option_group is the setting's group name. $option_name, pretty straightforward, is the name of the option. $sanitize_callback is the name of the function it can use to sanitize or validate that setting value. Now the reason $option_group and $option_name are the same is to prevent an existing error that will basically tell you that options page not found. This is a problem that's documented by WordPress and they actually recommend that these two parameters are exactly the same. So let's add a quick comment here and say the reason why these two are the same value. So now we have just registered a setting. Now just because we registered the setting doesn't mean it's already in our database. So a quick way to check that is to open MAMP, if you're using MAMP, if not any tool that you use has some kind of PHP my admin. So you would click web start and that's gonna open the MAMP or the tools interface. And then just search for phpMyAdmin > go to WordPress > open the WP options table > go to browse and in here you're gonna see all the options that are saved by WordPress. And I'm just gonna show all of the rows here. Now if we scroll all the way down, you'll see that we don't yet have our option. We'll check back in just a little bit. Now to group certain settings, we need to add sections to our options. And the way to do that is with the function add settings section. If we take a look in WordPress, add settings section takes four parameters, an ID, this is basically a unique identifier, the title of the section, the callback function used to render it in the HTML page, and finally the page we're gonna be displaying it on. Under here we're gonna say Add sections. In my case, I'm gonna add a single section, so I'm gonna say add_settings_section. The id is gonna be general-section. The title, let's call this general settings. The callback, we're gonna write a function called general_section_callback. You can call it whatever you want. And then the page is going to be this one, ap-theme-options. We're gonna grab it directly from add_theme_page and we're gonna paste it right here. Now of course if you have more sections you would add them just like this one but with different parameters. Finally, let's go ahead and add a field for displaying this setting. So for the field, we're gonna use a function called add_settings_field. And add_settings_field, will take a few parameters actually, it's gonna take a unique identifier, a title, a callback function for rendering that field in HTML, the page it's gonna be displayed on, the section, and finally, some optional arguments. So, we're gonna say add_settings_field. The id is gonna be ap-test-field-1, title Test field 1, callback is gonna be test_field_1_callback. Of course, this is not necessarily a good name, I'm just naming it like this so that the tutorial is more clearer. The page we're gonna be displaying this field is just like the section ap-theme-options. The section we're gonna grab this id here general-section. And finally, args is optional so we're not gonna use it here. But args is basically the list of arguments you can pass on to the callback function to this one, test_field_1_callback. So now if we do a refresh on our page, nothing happens basically, because all we did was register a setting, a section, and a field. But the callback function that's responsible for rendering that field on the page, is not written yet. We'll do that in the next lesson.

Back to the top