An options page is essential to any plugin or theme that requires the end user to enter or modify custom information. Even if you just want to display some instructions, an options page is still a good idea to incorporate into your software. Luckily, the process is not difficult for beginner developers with prior experience in HTML and PHP. All you need to do is register the settings and page, then create the page itself. For clarity in your code, it might be convenient to place all of the following code into a separate file, possibly called options.php or admin.php, and use the
function in your main functions file to run the code for the options page when needed.
Registering the Settings and Page
As with most development for WordPress, you have to tell WordPress what you are going to do before you actually do it. This tutorial assumes that your software does not have any previously registered options or settings, so we will have to register the settings you want to use. After that, you will need to create a space for the form needed to modify the settings, so we will register the page within the admin menu.
Register the Settings
Registering a setting is similar to adding an option, but with an added component. The function that needs to be called is register_setting(). It’s usage is simple once you understand the different parts of a setting. Each setting belongs to a group, which identifies settings with similar goals or in similar areas. For example, your options page has three sections: General, Appearance, and Other. Settings that belong to the “General” section should be grouped together, and might determine if certain basic functions are enabled. The settings that determine how the software’s output look should be grouped together in “Appearance.” Finally, any remaining settings would be placed into the “Other” group.
To actually register a setting, you need to know which group it will belong to and what to name it. Once you know those two pieces of information, you can create your settings using code similar to the example below. Of course, be sure to use your software’s namespace when creating functions and settings. For the following examples, “wphub” will serve as the namespace.
Imagine that the previous example was to add and register settings that controlled a function that accessed a remote API and processed it through some other function. The
function creates the database entry and saves the default value to the database if the option did not already exist. The
function accepts the setting’s group as the first argument, the “default” group for this example, and the setting’s name as the second argument. The group is left as the default group in the previous example due to the added simplicity, and you can research add_settings_section() and add_settings_field() if you need something more complex. If you need to sanitize the information that will be input by the end user, you can provide the sanitizing function’s name as a third argument, and it can be either a custom function or a built-in function. You can create as many settings in as many groups as you need using this method.
Register the Page
Registering your software’s options page is very simple. Just use the code from the example below and paste it into the same file where you registered the settings. Within this example, the
function, which places your options page under the “Settings” menu, can be swapped with another of the add_submenu_page() wrapper functions. Use
to place your options page under the “Appearance” menu, and
to place your options page under the “Plugins” menu.
All of the wrapper functions of add_submenu_page() accept the same arguments. The first argument is the text to be placed within the page’s
tag, while second argument is the text to be displayed within the sidebar menu, and should be descriptive enough for users to identify it yet short enough to not push against the sides of the sidebar. The third argument is the capability needed for a user to be able to see the options page, and the fourth is the ID you want this page to have. The ID should be unique, so using your software’s namespace will ensure that. The final argument is the name of the function that will display your option’s page content.
Creating the Page and Displaying Settings
Now that you have told WordPress what you are going to do, it is time to actually do it. Since you have all of your settings registered and your options page defined, you can now go forth with actually creating your options page and laying out your settings.
Create the Page
Creating the layout of the page is simple if you want to be simplistic with your page. There are more advanced ways of executing this, but this shall suffice for what we want to accomplish. The following example demonstrates the basics needed to get your options page functional and displaying content. When using the following code, be sure to replace the page title, optional section title, and descriptive text with your own content. If you wish to include additional sections, just copy everything between
and paste directly below the material you just copied.
There a few items in the previous example to note. The first is that your options page much be wrapper in a div tag with the class of “wrap,” so that the default CSS can be applied to it. You could remove it if you had something more sophisticated in mind and this tag was interfering with your styles. The second is that you can put any information before or after the form, and you can even completely exclude the form if you are just displaying information. The third and final item to note is that WordPress automatically processes and saves the information entered into form fields as long as you called
for each setting group you created earlier. This means that you do not need to create a separate function to save the information. All you would do if you wanted information saved in a precise way is to have WordPress pass each setting into a sanitizing function that would then alter the form data into something your software can process.
Display the Settings
Without delving into the more-complicated setup that requires you to declare sections, fields, and callback functions, there is a method of being able to display each setting as you wish in a simple fashion using tables. Yes, WordPress still uses tables on many pages in order to achieve a consistent look across all browsers. The following example should be a template for your own software, and should be located in place of
in the previous example.
This example illustrates two simple input fields, but you may use any type of form field that you require for your software. Be sure to place the same identifier you used in the
in the label’s “for” attribute, and the input field’s “id” and “name” attribute, and well as inside the
If you would like a combined example of everything above, you can copy and paste the following code into your own software.
A simple options page for your software is not difficult to set up if you only have a few configurable options. Retrieving those options is even easier by using the
function. The customization allows your end users to tweak your software to fit their needs, which is highly appreciated by the users and great for the WordPress community. While this tutorial does not utilize the latest features of WordPress to accomplish what we set out to do, it is sufficient for beginner developers creating a simple options page.