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

2. 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! 3. 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. 4. DECIDING WHAT SETTINGS ARE NEEDED 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. 5. DECIDING WHAT SETTINGS ARE NEEDED 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. 6. 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"); 7. HOOKING THE SETTINGS PAGE TO WORDPRESS 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: 8. HOOKING THE SETTINGS PAGE TO WORDPRESS $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. 9. HOOKING THE SETTINGS PAGE TO WORDPRESS 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 10. HOOKING THE SETTINGS PAGE TO WORDPRESS 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: function setup_theme_admin_menus() { 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!"; } 11. HOOKING THE SETTINGS PAGE TO WORDPRESS 12. HOOKING THE SETTINGS PAGE TO WORDPRESS 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." 13. HOOKING THE SETTINGS PAGE TO WORDPRESS 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. 14. HOOKING THE SETTINGS PAGE TO WORDPRESS 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', '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"; } 15. HOOKING THE SETTINGS PAGE TO WORDPRESS 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: 16. HOOKING THE SETTINGS PAGE TO WORDPRESS 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() { } 17. HOOKING THE SETTINGS PAGE TO WORDPRESS 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. 18. 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. 19. CREATING THE HTML FORM FOR THE SETTINGS PAGES Edit your settings page function: function theme_front_page_settings() { ?> Number of elements on a row: