Building WordPress Theme Settings Page Using the Settings API

Settings page is an important part of any WordPress theme and plugins. Most of the WordPress themes and plugins has the settings page where users can customize its features, styles and behavior. Using settings page your users can easily customize and update the theme without losing anything. This article is the continuation of our previous article “Creating WordPress Admin Pages : Custom Admin Menus“, so we recommend you study that article before this. In this tutorial we will be building WordPress theme settings page using the Settings API.

What is setting API?

Setting API are collections of hooks, functions and actions to create the custom option. Setting API was added for the first time in WordPress 2.7 and since then it is the recommended way by WordPress for creating WordPress theme setting page. If you don’t use Setting API, you have to manually create form with HTML and input the values inside the post object and save the post object in your database. But we should use WordPress built in functions called setting API for three main reasons which are as follows.

  1. The settings API are much safer and requires less effort
  2. Using pre made hooks and function of WordPress makes your theme more adaptive. It is easier to make theme updates for future WordPress versions.
  3. Settings API automatically save the settings made into the database without us worrying about any kinds of problems.


Building WordPress Theme Settings Page using the Settings API

Creating a Theme Settings Page Menu Item

The first step is to create a menu item in the Admin page (dashboard). When users clicks the custom menu link of the admin page they will be directed to the setting page that we are about to create. If you want to learn in detail about creating custom menu items in admin page check our article “Creating WordPress Admin Pages: Custom Admin Menus

Here is the simplified code to create custom menu item for theme setting page. Note: Paste this code in the functions.php file of your theme

function my_admin_menu () {
    $page_title = 'My Awesome Theme setting Page';
    $menu_title = 'My theme Setting';
    $capability = 'edit_posts';
    $menu_slug = 'awesome_page';
    $function = 'my_theme_settings_page';
    $icon_url = '';
    $position = 110;

    add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url, $position );

add_action('admin_menu', 'my_admin_menu');

function my_theme_settings_page(){}

The function my_theme_settings_page is the callback function inside which includes the content to be displayed inside the page. The above code should give you a new menu called My theme Setting as shown in the image below.

custom-page-menu WordPress Theme Settings Page using the Settings API

Using the Settings API

In the above code, we write the following code inside the my_theme_settings_page function.

function my_theme_settings_page(){
    <h1>My Theme Setting page</h1>
    <?php settings_errors(); ?> 

    <form method="post" action="options.php">
        <?php settings_fields("setting-group");?>
        <?php do_settings_sections('awesome_page')?>
        <?php submit_button();?>


settings_fields registers a section of settings called setting-group. Similarly do_settings_sections prints out all the setting sections in the particular settings page(awesome_page). Submit_button displays the submit button and the settings_errors function gives the feedback message to user. Right now your theme setting page should look like this.

Also Read:   How to Hide a Post from Home Page in WordPress

theme-setting-first WordPress Theme Settings Page using the Settings API

Adding the custom options in the settings page.

You can use the following code to add the custom options or input fields in the custom settings page.

function ff_custom_setting(){
   register_setting('setting-group', 'first_name');
   register_setting('setting-group', 'last_name');
   register_setting('setting-group', 'twitter_field');
   register_setting('setting-group', 'facebook_field'); 
   add_settings_section('ff_sidebar_options','Sidebar Options', 'ff_sidebar_options', 'awesome_page');
   add_settings_field('sidebar-name','Full Name','sidebar_full_name_func', 'awesome_page','ff_sidebar_options');
   add_settings_field('sidebar-twitter','Twitter','sidebar_twitter_func', 'awesome_page','ff_sidebar_options');
   add_settings_field('sidebar-facebook','Facebook','sidebar_facebook_func', 'awesome_page','ff_sidebar_options');
function ff_sidebar_options(){
   echo 'You sidebar options.';
function sidebar_full_name_func(){
   $first_name = esc_attr(get_option( 'first_name' ));
   $last_name = esc_attr(get_option( 'last_name' ));
   echo '<input type="text" name="first_name" value="'.$first_name.'" placeholder="first name">
         <input type="text" name="last_name" value="'.$last_name.'" placeholder="last name">';
function sidebar_twitter_func(){
   $twitter = esc_attr(get_option( 'twitter_field' )); 
   echo '<input type="text" name="twitter_field" value="'.$twitter.'" placeholder="Your Twitter id here">';
function sidebar_facebook_func(){
   $facebook = esc_attr(get_option( 'facebook_field' ));
   echo '<input type="text" name="facebook_field" value="'.$facebook.'" placeholder="Your Facebook id here ">';

At first we have used a hook called add_action to initialize the admin panel and call the function ff_custom_setting. Inside the function ff_custom_setting , there are three three important functions from where the setting API is being used.

  1. register_setting : Here the function is used to register the setting and automatically save the value in it.
  2. add_settings_section: It add a section to the setting page.
  3. add_settings_field: It adds a setting field in the setting page and section.

The custom options are being displayed from each of their respective functions. Your settings page should like this now.


Retrieving Settings

The values users enter in the setting page has to be retrieved in the front end. The values are stored internally in the setting API which can be retrieved using get_option() function. In the above you can see that the values are already retrieved using get_option() function and is stored in variables. Variables $first_name, $last_name, $twitter and $facebook can be used in front end to output the respective values.

We hope the article gave you basic ideas of using Setting API for custom option in the theme setting page.

The following two tabs change content below.

Kantiman Bajracharya

Kantiman Bajracharya is a freelance web developer. He is a computer geek who has a Bachelor’s degree in Computer Engineering. He has earned lots of satisfied customers while working for numerous successful projects. He is also a WordPress theme creator and web article writer. On free time he likes reading philosophy books, traveling and playing chess.

Share This Post