 All right, welcome everybody. I hope you are having a good week. If you are joining us from wherever you are joining us in the world today, please do as you joined it. Let us know where you are joining in the chat. Maybe let us know a little bit about you, share what you do with WordPress. Do you build with it? Do you develop for it? Do you contribute to it? Do you do all of those things? And I will continue with my introductions. So my name is Jonathan. I am from Cape Town in South Africa. I am a developer educator at Automatic and I'm sponsored to work with the training team. The training team are the folks that help manage these online workshops and everything related to learn.wordpress.org, which is the sort of community learning website for the WordPress community. I am quite happy to say that the weather is starting to change in Cape Town. We had some quite bad storms over the weekend and it was like I was in the middle of winter and now it is back to being sunny and bright and warm. So that always puts me in a good mood. So I hope wherever you are in the world today you are experiencing a nice day. If you're not, I'm sorry to hear that. Okay, we've got Mark from my favorite town or city or place, Issaquah in Washington. I love seeing that name every time. It's always gives me, I have a lisp which over time I've learned to work around. It sometimes crops up when I'm recording tutorials and I hear it come up and it drives me crazy. So whenever I see Issaquah with two S's that gives me a little bit of anxiety. We've got Aaron coming in from Sacramento, California. Welcome Cynthia from Ontario, Canada. I'm always appreciative of folks who are joining me so early in the States. It's one of the reasons I do these workshops at four p.m. my time so that we can hopefully get more of a broad spectrum of folks from across the world. So welcome everybody. Please do continue to let us know where you're joining in the chat as you join while I continue along with my announcements. So today we are talking about the settings API. Last week we chatted about the options API, the settings API and the options API work well together. If you weren't able to attend last week's session, there is a recording of it which I will share with you in a moment. But today we're going to be focusing on the settings API and what that does. Want to start by welcoming everybody again and thank you to Tracy who is co-hosting here today. Tracy is such an experienced co-host that I don't even have to start up early. I just, I wait until a few minutes before the time, make him co-host and off we go. So thank you again, Tracy for co-hosting. Please let me know at any point in time if you can't see the slide that I'm presenting right now or any of the slides. So you should see my shared screen through the entirety of this workshop. So if you can't see my screen, do let me know and we will fix that for you. We are presenting in what's known as focus mode. So that means that Tracy and I can see all of your video but you can't see each other and that just prevents any kind of instances of Zoom bombing which we have had in the past. And as always, you're welcome to ask questions. You're welcome to post your questions in the chat. You're welcome to unmute to ask questions. I don't mind either way. I just ask that if your question is not specifically related to what we're discussing at the time, maybe to keep it for the breaks. I have breaks in between the session that I take to allow for questions and answers. So if you are able to keep it to that point, fine. If you can't and you wanna just post in the chat, that's also okay. Then if you want to code along with me, we're not doing a lot of coding today. There's gonna be a lot of shared code that I'm gonna share with you. I'm not gonna be doing a lot of live coding because there's quite a bit of code in a way that we need to get through today. So I'm gonna be doing a lot of sharing of code and you'll be making some changes if you want to. But if you want to do it along with me, please make sure your local WordPress installation is ready, you've got your text editor ready and you're ready to rock and roll. As always, if I start speaking too fast or if I'm jumping ahead too quickly and you want me to keep things on screen, please do let me know. Always happy to jump back if we need to. And then as you may have heard at the start of the session, we are recording the session that is recording now and the recording will be posted to WordPress.tv afterwards. I usually get it done on the Friday after the Thursday session, latest by the Monday. And then last but not least, just some URLs that I recommend checking out if you haven't already, there's learn.wordpress.org which as I mentioned is the Learn WordPress website. There is developer.wordpress.org slash news. I'm gonna copy this into the chat now which is a great developer blog which I recommend taking a look at. And then last but not least, this is a new link that I'm adding to my slides today, the 2023 annual WordPress survey is out. So every year, the WordPress project launches the survey survey to kind of gather what folks are doing with WordPress, how they're using WordPress. So if you're a WordPress user, WordPress developer, WordPress extender, WordPress contributors or whatever, if you're working and doing things with WordPress, I do recommend taking the survey. The more people that we can get to take the survey, the more we can hear what folks want and where they want WordPress to go and where they see WordPress going. So please do take, I think it's maybe 10, 15 minutes to complete the survey, please do take some time. I completed it every year. I have since 2015 or 16, I can't remember now. All right, I'm just gonna scroll back through the chat and just see where other folks are joining us from here today. So we've got Benjamin from Cologne, Germany, welcome. John from Chicago. Hello, Arthur from Frankfurt. Nice to see you again. We've got Sam from Amsterdam in the Netherlands, welcome. RJ from Rajasthan, India, welcome. Sonia from Iran, welcome. Wow, I've got folks from all over. That's amazing, excellent. Well, welcome everybody. It is great to have you all here today. All right, our learning art comes for today. As I mentioned, we're going to be diving into the settings API. We're going to look at what the settings API is and what you should be using it for. And then I'm very briefly, I'm not gonna be doing a very, very deep dive because there's a lot of information to go into. We're gonna be looking at how to add a new setting to existing settings pages. And then we're going to look at how we can create new setting pages for a theme or for a plugin using the same setting. Then I'm gonna show you very briefly how you can add settings error messages if the data is not correct when the user saves the settings. And then we're briefly gonna chat about the advantages and disadvantages of using the settings API. Because I think it's a good idea to understand where it's useful and where it's not so useful. I'm also gonna show you an implementation of the settings API that I worked on a while ago on my personal blog and kind of what is possible using the settings API. Tracy says, I finished the survey yesterday. Lots of questions that it goes fast. No math required. That's always a good thing when a survey doesn't require any math. All right, before we continue, it's my turn to ask you all the questions. So I just want to find out on a scale of one to five. One being you don't know much about the settings API. Five being you know everything there is to know about the settings API. You've used it to build setting pages. Where do you feel you fall on the scale? Just so I can get a rough idea of what we have in the audience today. We've got a couple of ones coming through. We've got a zero, that's always fun. A few more ones. And what is interesting about this is that I think this, so I've only started implementing this question from around, okay, Mark's got it too, from around June, July. It's something new that I added to my workshops. I do find that most folks don't generally need to know about the settings API. And because the reason for that is if you're using a theme that you're comfortable with and if you're using plugins that you're comfortable with, you generally don't need to add settings anywhere. The only time you really need to add settings is if you're building a plugin and that plugin has settings or if you're building a theme from, you're building a theme that you're gonna sell and that theme has settings. But often those settings are moved to other places. If we think about the customizer for classic themes, if we think about how the block editor works and all your settings and things can happen in the editor. So it's an API that is not that well known and that's kind of to be expected. It's an API that I don't even know that well, I'll be honest and I'll explain why it's towards the end of the session. It is one that you sort of, it's a use once and then you very rarely come back to it. You set up your settings for your plugin or your theme that you're building and then once they're there, very often or not very often do you need to make changes. So it's one of the sort of, I would say, less unknown APIs in the WordPress ecosystem. All right, just very quickly requirements for today. As I mentioned, local WordPress install, text editor, if you want to code some files, a way to access your WordPress database, you don't have to access your database today. We're literally saving one setting everywhere. So I'm just going to use, sorry, I have SQL buddy installed on my machine and I will use that to show you what's happening in the database. But if you want to install it on your side, you can do it as a plugin that allows you to inspect your database from inside your WordPress dashboard. I don't recommend installing this on production sites, installed on local sites or development sites only. If you do install it on a production site to check something out, then make sure you uninstall it, deactivate it, uninstall it before you leave the site. So that's what I'm going to be using today. My code editor is going to be VS Code and then we'll need an empty plugin file but I'll create the plugin file with you if you want to work along with me. I'll share the code that I'm using as we go along. All right, any questions? I'm going to grab a sip of water. Are there any questions at any point in time? Well, sorry, if there's any questions now, let me know. Otherwise, once I've had myself a water, we'll dive in, make it two sips. One thing I've become very comfortable at being in these online workshops is they're being silenced when I ask for questions. I used to be very nervous. Now I'm okay. All right, so the first thing, link that I want to share with you is the documentation on the Settings API in the WordPress Developer Documentation. If you don't know how to find this documentation, you basically, all of the developer documentation or most of what you would need is available at developer.wordpress.org. It has all of these amazing categories on the front. There is a section on common APIs. You click on Utilize APIs and then all of the APIs that we've been covering for the last few weeks are all listed down the side and the one we're working with today is the Settings API. So the Settings API was added to WordPress way back in WordPress 2.7. That's a number of WordPressers ago. It basically allows admin pages containing settings forms to be managed semi-automatically. And what it does specifically is it allows you to find settings pages, sections within those pages and fields within those sections. If we have a look at the WordPress Settings menu, which is this last menu on the left of your WordPress site, you will see if you hover over that menu or if you click on the menu item, there are a bunch of settings pages. There is the general page, writing, reading, discussion, media, permalinks and privacy. Every single one of these pages is managed by the Settings API. And then underneath the hood, it is powered by the Options API that we discussed previously. Now, as I mentioned, if you weren't in the workshop last week where we did the Options API, you can watch this workshop. It's all about how the Options API works and it was sort of the four core functions. So adding an option, updating an option, fetching an option or getting an option, get option as the function core and then deleting an option. Those were the four core functions that we looked at. And as I mentioned in last week's sessions, the Options API specifically just handles the storing, updating, deleting and saving of the data. So what the Settings API does is it manages the creation of the settings user interface. So in other words, the fact that this has a site title label, the fact that this has a field, the fact that the field gets posted when you hit the Save Changes button, what happens to that data under the hood when you press Save Changes? It does some checking, some validation, some permissions checks. It then uses the Options API to store it to the database and then it uses the Options API to also show the value in the form when there's a piece of data saved. So that's how the two work together. Where are we? There we go. You'll see that it says that when using the Settings API, this is the note over here, when using the Settings API, the form posts to the wp-admin-options.php file. So every time you're using the Settings API, that's the file that manages when you post that form, it all goes to the same place and it provides fairly strict capabilities checking. So your users will need to have the Manage Options capability and in a multi-site, they will need to be a super admin to be able to submit the form. So that's why whenever you're building settings interfaces, you will generally use the Manage Options capability. Manage Options is generally only available to administrators. And so if you need users with a lower capability level than an administrator to be able to manage your settings, you're going to need to work with those changes as well. You might need to add a new capability and then allow that capability to manage those settings. By default, they need the Manage Options capability. Then below that, we have the Function Reference and it's basically a case of registering and unregistering settings. Then adding settings sections and settings fields. Then you've got what's called the Options Form Rendering, which I'll show you in a second. And then you can also specify errors. Now, when you try and read through this documentation, it can be very difficult to kind of understand how everything fits together. And so what I've found whenever I'm thinking about the Settings API and thinking about how these things work is I find it easier to show sort of a full section of code, which covers adding a setting to one of the settings pages and then diving into that code as we go along. So that's how I'm going to start. So I'm going to open up VS Code, which is my code editor. I'm going to go inside of my WP Content file, inside of my Plugins file and I'm going to create a simple file called WP Learn Settings. Using hyphens in between the name, WP-Learn-Settings.php. Inside of that file, this is basically going to be a plugin that we're going to create. So I'm going to start by adding a plugin header. I'll share it with you in the chat before I paste it in my file. If you've never seen a plugin header before, these are basically the fields that WordPress reads from the file to determine whether or not this is a plugin file and the bare minimum you need is plugin name, but I always like to give a version and a description, just so that I can see the plugin in the WordPress dashboard. With that in the file, so as long as the file is inside of the Plugins folder, with this content, if I now go to the Plugins menu item, the Plugins page, should I say in my WordPress site, there I will see the WP Learn Settings plugin. I can then activate this. It doesn't do anything right now. There's no code in there. You'll see there's the description and there's the version. That's why I put them in because then it shows something in the plugin list. So I'm going to activate this now. The plugin is now active, so any code that I start adding to it will become functional. Then I'm going to paste a whole bunch of code, all at the same time, but we're going to dive through it together. So the first thing I'm going to share with you in the chat is this, and then I'm going to pop it into my code editor here. And I'm going to go through what each of these steps does. So the very first step is I'm adding an action callback. This is the callback function to the admin and net action hook. So when you're setting up your settings, setting up your settings, I'm going to be very redundant today. You need to hook it into an admin hook. Ideally, the admin and net action hook needs to be fairly on in WordPress admin code execution. Then I'm creating this callback functions. I'm saying when the admin and net hook loads or fires call this callback function to do my custom code. Then here is the function. I'm just carrying it with a name there. And this is the code that we're working through. The very first thing that I'm doing is adding a section to the general settings so that we can add our fields to it. And the function that I'm using is the add setting section function. So let's go and open up that function in the WordPress developer documentation. I'm actually going to open up a new tab so we can have the code reference. And I will share this link with you as well. There it is, add setting section. And there is the link. And you will see that the parameters for this function are the ID, which are required at least, are the ID, the title, the callback function, and the page that needs to be added to. There is also an additional arguments parameter, which is optional. It's an array of data that you can send. We won't be using that today, but it's a good idea to read through that and see how it does. Basically, the ID is the slug to identify the section, so you need to define that. The title is the title of the section. The callback function is the function that you'll create that handles whatever that section does. And the page is the slug name of the setting page in which you wish to add it. So if you remember, we looked at those settings pages earlier, they were general reading, writing, or writing, reading, discussion, media, links, privacy, and in setting section, the options are general reading, writing, discussion, media, et cetera. So that's the code that we're going to be using. So here we are saying, right, the slug for this section, we're going to be calling it WP learn setting section. So we need to remember that. This is the description that we mentioned, example setting section in general settings. This is the callback function that's going to be fired when the section gets added, and then we're adding it to the general page. So that's what that code does. The next bit of code uses the add setting field, add settings field function. So let's open that up. And I will share that with you in the chat as well. So what this does is this adds a new field to a section. So this also has some parameters that are required. It has its own ID that we need to define. It has its own title. And again, it has a callback function. So we've got a callback function calling another callback function. We also have the page that it needs to be added to. And then there are some additional option ones. There's a section and there are further arguments that you can add as well. So we just need to focus for now on the required parameters. So if we have a look at the code, they will see WP learn setting name. So they're setting section, they're setting name. I'm using this WP learn setting sort of prefix. You could call it anything you want. I'm sticking with WP learn as the prefix and then setting as the project we're working on. So that's our ID there. Then again, we've got some English text in this case. You obviously if you're building this for a plugin you want to make this translatable, you would use the internationalization functions. I'm not doing that today. And then here we specify the callback function that fires when this piece of code happens. You'll see we're also adding this to the general page and we're adding it specifically to the learn setting section that we defined up here. So here we created the section and gave it an ID and now we're adding a field to that ID. And then we're saying, let's register a setting. That's the last sort of step we have here. So let's open up register setting and see what that does. There we go. And I will share that with you too. So register, register the setting and its data. So the required parameters are an option group and an option name. And then it also has some additional arguments which you can use if you need to. So in our case, I keep clicking on the wrong one. In our case, the option, which one was that? The option group was the same as what we set on the section general and on the field general. So that's the option group. And then the option name or the setting name in this case is the settings field that we created. So we tie those two together. With this code, you may expect that something might happen with this code. So what I'm going to do now is I'm going to go back to my WordPress site. And I'm going to, if you remember, we said we were adding this to the general page. So I'm going to open up the general page at this point in time. And if we scroll down to the bottom of this page, there we can see something has happened. It's added the example settings section in general settings, which is, there it is there. And it's added a critical error to the website. Okay. And I wanted it to do that on purpose. So if you have a debugging on now, you can go and have a look at your debug log. What is the date today? Today is the 28th. And you would see that there is an uncord type error call user function. Don't worry too much. The reason that's happening is because we've specified these callback functions, but we haven't actually specified the functions themselves. So now we need to create them. So the first thing we'll need to do is we'll need to create the learn setting section callback function. So let's do that outside of this function. So we'll say function, learn setting section callback function. And then we'll also need to learn, that's the section and this is for the setting. So we'll also need that function to happen. So function there and there. Let's, why is this one giving me an error? Oh, because I can't spell the word function. There we go. All right. Now let's look at what these two functions should do. So the section callback function, the learn setting section callback function, essentially just needs to echo some kind of content. It doesn't do anything related to fields. You would just want to use it. You don't, I don't think you have to even call it if you want to, you could probably return null to that function, but you would use it to include some kind of description about what the setting section is all about. So that's what we would put in over there. In the setting callback function, the one that was added to the setting field, that is where we want to actually manage our actual settings interface. So in other words, the input form or the checkbox or the text field or whatever for the setting. So in there, we could do something along the lines of this. Just going to grab this code for my example or dive into it in a second into what it's doing. But here you will see that I'm echoing an input. It has a name, which is the same name as the setting that we defined. It also has an ID. It's of a type checkbox. It has a value of one. And then it has some other properties and parameters which we'll dive into in a second. It also has a label, which is for the setting and it has some text within that label. Now, if you've never worked with HTML forms before, some of this might be brand new to you. I do recommend going on to something like the MDN developer docs, Mozilla developer docs or Google has a web.dev page as well to learn about how HTML forms work. But essentially your primary sort of field that you need for a form input is the name property because that's what gets posted when you hit the save button and is what then gets processed in the background. So this is kind of the least amount of code that you might need. In case you're wondering where I got this code from, it's right at the bottom of the, where is it now? Right at the bottom of the settings API page that I shared with you earlier, there is a big bit of example code. This is what we're going through today. And there's also a graphical representation of where everything goes. But I'm trying to talk you through it today so don't worry too much about that. With that in place, now we should see this intro text and we should also see this input field. So let's have a look. And there we go. There is our intro text. There is our field. You will notice it's specified as a checkbox. So that's great. There is the sort of title that we're set up. You see it says the example setting name, which is what we have set up there, example setting name. And then the label is explanation text, which appears after the setting field there as explanation text. So that works, that's great. The wonderful thing is once you've done all of that, you don't have to do anything else. You don't have to worry about inputting form data. You don't have to worry about processing that data, implementing sanitization, validation, anything like that. Once you've added the field, the field will now work. And I wanna just prove that by first of all opening up the SQL buddy page. So we're gonna go into SQL buddy quickly and I'm gonna go into my options table, which is as I mentioned last week, options is the table that where all the settings get stored. And I'm going to search for where option name contains WP underscore learn. Cause that's what the setting name prefix includes. And I'm going to apply that. And we get a test option and a test option array, which were the ones I was testing last week. But there's nothing in the database related to WP learn setting name, which is how I expect it to be saved. So because I've set this all up like this, if I now go into this general settings and I hit the text box and I say save changes, it saves all of the fields on this page, including my explanation text. So let's verify that, let's apply this filter again. And there is WP learn setting name. It stored a value of one, which is what we expected because we specified it to have a value of one. And then when the page loads, it also gets the setting value using get option and displays it as a tick box. And what's handling that is this code over here. So this code is a built-in WordPress function. I'm going to share that with you in the chat as well. And let's do a search for checked. And in case you're wondering why I don't have these on hand, it's because I like to show how to search and develop a documentation. So checked is a function in WordPress that you can use when you're working with check boxes. It will outputs the checked attribute, which is an attribute that you can apply to a check input box. And it will compare the first two arguments if they're identical, it'll mark it as checked. So in this case, it's using get option to get WP learn setting name, which is the same setting name that we defined the slug there, the ID, should I say. It then compares it to the value of one. If it is equal to one, then it returns checked. If it's not, then it returns not checked. So if I go back into that field and I untick it and I hit save changes, we will see that there is nothing there. And if we refresh, I'm actually going to make this learn setting name now. So we can just focus on that one. Learn setting name. There we will see it is now an empty value because it wasn't ticked, so it saves it as an empty value. All right, so that was adding a setting to a specific page. You will notice that it's quite a large chunk of code. So you need to add your section to your page. You need to add your field to your section and you need to register your setting. If you don't register the setting, then it doesn't save when you hit save on the button. You don't, as far as I remember, I'm actually just going to comment this out now. I don't think you have to use the callback function information. Yeah, I just want to test this very quickly. I should have tested this before today's session. So let's just give it a quick refresh. Yes, you don't have to do anything there. In fact, I think you might even be able to, let me go back to the code. Let's check its settings field. It's the settings section. Settings section. I think it is a required parameter. So it was at settings section. And yes, so the callback is required. You do need to specify it, but you can leave it as an empty function like this. And it just won't output that information, but it is useful to use for sort of a descriptive text about what the section does. I think you can also, let me just check, I think you can also remove that code and it'll just work. And obviously it won't render anything, but I think that would also work without throwing any errors. There you go. But obviously you're going to want to have, you wouldn't register a setting in a section to not have a field, but it is good to know that you can do those things. All right, I'm going to take another break here, grab a sip of water, check if anybody has any questions before we move on to how we could actually create our own page to add the setting field to. Okay. So now we know how to add a setting to a page. We could move it around, we could look at this code and we could change all the general options and move it to reading, whatever the case may be, to be able to add it to a new page. So we want to create our own page and manage the setting there. We would use a function called, I'm just going to find it here quickly. There we go. And I'm going to open up the function here. We use something called add submenu page. So add submenu page allows you to add a page to a top level menu page. It is recommended that if you're going to add your own pages to your own settings pages, to your WordPress plugin, that you don't register a new top level page. So if you're not registering something that already registers a new top level page, it's better to add your custom settings page to the top level settings page in the WordPress dashboard. You'll notice and this is something that I want to give the folks who develop SQL Buddy for recommendation. Can't think of the word now, but you'll notice that the SQL Buddy menu item is added to the tools top level menu, which is the right place to add it. So it means you're not adding multiple menu items and cluttering up your menu, you're adding it to existing pages. You can create a new top level menu if you really, really want to, but try and use an existing top level menu if you can. So to add a sub menu page, this is the function that we call. It has a slug that we need to define. So it's the slug name for the parent menu that we want to add it to, parent slug. There's a title we need to set up, a menu title we need to create for our new menu item. There is a capability string that we need to define so we can decide what type of user can access this information. And then we need to give the menu a specific slug so that we can add our sections and our fields to it. And then we have the callback function, which is the function that actually determines how this page works. You'll notice that the callback function is an optional parameter as is the position. So we'll dive into how that works in a second, but let's have a look at the code. So to be able to register sub menu pages, it is recommended to add them, or at least add the callbacks inside of the admin menu action hook. So I'm gonna just scroll right to the bottom of all of this code, and I'm gonna move this down a little bit here. So this is kind of what it would look like. So you would again be hooking into one of the WordPress action hooks, in this case, admin menu. That's one of the hooks that fires when the menu is built up. And then you would create your own callback function. So in this case, I'm adding a sub menu page. There is the function definition. There is the same function name. And then I use add sub menu page in that callback to define my sub menu. You'll notice that I'm specifying the options general.php page there. So that's the page that I wanna add it to. That's the slug name for the parent menu, or the file name of a standard WordPress admin page. So you can use both. The second and third parameters are the page title and menu title. So to give a little bit of a differentiation, what I'm going to do, let's see here, page title and menu title. So I'm gonna make the menu title menu and the page title page. So we can see how it renders differently on the front end. Or at least in the dashboard. Capabilities, if you remember I mentioned earlier, to be able to manage settings, you need to have the manage options capability. So it's a good idea to use manage options for your sub menu pages as well. And then the next two parameters are the menu slug. So this is now the slug for this menu. So we can just call this learn settings. And then the callback function. So because it's optional, I'm gonna take that callback function up now. Just for the sake of being interesting. And with that code, I'm gonna refresh the page and see what it does. So let's just go back to the dashboard, for example. Like it hasn't broken anything, no critical errors. If I mouse over the settings page there, it's WP learn settings menu. So that's the menu that we've set up. If I click on that, nothing happens. And that's because I haven't defined that callback function. So it would at least add the menu for me. It'll at least add the menu item. But then when I click on that, nothing will happen. So for something to happen, I need to define that callback function. So we'll pop that back over there. Then for this to work, we need to create that function and actually have it do something. And for a settings page, there is code that you can use and this is shared in the settings handbook that I showed you. If we scroll down to the options form rendering, there is this code over here. This is essentially what we're using, which I will show you now in the plugin. So what I need to do now is I need to create my callback function, my learn settings page callback function. So we say function WP learn settings page. And inside of that function, I need to do a few things. I'm gonna just paste this also, you can see it and then we'll talk through it. Let me share it. Oh, I've pasted it twice. Sorry folks. I also realized I haven't pasted the submenu page stuff either. So I'm gonna do that as well before we continue. Let me grab all of the submenu things. I will share it in the chat. All right. So the callback function does a few things. The first thing that I'm doing here and this is there's pros and cons to both sort of options. The one way to do it, there's a couple of ways you can do it. The one way is close your PHP tags and switch back over to HTML, standard HTML, and then reopen your PHP tags after the HTML. That's one way. The other way that folks like to do it is maybe put the HTML into a template file that you include and do it that way. You can use output buffering, which is a PHP thing that you can do which sort of captures what's being sent to the browser. Some hosts don't enable output buffering. So that's maybe also not a great way, depending on the host, sometimes it's a problem. But yeah, there are multiple ways of doing it. This is not the way I necessarily recommend. For me, it's a case of do it based on your requirements. But in this case, what we're doing is we're outputting a div with a class of wrap and then we're doing a header tag. In this case an H2. We're creating the form which posts to the options.php page, which if you remember very early on, I said that's where all the settings get posted to. And it is a post method because we want to post the full data. And then these three fields are the only things we need to output. So we output all the settings fields that is tied to the learns settings fields group. We do the do settings sections, which is again, WP learn settings. So in other words, all of the settings sections that have been set up. And then we output this a bit button. So that's all we need to do for this to hopefully work. So let's see if this has worked. If I go back into my dashboard and I hit refresh. Now if I go down to my settings menu, first of all, I want to show you in the general that the example setting is still there. Let's go to the learn settings menu. And there we go. So we see the learn settings header. We see the save changes button. If we inspect this, I'm going to right click and click on inspect. So it opens up my developer tools and I'm going to move this over and then just zoom in a little bit here. So we can see this a little bit bigger. You will see it has, there is the div class of wrap. If you don't specify the wrap, then it's not exactly the same as everything else in your WordPress dashboard. There's the header that we've output. There's the form. And then what it does is, so this settings field function call, essentially outputs a bunch of hidden fields. The one is the option page. The other one is the action. And the third one is the WP nonce, which is a security check that allows you to, when the data is posted, WordPress checks isn't coming from a trusted resource. You'll also see there is a WP HTTP referrer input type hidden, created, which basically says it uses this value so that once it's posted and saved the data, it'll redirect back to this URL, which you'll notice WP admin options general.php page, WP learn settings is the same as this URL here. So when you hit save on this, it'll go to the options.php, do the checks, save the data, and then return back to this page. Then because we used the submit button function, it'll create the submit paragraph class with the submit button for you, with all the required styling and all of that. So that's great. That gives us a form that we can work with. But the problem is we're not seeing any of our fields. And that is because the, as you saw earlier, the fields are still registered to the general page. We want to change that. And we want all of those fields to be moved to our new learn settings page because when we are rendering the settings fields and do settings sections, we're calling it on this WP learn settings. So what we would then do is we would change everywhere where it says general to WP learn settings. So there'd be WP learn settings, there'd be WP learn settings, there'd be WP learn settings. And that's the only change we need to make. The callback will still work, the callback function will just work, it'll just move everything into our new page. So I'm gonna copy all of this up for you so that you can see those changes if you would like to. Otherwise, let's take a look and see if that works. So let us refresh this page. So there we go. There's our section that we created. There's our setting name, our explanation text. If we click on the general settings page and we scroll to the bottom, that field has been removed because we moved it to our new page. And if we click back there, there it is. You'll also notice that I couldn't, I didn't test it because I didn't move it back. We can do it in a second. But whatever's been saved to that setting is saved to the setting name or the option name in this case, not the section or the page it belongs to. So let me show you what I mean by that. If I, I'm just gonna revert these back to being in the general page and we will refresh this, go back to general. And I'm gonna now save this as checked. So there it is checked. If we view that in the database, it is a value of one. If we now revert this back to learn settings, so it's all grouped in the new page and we hop on over to that page. So I'm gonna have to go here now. So wrong one. I'm going to have to go there. You will see that the value is still saved. So the value of the settings field is tied to the field name, not the page or the section it belongs to. So you can move things around and it won't affect the functionality. All right, any questions on all of that before we continue, I'm going to stop for another sip of water. I'm gonna leave this in the screen if anybody wants to see it and then we will move on to the next section, the last section, shall I say? Right, we don't seem to have any questions. So the last thing that I wanna share with you is the fact that you can add error messages. Now, the reason you might, so you will notice that when I save these changes, because I'm posting to the options table, it automatically pops up a little admin notice to say the settings have been saved. But I might want to include some kind of user messaging if something is not the kind of format that I wanted it. For example, if I wanted a string for a certain field to be in a certain way or I wanted to validate a certain bit of data, I would want to be able to show the user that hang on, you're not including this data incorrectly, you're not saving this data incorrectly. So what I'm going to do for this one is I'm gonna make it a requirement that when you go to this page, you have to save this field. So to do that, I use the add settings error function. So let's go into the documentation and I'll show you what that tells us. So add setting error, registers a settings error to be displayed to the user. It's part of the settings API. It's used to show messages to users about validation problems, missing settings or anything else. Then it says settings errors should be added inside the sanitize callback function defined in register setting. So if we go back to register setting and we go and look for the sanitize callback, there it is there, you will see it's part of the arguments array that you can pass to the register setting function. It is optional for you to pass that. There is a default sanitize callback that runs anyway, but you can specify your own and essentially your own callbacks will run over and above whatever is happening by default. So the first step is to add that callback to register setting. So I'm going to scroll to the top here and here is the, where is it now? There is the register setting call. I'm going to make this a little bit easier to read. I'm going to move things around a little bit just to move the first two parameters on their own line. And then I'm going to create the third parameter. So after this, I'm going to pop in a comma. And as we said, this is an array of values that we can pass. So I'm going to open up an array and I need to specify the sanitize callback item in that array. So this is another callback function that I'm creating. So I need to create a brand new function for this. In this case, I'm simply going to stick with my prefix and everything else that I've been using so far. So it's going to be WP learn setting sanitize callback function. It's also a good idea at this point in time to define the type of the data that you're storing. So because I'm storing either a one or an empty and if you remember from, if you were in the options API workshop, you'll remember that while it stores it as a string, you can store ones and zeros for true and false. And then you can set that up. So that's what's known as a Boolean. So it's a good idea to also specify the types. In this case, I'm going to specify it as a Boolean so that it knows what to work with. Once I've created that, now I need to create this WP learn setting sanitize callback function. Now where you put this is entirely up to you depending on how your plugin is structured. If you're using a more procedural system, which is what I'm doing now, all of these functions in the main file, I generally like to add it after the setting callback functions. In other words, after where the setting field is being output. So I'm going to pop this in over here. And then inside of that, that callback function will receive a parameter which will be the value of the data being posted. So I'm going to call that parameter input. You can call it whatever you want, but that will be either the one or the empty string if the checkbox isn't checked. If you know HTML form fields, you give a checkbox a value. If it's checked and the person had submit, that value gets posted. If it's unchecked, then an empty string gets posted. And then in here, what I can do is I can say if the input is zero. There's a whole conversation we can have about empty strings and ones and zeros, but for now, this is what we're going to use. And then in here, we can add the error. So we're going to use the add settings error function and we're going to pass the required parameters. So in this case, the parameters we need are the setting itself, the slug of the setting, the code parameters, which is the slug name to identify the error, the message that we want to output to the user and then the type, whether it's an error or a warning or anything like that. So in our case, we can do this. We can say WP learn setting name is the setting name that we've been using everywhere. When we registered the setting, that was the name of it. Here it is over here under register setting. Then this is the slug for this error. Then we're going to give it some kind of message. In this case, we're just going to say please check the checkbox and keeping it super simple. And we're going to say it's an oven error type and the type that we define there will determine how it displays. So that's all what we're going to set up. So I'm going to copy the register setting, the updated version of register setting for you in the chat if you want to grab that and then I'm also going to copy the WP learn setting sanitize callback function. So you can use that. And to see how that works, let's hop on over to our settings page. It was checked the last time we did it. I'm going to move developer tools just out of the window. If I now try and uncheck it and I hit save changes there, it shows me my error message. Please check the checkbox and it shows a little red on the side because I specified it as an error. If I change that to something else, let's try sorry, that's the wrong page. Let's try warning. Then it would show a different color. So let's just show you that. Then it shows the orange color. So depending on how severe the warning is you can change the warning type. This uses the admin notices hook which I haven't done a workshop on yet but it basically it's how you manage notices inside of your WordPress dashboard. Okay. This is a very simple implementation. You probably should be doing a better check on the input. I'm just using that as a quick cheat. Because you know it's one or an empty string you should probably be checking for is not equal to one to get the correct result but this does work. So that's how you can do some kind of checking on the data to make sure that the right kind of information is being stored. All right. Any con, any con. Any questions on how to add settings errors? Before we dive into what I consider to be the pros and cons to using the settings API. Okay. Two things I wanna mention before we dive. Actually, let's chat about the pros and cons and then we can dive into those things. So the advantages, the pros of using the settings API. Number one, you've got automatic validation and sanitization. So all I had to do was specify the right, where was it? The right capability on the submenu page so that nobody can access that page without the correct permissions. I didn't have to do anything else with the settings. I didn't have to specify who can manage those settings. It's automatically built in by default. I didn't have to do any kind of validation of the data being posted to the form. It happens by default. So that's one of the advantages of using the settings API. The other advantage is it's automatically saved to the database. I didn't have to worry about saving the option using the add or update options API functions to be able to save it to the database. It's automatically added in the way I wanted to be added. And then finally, by using the sections and the pages, it automatically adds things to the settings area for you. You don't have to do much in the terms of layout and that kind of thing. All you really have to do is specify your settings page layout. And then you just use those three fields and it all just works. And then you have to specify your settings HTML for each setting that you create. The disadvantages, well, one of the disadvantages is what I just mentioned. You have to create HTML for every single setting you want to use. There isn't a way what, and I remember, I still remember to this day, the first time I discovered the settings API it was at a live workshop at a WordCAP. And I saw the person writing this code in the callback function. And I remember asking the question, well, why not just have another function? In this case, for example, that does something like this, that does a echo checkbox and then you pass in the name, for example, and maybe the value, maybe you don't even need the value, I don't know, whatever the case may be. And then it then handles, maybe not the value, maybe the name and the explanation text for the label, that might be a better option. It handles whether it's a one or a yes or a no or whatever. It handles the HTML, it does everything you need to do. So WordPress doesn't have any kind of fields API like that. That to me would make things a lot easier, but there is some work happening. It's a project that was kicked off, I think it was in 2018. I'm gonna share this with you here. I think it was in 2018, they decided to kick this off. The idea is that they would like to create a unified PHP API to work with any screen that has a form on it. And the goal in fact is actually to, if you have a look through the information around this, the goal is to almost remove the requirement of using the settings API. So you would just define a setting and you would define where it should be. And then you wouldn't have to do all that other settings API callback stuff and putting things in different places. You would just use the fields API for that. So that is something that is currently been working on. It was restarted this year and that's currently being worked on regularly. You can go to, I'm actually going to share that link with you as well. If I can find it. All right, I think it's at the bottom of this. Yeah, here we go. So if you go to, I'm gonna share both of these links with you in the chat. If you go to make.wordpress.org forward slash call and you search for all tags with the word fields API, you will see the regular meetings that folks are hosting. Let me just hide that. And the updates, the last update was about two weeks ago that Scott posted. They've got a core fields Slack that they chat in. And if this is something you'd like to get involved in, if the idea of building out the fields API is something you're interested in, I do recommend getting involved with Scott and the other folks there and seeing what you can do to help. It excites me to see this happen. My, I haven't dived into what they're doing, but I have a feeling you're probably gonna get to a point where you're gonna go setting field and that's it. And everything else will just happen magically for you, which would be pretty amazing. So that's what I think they're going with that. Then the other disadvantages, you don't really have a lot of control over the user experience. So it's both, in my opinion, it's both a pro and a con. In the WordPress dashboard, you do kind of want things to look the same, but if you really wanna sort of give your users a better experience, you might want to build something yourself. I'm gonna use SQLBuddy as another example here. So SQLBuddy is developed by the folks at Delicious Brains. I had the privilege of working with Delicious Brains for about a year, two years ago. And as you can see, they've built their own user interface with us. This is all React-based as far as I remember and they've done their own thing. And it does look really, really slick because there is no sort of style book if you will for new settings pages using these new React APIs, it kind of deviates slightly from the WordPress sort of defaults. If you think about the block editor and what's happening there, but I do see it getting to a point where that will be possible. What excites me about the fields API is it might be possible one day to register your field and then it becomes available in the block editor somewhere and you just have this cool new interface. So that also excites me about that. And then last but not least, one of the disadvantages is if things go wrong and I've had this a few times, if you're saving a setting and you're setting up an error message and you're checking for the wrong data type and you're not sure what's going on, you don't have control over that code in the options.php file to be able to debug what's going on. So then you have to dig into core files. If you're not somebody that has something called step debugging setup with something like xdbug, you have to start echoing variables in the options.php file in the core file, which is not great. So it can be tricky sometimes trying to sort of debug these core issues when you're working with a settings API. In my opinion, there's no right or wrong answer. I've worked in both the settings API and in the block editor. So they both have their pros and cons. I do think that there is a space for the settings API to be used, especially for like a small group of settings. So it's good to know how it works if you need to add settings to WordPress. Maybe even if you're just adding a setting to like the general section or the reading section or the writing section, it's a good idea to understand how it works and what it does. As you can imagine, if you look at this code, we've added one setting today to one page and that is with one error and that's 93 lines of code. So it's a lot of code that you have to write just to get one setting down. What some folks have done, some plugin developers around the world, different plugin projects, they've sort of created their own fields API, if you will. And one example of that that I wanted to share with you, if you're ever building your own plugin, a colleague, ex-colleague of mine, he used to work with me at Automatic. We used to run the WordPress Cape Town Meetups together. His name is Hugh Lashbrook. He developed this WordPress plugin template. Now the template itself hasn't been updated in a while. So I wouldn't recommend using it for everything today. But what I have used quite a bit inside of this template is there is an admin API.php file which essentially creates a whole, there's basically a display field function. And it has a, so what you do is you set up an array of fields. So you say, I want five fields and you create this array and you give them a slug and some description of text and what type of field it is. And then using this template admin API, it loops through that array of fields. And then based on the field type, it echoes the HTML for you. So Hugh has done quite a bit of work on building this app so that you can use it and you don't have to worry about managing the HTML of yourself. So I do recommend downloading this code and checking it out just purely for that. I have been thinking about extracting the settings part from this and turning into something that you could easily just drop into a plugin somewhere and use, just haven't had the time for it. But if you want to build a settings pages and you don't want to have to write all that code all the time, I do recommend checking this out. One of the plugins that is following this process and I'm going to log into my site very quickly is the seriously simple podcasting plugin. I've mentioned this before in my sessions. In case you're wondering, yes, Hugh was the original developer of seriously simple podcasting as well, which is why his template code was used in the plugin and he uses it to manage all of these settings. So he's got all of these tabs across the top so you can create settings tabs and then sections within tabs and then all of the settings in there. And essentially, whenever you need to add a new setting, you just go and find the array that sets up all the settings, you find where you want to add the new setting, you just pop in a new item, give it a slug description and a label and then it renders itself on the backend. So it is possible to use that to sort of build more robust settings pages that you don't have to manage yourself. And then at least if you need to debug things, it's code that you're owning. Okay, so those are my things I'm gonna share. I think I did share that. Yes, I shared the plugin. So there we are, good to go there. Awesome. That's my bit for today. Does anybody have any questions on all of that before we wrap up? Hopefully if you were a zero or a one or a two, your knowledge has increased a little bit today. If it hasn't, let me know. If you didn't find anything interesting here today, please let me know. There don't seem to be any questions as far as I can tell. So I'm going to wrap that up here and I'm gonna say thank you very much for your day. I hope you enjoy the rest of your Thursday and the rest of your weekend. And I will see you again next week when we'll be doing something else. Thanks very much.