The inter-tubes are awash in tutorials for how to add Theme Options to WordPress Themes - so why write another? Primarily, because most such tutorials are several years old, don't implement current best-practices, and were written without any awareness of the WordPress Settings API.
While others such as Otto and Ozh have done yeomen's work in explaining how to implement the Settings API, I have not yet come across anything that really put everything together, and explained the process and implementation from beginning to end, in a way that even the less-experienced Theme developers (like me) could easily understand.
This tutorial will attempt to fill that gap, by providing examples of current (as of the pending release of WordPress 3.1) best-practice implementation, not merely of the Settings API, but of Theme Options implementation as a whole, including:
- Registering options in the database as a single options array
- Initializing default options
- Creating a single Theme Settings page (with tabs)
- Defining settings page sections and fields
- Validating and white-listing user-input form data
- Adding Settings Page contextual help
- Enqueueing custom CSS for the Settings page
- Implementing settings in the Theme template files
- Enqueueing front-end CSS
Throughout this tutorial, I will be using code from my Oenology Theme for implementation examples. For full code, see the latest development version.
Assumptions: Best Practices
The following will be the working list of best practices that will be incorporated:
- Theme Settings defined as an options array in a single database entry
- Theme settings added to a single Theme Settings Page
- Theme Settings page is added to the "Appearance" menu
- Theme Settings page added using the "edit_theme_options" user capability
- Theme Settings registered, updated, and validated using the WordPress Settings API
- Theme Settings modify the template using action/filter hooks wherever possible
Getting Started
The first thing we need to do, even before touching any code, is to determine:
- What options to include in the Theme
- How to organize those options on the Theme Settings Page
In my case, I am adding only a handful of simple options:
- Header Navigation Menu Position: currently, Oenology displays the Header Navigation Menu above the site title and description. I am adding a setting optionally to display the Header Navigation Menu below the site title and description.
- Header Navigation Menu Depth: currently, Oenology is designed so that only the top-level Pages display in the Header Navigation Menu, and Child Pages display in a left-column sub-menu. I am adding a setting optionally to display Pages to a depth of one (top-level Pages only), two, or three, with hover drop-down menus.
- Footer Credit Link: currently, Oenology does not display any form of footer credit link. I am adding a setting optionally to display a footer credit link.
- Varietals: the default style of Oenology is intentionally minimal. It is intended to be clean, simple, and cross-browser. I am adding a setting optionally to select from among Theme "skins" (which, in keeping with the oenology metaphor, will be called "varietals"), which will apply different color/style schemes to the Theme.
Given that I'm only adding four Theme options, I could very easily put all four together on one Settings page. However, I may want to add additional options in the future - and also, I want to provide a proof-of-concept for creating complex Theme Settings pages in a way that supports the Settings API. So, the Theme Settings page will have two tabs: "General", and "Varietals". Further, the "General" tab will have two sections: "Header Options" and "Footer Options".
So, that's our basis. Let's get started!
