WordPress theme setting page

Create a Settings Page For Your
WordPress Theme
Junejo Naeem Ahmed
WORDPRESS

WORDPRESS THEME
• Creating your own theme for WordPress is a great way to give
your blog or other WordPress powered web site an original
touch.
• But even the nicest looking theme is not that nice if you have
to get under the hood and edit the theme's HTML or PHP
code whenever it's time change some aspects of it.
• Especially, when it's not you but a paying customer using your
theme.
• Luckily, creating a settings page for your theme in WordPress
is not very hard!

DECIDING WHAT SETTINGS ARE NEEDED
• It all starts from the need: to create a clear and useful settings page,
you have to figure out the things that will need to be changed and
leave out everything else.
• Every new setting you add to the admin menus adds complexity to the
user interface and risks making the theme harder to use.
• That's why it's better to be careful and handpick the options that are
going to be changed often and leave out one time customizations that
can easily be done changing one file inside the theme.
• Another question to keep in mind is "Who is going to be changing
these settings?“
• If the user is familiar with PHP and WordPress, it might be reasonable
to expect that he is OK with embedding his Google Analytics code in
the code herself.
• but you shouldn't require that from a graphic designer, not to mention
a writer who doesn't even need to know anything about HTML and
CSS.

• Common ideas for things to define in theme settings include:
• The site's Google Analytics tracking code
• The number of sidebars and their positioning (left, right, maybe even
up and down)
• Page width
• The contents of your footer
• Options for features that are specific to the theme, such as custom
teaser formats.

• Once you have collected the list of theme features that you'd like to
control through a settings page, you are almost ready to start the
implementation.
• Before you move on and create your settings page, you can save time
by making sure that there isn't a WordPress feature already available
for the customization you have in mind.
• Widgets, custom menus, custom backgrounds and header images are
all useful tools for making your theme customizable with a lot less
work than required for creating your own settings.

HOOKING THE SETTINGS PAGE TO WORDPRESS
• Creating a settings page starts by creating a function that sets up the
menu and hooking it to the WordPress action admin_menu.
• This tells WordPress to call your function when its time to create the
menus so that everything is done at its proper time.
• Add this code to your theme's functions.php file:
• function setup_theme_admin_menus() {
• // We will write the function contents very soon.
• }
• // This tells WordPress to call the function named
"setup_theme_admin_menus"
• // when it's time to create the menu pages.
• add_action("admin_menu", "setup_theme_admin_menus");

• We'll now put the code for creating the settings pages inside the
function we just created.
• When creating your settings page, you have the choice of either adding
the page as a submenu to one of the existing settings groups or of
creating your own top level menu.
• Adding a submenu is done with the function add_submenu_page:
• <?php add_submenu_page($parent_slug, $page_title,
$menu_title, $capability, $menu_slug, $function) ?>

• $parent_slug is a unique identifier for the top menu page to which this
submenu is added as a child.
• $page_title is the title of the page to be added
• $menu_title is the title shown in the menu (often a shorter version of
$page_title
• $capability is the minimum capability required from a user in order to
have access to this menu.
• $menu_slug is a unique identifier for the menu being created
• $function is the name of a function that is called to handle (and
render) this menu page.

• If you choose to add the menu page as a submenu to one of the
WordPress groups, you can use the following values as the
$parent_slug parameter:
• Dashboard: index.php
• Posts: edit.php
• Media: upload.php
• Links: link-manager.php
• Pages: edit.php?post_type=page
• Comments: edit-comments.php
• Appearance: themes.php
• Plugins: plugins.php
• Users: users.php
• Tools: tools.php
• Settings: options-general.php

• The Appearance group looks like a good candidate for placing our
settings page.
• Let's try that, and create our first settings page.
• Here's an updated version of our menu setup function:
• add_submenu_page('themes.php',
• 'Front Page Elements', 'Front Page', 'manage_options',
• 'front-page-elements', 'theme_front_page_settings');
• }
• We still need to create the function theme_front_page_settings for
this to work. Here it is in its simplest form:
• function theme_front_page_settings() {
• echo "Hello, world!";
• }

• We also need to check that the user has the rights required for editing
the settings page.
• To do that, add the following code at the beginning of the settings
page function:
• // Check that the user is allowed to update options
• if (!current_user_can('manage_options')) {
• wp_die('You do not have sufficient permissions to access this page.');
• }
• Now, if a user who isn't allowed to manage options comes to the
settings page, he will see nothing but the message, "You do not have
sufficient permissions to access this page."

• If your theme needs multiple settings pages, it can be confusing for the
user to look for them scattered all around the menu structure.
• In that case, creating your own settings group makes it easier for the
theme user to find all the menu pages for the theme.
• To add your own settings group, you need to create a top level menu
page and link the submenu pages to it.
• Here is a new version of our menu setup function.
• The add_menu_page function used to create the top level menu is
similar to add_submenu_page except that it doesn't take the
$parent_slug parameter.

• add_menu_page('Theme settings', 'Example theme', 'manage_options',
• ‘my_theme_settings', 'theme_settings_page');
•
• add_submenu_page(‘my_theme_settings',
• 'Front Page Elements', 'Front Page', 'manage_options',
• 'front-page-elements', 'theme_front_page_settings');
• }
•
• // We also need to add the handler function for the top level menu
• function theme_settings_page() {
• echo "Settings page";
• }

• If you test the code and refresh the WordPress admin, you'll see your
new menu group appear at the bottom of the menu list:

• But something doesn't look quite right yet.
• Clicking the top menu element doesn't lead you to the "Front Page"
menu but a menu page called "Example theme.“
• This is not consistent with how the other WordPress menus function,
so let's do one more thing: by changing the $menu_slug attribute in
the add_submenu_page call to the same value as in the top level
menu, we can link the two menus so that selecting the top menu
selects the front page menu:
function setup_theme_admin_menus() {
add_menu_page('Theme settings', 'Example theme', 'manage_options',
‘my_theme_settings', 'theme_settings_page');
add_submenu_page(‘my_theme_settings',
'Front Page Elements', 'Front Page', 'manage_options',
‘my_theme_settings', 'theme_front_page_settings');
}
function theme_settings_page() {
}

• Looks better. If you want to still improve the looks of your menu group,
there are two optional fields in the add_menu_page function that you
will find useful.
• Just add the values after the function name in the method call:
• $icon_url specifies the URL of an icon for the top level menu.
• $position specifies the position of your menu group in the menu list.
• The higher the value, the lower the position in the menu.

CREATING THE HTML FORM FOR THE SETTINGS PAGES
• Now that we have created the settings page, and it shows up
nicely in the side menu, it's time to start adding some
content.
• So, let's go back to the list of settings we had in mind, and
draft a page for editing them.
• we need a field for defining how many elements should be
listed on one row, and a list for defining the actual elements.
• To start from the easier, let's create a text field for the number
of elements on one row.

• Edit your settings page function:
• ?>
• <label for="num_elements">
• Number of elements on a row:
• </label>
•
• <input type="text" name="num_elements" />
• <?php
• }

• When you reload your settings page, you'll see the first settings field
appear:

• To make the settings page fit seamlessly in the WordPress experience and to give your
theme a professional touch, it's a best practice to use the CSS classes and styles that
WordPress uses in its own settings pages.
• A good way to learn the tricks is to just go ahead and analyze the WordPress source
code.
• The most important thing is to wrap your setting page with a div with the class "wrap".
• Within that div element, you can use many predefined styles such as headings, buttons,
and form fields.
• Let's start by styling the title of our settings page:
• We will create a h2 heading for the page (You can use the heading tags from h2 to h6 to
create headings with different sizes.)
• We will show the theme settings page icon before the heading. (You can use the
predefined WordPress icons with the screen_icon function.
• The function can take one of the following parameters: index, edit, upload, link-
manager, pages, comments, themes, plugins, users, tools or options-general.)
• We will put the input element inside a form and a table with the class form-table.

• ?>
• <div class="wrap">
• <?php screen_icon('themes'); ?> <h2>Front page elements</h2>
•
• <form method="POST" action="">
• <table class="form-table">
• <tr valign="top">
• <th scope="row">
• <label for="num_elements">
• Number of elements on a row:
• </label>
• </th>
• <td>
• <input type="text" name="num_elements" size="25" />
• </td>
• </tr>
• </table>
• </form>
• </div>
• <?php
• }

SAVING THE FORM
• The settings page looks good, but there is something missing: it doesn't do
anything yet.
• It's time to save some data.
• WordPress provides an easy system for saving theme and plugin settings
as key value pairs to the database using two functions:
• get_option and update_option.
• The data stored using the functions can be as simple as a number value or
as complex as an array nested multiple times.
• The handling of the form is done in the same function that renders the
form.
• To know whether a form was submitted or not, we add a hidden field,
update_settings to the form and then check whether that field was sent or
not in the handling function.

SAVING THE FORM
• if (isset($_POST["update_settings"])) {
• // Do the saving
• }
• The hidden field that goes inside the form looks like this:
• <input type="hidden" name="update_settings" value="Y" />

SAVING THE FORM
• Let's start by saving the easier setting, num_elements.
• We'll escape the attribute to make sure the user isn't sending malicious
content in the from of HTML tags and then save it to the WordPress
settings storage.
• When using update_option, we don't need to worry about whether the
setting has already been saved or not.
• $num_elements = esc_attr($_POST["num_elements"]);
• update_option("theme_name_num_elements", $num_elements);

SAVING THE FORM
• Before we move to saving the list, let's add the current value of
num_elements to the settings form so that the user always sees what
value he has entered in before deciding the next value.
• This will also help us test that the value was actually saved.
• <input type="text" name="num_elements" value="<?php echo
$num_elements;?>" size="25" />
• And for cases where we haven't saved anything yet, we'll need to load the
current value from options, so let's add this piece of code to be executed
when there is no form submitted.
• $num_elements = get_option("theme_name_num_elements");

SAVING THE FORM
• When a form is saved, it's important to notify the user so that he isn't left
wondering whether something happened or not.
• So, let's render a simple notice saying "Settings saved." right after the
update_option:
• <div id="message" class="updated">Settings saved</div>

USING THE SETTINGS INSIDE THE THEME
• Saving and showing settings values within the admin area is great, but
what really counts is how you use them to customize your theme, so now,
we have come to the point where it's time to take our settings and do
something cool with them.
• From here on, changes go to index.php instead of functions.php. First,
we'll read the options to variables:
• <?php
• $num_elements = get_option("theme_name_num_elements");
• ?>

CONCLUSION
• Now, we have created a settings page for a custom theme.
• The theme is far from complete, but I hope this introduction got you
started with adding settings and customizable elements to your next
WordPress theme.

WordPress theme setting page

More Related Content

What's hot (20)

Similar to WordPress theme setting page (20)

More from Naeem Junejo (6)

Recently uploaded (20)

WordPress theme setting page