WordCamp Raleigh – I am WordPress

The slides are already up for my presentation I am WordPress and So Can You (Whizbangy html/js slides. Works right in your browser!).

I had a few followup questions about getting started with particular teams.

To get started with the Theme Review Team, go to the Ticket Request Queue (or find the current month, if you’re coming by this post at some later date) and leave a comment with your WordPress.org user name. Someone will assign a theme to you and make sure that you got through the reviewing process okay.

If you’re interested in UI/UX work, make.wordpress.org/ui is very active — read through the last few months of posts to get a sense of the kind of discussions we have, and then drop in to one of our meetings on Tuesday afternoons (Eastern) in the #wordpress-ui channel in IRC. If you don’t know IRC yet, you can chat through the web at webchat.freenode.net. Since we’re currently in beta for 3.5, most of the current work is cleanup and bug-fixing, but we’re happy to have you come by and we’ll be starting up the next design phase before you know it!

And for the people who asked about getting started in the forums, I really, truly meant it when I said you can just dive in. Start with answering a question — even if you think you’re just one tiny step more advanced than the person who’s asking. It’s a great feeling, and you’ll learn more every time you do it.

I went to WPCS and all I got was this totally awesome t-shirt

Oh, and…

Some much-needed recharge time here:

A few moments of the kind of determined weirdness you only find near the beach:

100 people who are no longer just avatars, twitter feeds, or IRC handles (sadly, a few couldn’t come due to visa trouble, life emergencies, or Hurricane Sandy. You were dearly missed.):

Photo credit: Konstantin Kovshenin. But he’s in it! So I’d also love to give proper credit to the person who really took it.

On top of all that (phew!) it was one of those rare conferences that really reworked my brain. I feel incredibly lucky to have had two of those this year, and just like AdaCamp DC in July, I left this one with a whole new sense of focus and community, mixed with some real, practical new knowledge and action.

There are summaries of the morning and afternoon discussions, with more detailed notes to come. I’ve always felt that the mark of a great conference is that I want to clone myself several times over in order to take in everything that’s going on at once. This one had that, plus overflow into more discussions (and hacking on everything and anything) the next day. Each session produced action items, many of which are already underway. There are new projects underway, making features people have wanted for a very, very long time. And I’m pretty sure the media system got about 3 new versions overnight…

My First Patch, chapters 1-3

My first patch to an open-source project was for Dreamwidth, which is a wonderful hosted blogging community built on a fork of the LiveJournal codebase, with an unusual commitment to supporting devs even if they’ve never written a single line of code. If I remember correctly, I added the trailing zeroes to whole-dollar prices in their store so the numbers would line up correctly.

My first patch to WordPress was one line of CSS changing the width of a table. Some people really hated the change, and anyway, the entire project it was part of eventually got rolled back because it wasn’t going to be ready for release time.

My first WordPress props only came after I signed up for a team and volunteered for a whole new feature, which I never would’ve had the guts to do if I hadn’t dipped my toes in first (and sat in on meetings, and followed lots of tickets, and learned who ask questions of, and generally watched the whole process through a cycle) (also, I got fired up by a WordCamp talk and tweeted to a bunch of people that I wanted to get at least one patch in 3.4, and public commitment is powerful stuff).

Ever since I went to AdaCamp, but really, ever since Dreamwidth, I’ve been really interested in new developers’ experiences. I still consider myself one, for one thing, but also, every dev I know, no matter how amazingly skilled or outwardly confident, has or once had a bit of “am I good enough for core?” And really: tiny patches and openness to learning really are good enough.

If you have a good first-patch story, tell me! Or better yet, put it in your own blog and let me know!

Backwards compatibility for WordPress 3.4 headers and backgrounds

As I mentioned in the previous post, the new versions of WordPress custom headers and backgrounds have some great new features, but they require WordPress 3.4. That’s no problem if you’re already steering your custom development towards 3.4 (and you should be), but if you’re building themes for distribution, you can’t be sure that all your users are going to upgrade on the first day or even month.

Michael Fields, Automattic Theme Wrangler and all-around smart theme guy, pointed me toward the latest version of P2, which has a rather nice way of handling the backwards compatibility issue for just this case: (This function is called within theme setup)

function p2_setup_custom_header() {
	$args = array(
		'width'               => 980,
		'height'              => 120,
		'default-image'       => '',
		'default-text-color'  => '3478e3',
		'wp-head-callback'    => 'p2_header_style',
		'admin-head-callback' => 'p2_admin_header_style',

	$args = apply_filters( 'p2_custom_header_args', $args );

	if ( function_exists( 'get_custom_header' ) ) {
		add_theme_support( 'custom-header', $args );
	} else {
		// Compat: Versions of WordPress prior to 3.4.
		define( 'HEADER_TEXTCOLOR',    $args['default-text-color'] );
		define( 'HEADER_IMAGE',        $args['default-image'] );
		define( 'HEADER_IMAGE_WIDTH',  $args['width'] );
		define( 'HEADER_IMAGE_HEIGHT', $args['height'] );
		add_custom_image_header( $args['wp-head-callback'], $args['admin-head-callback'] );

Elsewhere in the theme setup function, P2 also uses:

	$args = apply_filters( 'p2_custom_background_args', array( 'default-color' => 'f1f1f1' ) );
	if ( function_exists( 'get_custom_header' ) ) {
		add_theme_support( 'custom-background', $args );
	} else {
		// Compat: Versions of WordPress prior to 3.4.
		define( 'BACKGROUND_COLOR', $args['default-color'] );

That’s taken direct from P2 — you’ll have to make adjustments for your own themes: change the slugs, set up the options you want to use, etc.

I can’t think of any reason you couldn’t wrap both function_exists() checks into one conditional, but I’m inclined to keep them separate — it’s easier to read, easier to override in child themes, and if one extra check is a performance concern, it’s time to add a second hamster to your hamster wheel…

(On the other hand, I’m not a fan of holding on to backward compatibility beyond a couple of core versions back. There are a lot of themes out there still checking if widgets are supported, and at that point it’s just cruft. Be nice to your code.)

Flexible headers in WordPress 3.4 themes

As of WordPress 3.4 Beta1, theme authors can allow custom header images with flexible heights, widths, or both.

In other words, instead of being limited to a fixed size determined by the designer, as you’re already familiar with:

With flexible headers, you can allow users to upload smaller or larger headers without having to make a child theme or (worse) hack your theme, like so:

How to do it:

Image header support in 3.4 no longer uses all the constants that had to be defined in previous versions — HEADER_IMAGE_HEIGHT, HEADER_IMAGE_WIDTH, HEADER_TEXT_COLOR and the like are now gone. Instead, all the header support options are included in a single array, and enabled with a call to add_theme_support() in your theme’s functions.php file.

This is how the array looks in the theme I used for the screenshots above:

// Add support for flexible headers
 $header_args = array(
 'flex-height' => true,
 'height' => 200,
 'flex-width' => true,
 'width' => 950,
 'default-image' => '%s/images/headers/path.jpg',
 'admin-head-callback' => 'mytheme_admin_header_style',

 add_theme_support( 'custom-header', $header_args );

If flex-height or flex-width are not included in the array, height and width will be fixed sizes, replacing the old HEADER_IMAGE_HEIGHT and HEADER_IMAGE_WIDTH. If flex-height and flex-width are included, height and width will be used as suggested dimensions instead.

Don’t forget to remove any references to the old constants in your template files — in my header.php, I simply replaced.

<img src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="" />


<img src="<?php header_image(); ?>" height="<?php echo get_custom_header()->height; ?>" width="<?php echo get_custom_header()->width; ?>" alt="" />

For reference, here’s the full set of options and their default values, as found in /wp-includes/theme.php. Note that the other header image options like text, text color, and randomization are available in the same add_theme_support() call by setting only the options you need:

$defaults = array(
'default-image' => '',
'random-default' => false,
'width' => 0,
'height' => 0,
'flex-height' => false,
'flex-width' => false,
'default-text-color' => '',
'header-text' => true,
'uploads' => true,
'wp-head-callback' => '',
'admin-head-callback' => '',
'admin-preview-callback' => '',

A few important notes:

  • Flexible header support has to be built into each theme – it will not work automatically with your pre-existing themes.
  • This functionality requires WordPress 3.4, which is currently in beta. You can grab the latest here (.zip file). Please use it for testing and development, but don’t run it in production unless you know what you’re doing and have some risk tolerance.
  • Design-wise, flexible heights are relatively easy; flexible widths are much trickier to work into a layout while still looking good. Experiment!

Plugin: Blogify Posts Menu

I hate “Posts”. Oh, I don’t mean that I hate posts, and in fact I’m kind of in love with making more of them now that I’m finally getting back in the habit.

No, I mean I hate the thing in the WordPress menu that says “Posts”, because when I’m looking at the menu for what to click, I’m thinking, “I want the blog”. And because I’ve seen about a bajillion new users get really, painfully stuck on Posts and Pages and What’s the difference, and How do I know which one to use, and even after explaining, still just want to know, “but how do I post to my blog?”

When it happens that consistently, it isn’t a problem with the users. They’re simply telling us that we need a better label.

This plugin changes the label. No muss, no fuss, no configuration needed. Scratch your own itch, or add it to your standard bag of tricks when building sites for other people. Grab the plugin and more details at the WordPress repository or on the plugin page.

WPTRT Review-a-thon tomorrow

The Review Team has been playing around with ideas to get through our backlog of themes to be reviewed, so I’ve proposed an IRC meetup in #wordpress-themes on Freenode, tomorrow at 1700 UTC / noon US Eastern.

The model I have in mind is http://codex.wordpress.org/WordPress_Bug_Hunts

In particular, I want to invite any new or wanna-be reviewers to join in; this would be a great chance to get started with reviewing, get your test environment set up and work through your first few reviews with help on hand to understand how the guidelines work.

We have just a few ground rules:

  • This isn’t a meeting with an agenda: it’s a group work day. Drop in for as long as you’re available, and get as many reviews done as you can during that time.
  • The goal is to crunch through as much of the queue as possible while helping and learning from our peers.
  • All reviewers, however new or experienced, can bring questions about how to handle particular issues. Absolutely no penalties for admitting you’re stuck ;)
  • Themers, you’re welcome to join in the discussion, try your hand at reviewing, or just lurk and learn the process. However, please don’t use this time to ask about when your own theme will be done — we’re taking everything in queue order, and we’d most likely just encourage you to sign on to review a few themes.
  • For new or potential reviewers, more experienced people will try to help out as much as we can with getting started, working with trac, setting up your test environment and the like.


Minimum Viable Theme Review

I saw yet another version of a conversation I’ve had over and over again roll by on Twitter last night. A client comes to a dev with a theme they’ve already bought — maybe they thought they could DIY and got stuck; maybe they found the look they really want and they just want to hire a freelancer for some tweaks. It doesn’t really matter. Either way, the next thing that happens in this story is

… because the theme in question is a non-standard pile of deprecated functions held together with duct tape, baling wire, and spit.

So I’m proposing that every WordPress theme that’s intended to be used by anyone other than the original developer1 should be good enough to pass a very abbreviated Minimum Viable Theme Review2:

  1. Develop with WP_DEBUG on. If you see any warnings and whatnots printing out at the top of the screen, whether in admin or the front end, fix those first.
  2. Run your theme through Theme Check. Yes, some of the requirements are specific to the Repo, and you don’t need to worry about your license URI unless you’re building for distribution. But the real strength of Theme Check is in finding the things you could be doing in a more WordPress-ish way. Still using a years-old hack to add a menu, or hand-coding feed links in your header? Yeah, don’t do that. Theme Check will give you all that stuff in a handy color-coded and prioritized list.
  3. Load up the Theme Unit Test Data and eyeball all the pages and posts. It’s designed to make it very clear when you’ve forgotten to style something or account for some use case. Because I promise some user, somewhere, is going to load up an oversized picture, and not actually want it to overlap the sidebars; or they’ll want to use an ordered list, and they don’t expect it to come out exactly like an unordered list. And in my experience, that user is usually me.

Look, I’m not saying that every theme needs to go through a full wptrt-style review process (although a gal can dream!). But as a starting point, it doesn’t seem a lot to ask that any theme that’s released in the wild should 1) Not break WordPress 2) Do core WordPress stuff the way it’s supposed to, and 3) Display the end user’s content the way they meant it to be displayed.

  1. And remember that “yourself in six months” counts as someone else. Don’t believe me? Think of the headdesk when you read your old code.
  2. Yes, before you ask, all examples are real

“Without a plugin” considered dangerous

Like a lot of devs, I’m sadly addicted to all the many tips and how-tos and tutorials that float around in the WPverse. Some of them are utterly brilliant. A very few of them open my eyes to new ways of doing things that I couldn’t even have imagined doing the old way. But far more often, I follow a link that leads to the other kind of tuts. The ones that promise that by just copying a few lines of code, you can do magical things without needing to use any plugins at all!

There’s just one problem with this. Plugins exist for a very good reason: to add non-core functionality 1 to your site without hosing up the whole lot.

Much more importantly, a plugin is the right way to do it the great majority of the time. There’s a whole Plugin API that exists just to make it possible to hook your code to WordPress with minimal fuss! Those really cool new features you love were first tried out and gained traction as plugins! And anyway, there are really only two other choices:

  1. Edit your theme’s functions.php. This works just fine, because code in functions.php will be included just the way a plugin would be2. Except for the small fact that now you — and more importantly, your users and clients — are stuck with that theme. Wanna change themes as your mood strikes you? Or just update to a newer version? Say goodbye to all that new functionality. As one friend of mine puts it, when you repaint the bathroom, you don’t normally expect the toilet to vanish…
  2. Hack core. Congratulations, you have now fucked your site. At best, you’re now unable to upgrade WordPress (including security updates) without losing your tweaks. At worst, you’ve introduced entirely new issues: because if you’re hacking core just to add a new widget or dongle or gizmo, you probably didn’t read the code all that carefully, now did you?
To sum up:


  1. By “non-core” I don’t mean “unpopular” or “not useful” or even “not something I might need to build an entire site around”. Just… not in core.
  2. Please take this fact as a hint that a plugin is a perfectly normal and acceptable way to do things