Incorporating the Settings API in WordPress Themes

Filed in Web DevelopmentTags: Settings API, Themes, tutorials, WordPress

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!

Fried rutabaga with broiled pork chop and Brussells sprout slaw

Rutabaga: Well-Kept Low-Carb Secret

Filed in PersonalTags: Health/Nutrition, Low Carb

Oh, rutabaga, where have you been my whole (low-carb) life?

I have been a dedicated low-carber for over a decade. While I could go the rest of my life without eating another dessert or drinking another soft drink, my meat-and-potatoes farm-community up-bringing often leaves me missing starch-laden foods of my youth, such as fried potatoes and biscuits and gravy. In fact, when I decide to splurge, it is almost alway with one of these two foods. In over ten years of living low-carb, I had never found a suitable, low-carb replacement for crispy potatoes fried in bacon grease.

Enter the rutabaga: humble root vegetable, that also happens to be incredibly low in carbohydrate (under half the net carbohydrate content of a potato). While not a strictly low-carb food, it makes for a great option for the occasional potato fix.

Apparently, the rutabaga has fallen out of popular use, due to its reputation as famine food during World War II. How unfortunate. As it turns out, the rutabaga is basically just as easy to work with as the potato, and makes an equally good accompaniment as the potato when fried.

Here are the results of tonight's experiment with making fried rutabaga.

The rutabaga is at first a somewhat unusual-looking vegetable, but is actually easier to peel than a potato:

Rutabaga Peeled and Unpeeled

Rutabaga Peeled and Unpeeled

Once peeled, rutabaga is considerably more difficult to cut through than a potato; however, once I quartered the rutabaga, the mandolin made quick work of slicing:

Rutabaga Quartered and Mandolin-Sliced

Rutabaga Quartered and Mandolin-Sliced

I initially fried a small batch (1/2 rutabaga) of potato chip-thin slices, to get a feel for the texture and taste of fried rutabaga.

Frying a trial batch of rutabaga

Frying a trial batch of rutabaga

Having discovered that rutabaga fries essentially the same as potato, we were pleasantly surprised further to discover the mild, natural sweetness of rutabaga that - especially when crispy-fried - pairs in a rather addictive manner with a little salt and pepper.

Finding the trial run successful, I set the mandolin to one setting thicker, sliced another whole rutabaga, and fried the whole batch in bacon grease, as before.

First full batch of fried rutabaga

First full batch of fried rutabaga

This batch definitely took longer to cook than the potato chip-thin slices, but still barely took longer than the time required to broil pork chops.

The pork chops and fried rutabaga (garnished with a few bits of crumbled bacon), combined with some Brussels sprouts "slaw" (steamed Brussels sprouts, core removed, mashed/quick chopped, with butter, Parmesan cheese, and a few drops of lemon juice) made for a tasty and - and unexpectedly filling - meal.

Fried rutabaga with broiled pork chop and Brussells sprout slaw

Fried rutabaga with broiled pork chop and Brussells sprout slaw

(I actually was unable to finish the entire plate.)

Next up: rutabaga chips in the deep fryer, rutabaga soup (using my secret family potato soup recipe), and roast with rutabaga.