Late 2008, WordPress version 2.7 was in development and the backend interface was to receive a new facelift based on the usability testing conducted–code name Crazy Horse. This was a major change to the interface and it didn’t come welcomed when the community first saw the base UI-sans design in trunk. I was even a bit frustrated as it looked horrible. Despite knowing that WordPress was still in development, the community started throwing negative criticism thinking that the barebones UI was the final look. However little did we know that the actual “design” was being actively worked on by Matt Thomas and the community was basing their negative criticism off of alpha software. Low and behold, the design was finally committed to trunk and everyone loved it!

Now in version 3.0, we’re getting a new menu management system. This is going to be a highly used feature so there’s been a lot of critiquing and concern about it’s current state. Days after the original feature freeze (Feb 15th), WooThemes navigation system was contributed into WordPress. The community was grateful of WooThemes, but also concerned about the feature freeze deadline and getting the system integrated into core from a UI and coding perspective. So in addition to a several other developers, I stepped in and we all started reworking the codebase and making the UI more inline with WP’s UI conventions.

Long story short, after one of my patches got committed, Jane Wells posted her thoughts on it’s current in-development state along with comments pretty much +1′ing her concerns. The gist of her post was summed up to WP needing “a *basic* menu feature that plugins can build on.”

And the irony being that that’s exactly what my patches were doing. I cleaned up the interface and I reworked the codebase to make it easier for plugin authors to add their own menu item types. So now with the menu super nova patch in, the underlying code to support any post type and taxonomy is there which is pretty much what plugin authors will want to extend in Menus. Before this patch, it wasn’t possible. And because that patch was already huge, I moved everything over to the next patch sprint which was to limit the UI’s menu item types to just pages and categories with the additional post types and taxonomies being disabled from the screen. To enable them would just be a checkbox away in the screen options tab. But before that could even happen, the menus system is being criticized—just like crazy horse—as if everything was final when we haven’t even hit beta yet.

My point is, hold off on any negative criticism regarding the development of alpha software. Features are still being actively fine-tuned and bugs are still being ironed out. So hold your horses, it’s alpha software.

Step 1: Add a new instance of the widget to the options table

update_option( 'widget_search', array( 2 => array( 'title' => '' ), '_multiwidget' => 1 ) );

Parameters:

• Prefix widget_ with the id base of the Widget’s class.
• A two-dimensional array with:
  • the first array containing the widget’s settings
  • and the second containing the required: '_multiwidget' => 1

Note: In the second parameter of update_option, I gave the array a key value of 2. This number is intentionally there. More on that in step 2.

Do as many of those update_option calls for each widget instance you’d like to register. Then move along to step two:

Step 2: Update the sidebars options table

update_option( 'sidebars_widgets', array(
	'sidebar-1' => array(
		'search-2',
	),
	'wp_inactive_widgets' => array(),
	'array_version' => 3
));

The only thing you have to change here is the array in the second parameter:

• The array keys should be the id of the widget area
  • And it’s values should be the id base of the widget’s class, a dash, and then the same number we used as a key for the widget (created in step 1). In this case, it’s 2.

You may optionally preset widgets as inactive by throwing them in the wp_inactive_widgets array. And I wouldn’t mess with the array_version array. This is a hack since we’re not using any proper APIs to preset widgets so don’t go messing around with too much.

Et volia! You just perform the equivalent of selecting a widget from the available widgets section, dragging that instance over to a widget area, configured it, and saved the changes.. all through code!

Here’s the complete code along with additional sidebars and widgets so you see how that looks.

Devel

Devel is a WordPress plugin made up of “components” (which are the mini plugins) which can be activated or deactivated so you only use what you need. For the 0.1 release, I’ve bundled only one component with devel and that is the Custom Fields Manager.

Custom Fields Manager

The Custom Fields Manager component displays a listing of all custom fields available in your WordPress site. This is handy for when over the years, you’ve used a few dozen custom fields and would like to pin point all the posts that their used in to maybe modify or delete them. Well with the Custom Fields Manager, you can. In addition, you can edit a custom field to update it’s meta_key value, which will update all of it’s instances on your site. This is useful for when you’ve misspelled a custom field in one of your posts, or if a plugin changed which custom field it needs you to use. Finally, with Custom Fields Manager, you can delete individual custom fields or delete them in bulk. And that’s what you can expect from the Custom Fields Manager component. It provides very handy administrative task for managing your custom fields.

The Components API

In addition, there’s a neat components API built in so you can add your own components to the list. I’m not the only developer with a library of useful mini plugins, so devel allows you to bundle your own set. Thanks to Justin Tadlock and his Members plugin which is where I got the components idea from.

Download Devel Now.

P.S. Once I polish up all of my mini plugins, I’ll gradually add them as components to devel. For now, enjoy the CFM.

With the comments loop widget, you now have that always-a-hassle-to-create comments.php file completely revamped and widgetized. You can have multiple instances of the comments loop widget for each comment type, easily allowing you to separate comments from trackbacks.

I’ll let the widget settings do the talking:

Oh, and there’s more…

You know a comments loop widget wouldn’t be complete without the comments form:

With the Comments Loop widget in your arsenal, you’ll never need to edit your comments.php file again. Just create a new sidebar in any of your singular based templates (e.g. single.php, page.php, attachment.php). All the wording is editable from the widgets admin, all elements have semantic css class/id names, and if you love hooks, there’s plenty of those.

Download it now.

With the WordPress Loop widget, you’ll be able to create custom loops for your content, and display them exactly how you like—all without touching any code! It’s got all the bells and whistles you’d might expect:

Click on the screenshot to view bigger version

Of course if you know your way around PHP, then there’s 4 well-placed action hooks you can hook into.

Download it now.

In this example, we’re going to look at the popular k2 theme and see what it takes to consolidate their settings into one single database entry.

Upon installation, k2 runs an install function that adds several settings into the database.

function install() {
	add_option( 'k2version', K2_CURRENT );
	add_option( 'k2asidescategory', '0' );
	add_option( 'k2livesearch', '1' );
	add_option( 'k2rollingarchives', '1' );
	add_option( 'k2archives', '0' );
	add_option( 'k2sidebarmanager', '0' );
	add_option( 'k2columns', '2' );

	// Added 1.0-RC8
	add_option( 'k2animations', '1' );
	add_option( 'k2entrymeta1', __('Published on %date% in %categories%. %comments% %tags%', 'k2_domain') );
	add_option( 'k2entrymeta2', '' );
	add_option( 'k2widgetoptions', array() );

	$defaultjs = "// Lightbox v2.03.3 - Adds new images to lightbox\nif (typeof myLightbox != 'undefined' && myLightbox instanceof Lightbox && myLightbox.updateImageList) {\n\tmyLightbox.updateImageList();\n}\n";
	add_option( 'k2ajaxdonejs', $defaultjs );
}

We’re going to recreate that install function, but first, lets add a new function that stores the default values for each option as an array:

function k2_default_options() {
	$defaultjs = "// Lightbox v2.03.3 - Adds new images to lightbox\nif (typeof myLightbox != 'undefined' && myLightbox instanceof Lightbox && myLightbox.updateImageList) {\n\tmyLightbox.updateImageList();\n}\n";
	$options = array(
		'version' => K2_CURRENT,
		'asidescategory' => false,
		'livesearch' => true,
		'rollingarchives' => true,
		'archives' => false,
		'sidebarmanager' => false,
		'archives' => false,
		'columns' => '2',
		'animations' => true,
		'entrymeta1' => __('Published on %date% in %categories%. %comments% %tags%', 'k2_domain'),
		'entrymeta2' => '',
		'widgetoptions' => array(),
		'ajaxdonejs' => $defaultjs,
	);
	return $options;
}

You’ll noticed that I removed all prefixes of k2 as their not needed when everything is being stored under one entry. I also converted all the 0’s and 1’s into their boolean values. Now let’s recreate the install function:

function install() {
	add_option( 'kaytwo', k2_default_options() );
}

It’s as simple as that. Retrieving those values is just as easy:

$kaytwo = get_option( 'kaytwo' );

echo $kaytwo['version'];
echo $kaytwo['columns'];
echo $kaytwo['entrymeta1'];

Updating options involves retrieving the entire options array and updating only those that need to be updated.

$kaytwo = get_option( 'kaytwo' );

$kaytwo['version'] = '1.0';
$kaytwo['columns'] = '4';
$kaytwo['entrymeta2'] = __('Posted in %categories%. Tagged: %tags%', 'k2_domain');

update_option( 'kaytwo', $kaytwo );

Remember to include all options, even those that are not being updated themselves. Failure to do so removes those options from the database completely.

Deleting an option is similar to updating. Retrieve the entire options array and unset those that need to be removed:

$kaytwo = get_option( 'kaytwo' );

unset( $kaytwo['sidebarmanager'] );
unset( $kaytwo['asidescategory'] );

update_option( 'kaytwo', $kaytwo );

And that’s how you would consolidate all your options under a single database entry. But why stop here? Since we’re going to be interfacing with the database all throughout our WordPress theme, let’s make these calls into functions.

define( 'THEMEOPTIONS', 'kaytwo' );

/**
 * Returns the value of an option from the db if it exists.
 *
 * @since 0.4
 *
 * @param string $name Option Name.
 * @return mixed Returns the option's value if it exists, false if it doesn't.
 */
function framework_get_option( $name ) {
	$options = get_option( THEMEOPTIONS );
	if ( isset($options[$name]) ) {
		return $options[$name];
	} else {
		return false;
	}
}

/**
 * Adds an option to the options db.
 *
 * @since 0.4
 *
 * @param string $name Option Name. Must be unique.
 * @param mixed $value Option Value.
 * @return bool True on success, false if the option already exists.
 */
function framework_add_option( $name, $value ) {
	$options = get_option( THEMEOPTIONS );
	if ( $options and !isset($options[$name]) ) {
		$options[$name] = $value;
		return update_option( THEMEOPTIONS, $options );
	} else {
		return false;
	}
}

/**
 * Updates an option to the options db.
 *
 * @since 0.4
 *
 * @param string $name Option Name. Must be unique.
 * @param mixed $value Option Value.
 * @return bool true|false
 */
function framework_update_option( $name, $value ) {
	$options = get_option( THEMEOPTIONS );
	if ( $value != $options[$name] ) {
		$options[$name] = $value;
		return update_option( THEMEOPTIONS, $options );
	} else {
		return false;
	}
}

/**
 * Deletes an option from the options db.
 *
 * @since 0.4
 *
 * @param string $name Option Name. Must be unique.
 * @return bool true|false
 */
function framework_delete_option( $name ) {
	$options = get_option( THEMEOPTIONS );
	if ( $options[$name] ) {
		unset( $options[$name] );
		return update_option( THEMEOPTIONS, $options );
	} else {
		return false;
	}
}

Just define THEMEOPTIONS as the name of the database entry and your all set.

To read more on this topic, check out this post on Striderweb.

In the last article, we looked at a simple way for making your template files more cleaner and DRY using do_atomic(), a function that registers three predefined do_actions() for any particular location. In this article, we’re going to step it up a notch and talk about context and how we can create context sensitive action hooks.

Let’s talk about what we can do now. WordPress allows you to create action hooks at any point in your WordPress theme to allow other functions to be executed at that particular location. Well that’s pretty cool. But what about context? If you’ve ever used any sandbox-based theme, you should be familiar with the class generating functions it pours into the body tag and other sections throughout your theme. Those functions give CSS clear context as to what page is being displayed and a lot more specifics.

So if we had a #header div that displayed our site’s name and tagline, those class generating functions would allow us to style the #header div differently for pages, archives, or any other template without adding any if, else logic to the actual template file.

<!--BEGIN #header-->
<div id="header">
	<h1 id="logo"><a href="<?php bloginfo( 'url' ); ?>"><?php bloginfo( 'name' ) ?></a></h1>
	<p id="tagline"><?php bloginfo( 'description' ) ?></p>
<!--END #header-->
</div>

#header { background-image: url( '../images/header.jpg' ); }
.page #header { background-image: url( '../images/header-page.jpg' ); }
.single #header { background-image: url( '../images/header-single.jpg' ); }

So that got me thinking, why not do this for action hooks too?

Chris Jean wrote another version of the get_context() function which you should definitely check out.

/**
 * Retrive the context of the queried template.
 *
 * @since 0.4
 * @return array $query_context
 */
function get_query_context() {
	global $wp_query, $query_context;

	/* If $query_context->context has been set, don't run through the conditionals again. Just return the variable. */
	if ( is_array( $query_context->context ) )
		return $query_context->context;

	$query_context->context = array();

	/* Front page of the site. */
	if ( is_front_page() )
		$query_context->context[] = 'home';

	/* Blog page. */
	if ( is_home() )
		$query_context->context[] = 'blog';

	/* Singular views. */
	elseif ( is_singular() ) {
		$query_context->context[] = 'singular';
		$query_context->context[] = "singular-{$wp_query->post->post_type}";
		$query_context->context[] = "singular-{$wp_query->post->post_type}-{$wp_query->post->ID}";
	}

	/* Archive views. */
	elseif ( is_archive() ) {
		$query_context->context[] = 'archive';

		/* Taxonomy archives. */
		if ( is_tax() || is_category() || is_tag() ) {
			$term = $wp_query->get_queried_object();
			$query_context->context[] = 'taxonomy';
			$query_context->context[] = $term->taxonomy;
			$query_context->context[] = "{$term->taxonomy}-" . sanitize_html_class( $term->slug, $term->term_id );
		}

		/* User/author archives. */
		elseif ( is_author() ) {
			$query_context->context[] = 'user';
			$query_context->context[] = 'user-' . sanitize_html_class( get_the_author_meta( 'user_nicename', get_query_var( 'author' ) ), $wp_query->get_queried_object_id() );
		}

		/* Time/Date archives. */
		else {
			if ( is_date() ) {
				$query_context->context[] = 'date';
				if ( is_year() )
					$query_context->context[] = 'year';
				if ( is_month() )
					$query_context->context[] = 'month';
				if ( get_query_var( 'w' ) )
					$query_context->context[] = 'week';
				if ( is_day() )
					$query_context->context[] = 'day';
			}
			if ( is_time() ) {
				$query_context->context[] = 'time';
				if ( get_query_var( 'hour' ) )
					$query_context->context[] = 'hour';
				if ( get_query_var( 'minute' ) )
					$query_context->context[] = 'minute';
			}
		}
	}

	/* Search results. */
	elseif ( is_search() )
		$query_context->context[] = 'search';

	/* Error 404 pages. */
	elseif ( is_404() )
		$query_context->context[] = 'error-404';

	return $query_context->context;
}

get_query_context() returns an array containing the context of the current queried template. And it only runs once per page, even if there are multiple calls to it, so there’s no performance lost. get_query_context() is also custom post type aware.

Now, that we have some context, let’s put it into action. Here’s the new and suped-up do_action() — do_atomic():

function do_atomic( $tag = '', $args = '' ) {
	if ( !$tag )
		return false;

	/* Do actions on the basic hook. */
	do_action( $tag, $args );

	/* Loop through context array and fire actions on a contextual scale. */
	foreach ( (array) get_query_context() as $context )
		do_action( "{$tag}_{$context}", $args );
}

So now using do_atomic(), we can treat our action hooks just like we always did. In addition, do_atomic() registers up to 22 different contexts, so if you’d like to display something specific to page templates or archives-based templates, do_atomic() allows you to do so without creating any additional code.

Let’s go back to our header.php and replace the #header div with this:

<!--BEGIN #header-->
<div id="header">
	<?php do_atomic( 'theme_header' ); ?>
<!--END #header-->
</div>

And now, when a user queries a page template, you’ll have four actions fired in this order:

1. add_action( ‘theme_header’, ‘my_custom_header’ );
2. add_action( ‘theme_header_singular’, ‘my_custom_singular_header’ );
3. add_action( ‘theme_header_page’, ‘my_custom_page_header’ );
4. add_action( ‘theme_header_page-id-5′, ‘my_custom_page_foobar_header’ );

This way, you can specify a variety of looks for the header all while keeping your template files and functions clean and clutter free of if, else and is_* statements. And if by any chance you have more than one of those contextual hooks fired on a given page, simple call remove_action(); so only the desired one gets executed.

theme_before_location();
theme_location();
theme_after_location();

Where location is the location of that particular hook (e.g. header, footer, loop). Now that’s great and all, but here’s a smarter way:

do_atomic( 'location' );

Where do_atomic is:

// Registers three action hooks at once.
function do_atomic( $location = '' ) {
	if ( !isset($location) ) return;

	do_action( "theme_before_{$location}" );
	do_action( "theme_{$location}" );
	do_action( "theme_after_{$location}" );
}

Makes for much cleaner template files. The next article on smarter hooks will take this concept to an even higher level.

On the same path… If you have a child theme (I’ll use Ian Stewart’s pro/paid Thematic child theme called Power Blog, as the example) and want to customize that – what do you do? Currently we’re talking about customizing themes by using Child Themes. If I wanted to make mods to Power Blog, I’d have to change the child theme directly, thus negating some of the reasons for using a Child theme – like upgradability.

Do we get to a day where we need grandchildren themes? I think your code might be the start of a way to “group” the family theme files together. -Kel

The day WordPress starts talking about “grandchild” themes is the same day I’ll convert all my blogs over to movable type Habari.

Way back when I started talking about theme frameworks, I talked about how WP Framework stands out:

One of the main design goals I wanted to achieve with WP Framework that differentiates it from other frameworks is the fact that it’s not styled.

A WordPress theme framework should be design-agnostic. That’s why it’s a framework. It should only contain the building blocks and the most essential code (by the way, WP Framework 0.2.4 has just be released!).

Carrington gets it. Alex King built a base framework of carrington, basically extracted all the template logic and things that made his theme work into a “core” framework. When he builds themes off of carrington, he simply extends the core framework by building on top of it; not via a child theme.

So if users of Carrington blog wanted to customize it, they would create a child theme for it and modify it accordingly. Here’s two possible scenario’s that show the benefits of what I’m describing:

• Carrington blog gets an update that includes a new section above the sidebar (a feature dealing with the design, not the logic). Users would simply download/update Carrington blog and the new section would appear above the sidebar as expected. All of the user’s changes for Carrington is preserved and left intact via the child theme.
• But let’s say Carrington framework fixes a bug in it’s atomic template system (an issue dealing with the framework logic, not the design). There would be an update available to all themes based on carrington, and users would simply download/update carrington blog (or which ever theme based on Carrington they have) and the fix gets applied. The user’s modifications to Carrington blog are left intact via the child theme.

It’s important to think of a theme framework as the logic of the theme, not the design or the underlying xHTML.

To put this into a step by step process:

1. Start with a blank WordPress theme framework
2. Create your WordPress theme based off said framework
3. Now to customize this WordPress theme (which is essentially the first two steps combined), create a child theme for it.

That’s how WordPress theme frameworks should work. In Kel’s case, Thematic already consist of the first two steps described above when it should only be the first one. So now that she’s using the Thematic Power Blog, she won’t be able to customize her theme using a child theme because it’s already one.

function has_kids() {
	if (STYLESHEETPATH !== TEMPLATEPATH) return true;
	return false;
}

if ( has_kids() ) {
	// do stuff
}

This function works whether you call it from a child theme or parent.