What many people don’t know is that the current taxonomy schema was added way back in WordPress 2.3. Yes, that means the ability to create and use custom taxonomies has been around since 2007. We didn’t get all the cool functions added until 2.8 though.

However, one thing we’ve had since 2.3 was the ability to create taxonomies for any object type, not just posts. In WordPress, there are several object types:

• Posts
• Users
• Comments
• Links

So, you can technically create a taxonomy for any object type. Most of WordPress core support is for posts, but the API is extremely well thought out and can handle the other object types with minimal code effort.

This tutorial will focus on registering and using a taxonomy on the user object type. It will not be a 100% solution for everything you can do with a custom user taxonomy. Consider this an extremely rough draft of what’s possible.

Because this is such an in-depth topic, I cannot explain every minute detail. That would make for about a 50-page tutorial. You’ll need to be familiar with a few key areas in WordPress development before proceeding: plugins, themes, users, and taxonomies.

Registering a user taxonomy

In this tutorial, you will use and register a taxonomy called “Profession.” This is just an example, so feel free to experiment and create your own taxonomies for your uses.

To register the user taxonomy, you use the register_taxonomy() function just like you would with any other taxonomy. The following code block will register the profession taxonomy and set up its arguments.

/**
 * Registers the 'profession' taxonomy for users.  This is a taxonomy for the 'user' object type rather than a
 * post being the object type.
 */
function my_register_user_taxonomy() {

	 register_taxonomy(
		'profession',
		'user',
		array(
			'public' => true,
			'labels' => array(
				'name' => __( 'Professions' ),
				'singular_name' => __( 'Profession' ),
				'menu_name' => __( 'Professions' ),
				'search_items' => __( 'Search Professions' ),
				'popular_items' => __( 'Popular Professions' ),
				'all_items' => __( 'All Professions' ),
				'edit_item' => __( 'Edit Profession' ),
				'update_item' => __( 'Update Profession' ),
				'add_new_item' => __( 'Add New Profession' ),
				'new_item_name' => __( 'New Profession Name' ),
				'separate_items_with_commas' => __( 'Separate professions with commas' ),
				'add_or_remove_items' => __( 'Add or remove professions' ),
				'choose_from_most_used' => __( 'Choose from the most popular professions' ),
			),
			'rewrite' => array(
				'with_front' => true,
				'slug' => 'author/profession' // Use 'author' (default WP user slug).
			),
			'capabilities' => array(
				'manage_terms' => 'edit_users', // Using 'edit_users' cap to keep this simple.
				'edit_terms'   => 'edit_users',
				'delete_terms' => 'edit_users',
				'assign_terms' => 'read',
			),
			'update_count_callback' => 'my_update_profession_count' // Use a custom function to update the count.
		)
	);
}

I won’t cover all the arguments used in the code above. I’ve written about those in a previous tutorial. However, there are a few arguments you should pay careful attention to:

• rewrite['slug']: I used author/profession so that the slug would fall in line with the WordPress user slug, author. We’ll need a slight fix for this too, which I’ll get to later in the tutorial.
• capabilities: For simplicity, I’ve set most of the capabilities to edit_users. Only administrators can manage, edit, and delete professions with this by default. The assign_terms capability is set to read so all users can edit this on their profile page. You’ll want to set up some custom capabilities or configure this to do what you want.
• update_count_callback: You must use a custom function for this because WordPress expects the taxonomy to be for the post object type.

Once you’ve registered your taxonomy, WordPress really doesn’t do much for you. It won’t add any custom admin pages, meta boxes, or anything of the sort like it does for posts. That’ll be left up to you.

Custom term update count callback

Right off the bat, you’ll already need some custom code. Since WordPress will only update the term counts for taxonomies on posts, you’ll need a function to do this for users.

When you registered your taxonomy, you set the update_count_callback argument to my_update_profession_count. The following code is that callback function.

/**
 * Function for updating the 'profession' taxonomy count.  What this does is update the count of a specific term
 * by the number of users that have been given the term.  We're not doing any checks for users specifically here.
 * We're just updating the count with no specifics for simplicity.
 *
 * See the _update_post_term_count() function in WordPress for more info.
 *
 * @param array $terms List of Term taxonomy IDs
 * @param object $taxonomy Current taxonomy object of terms
 */
function my_update_profession_count( $terms, $taxonomy ) {
	global $wpdb;

	foreach ( (array) $terms as $term ) {

		$count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $term ) );

		do_action( 'edit_term_taxonomy', $term, $taxonomy );
		$wpdb->update( $wpdb->term_taxonomy, compact( 'count' ), array( 'term_taxonomy_id' => $term ) );
		do_action( 'edited_term_taxonomy', $term, $taxonomy );
	}
}

I just kept this extremely simple and modified the _update_post_term_count() WordPress function. Feel free to further modify it to suit your needs.

Creating the manage terms page

Since WordPress does not create an admin page for managing terms of custom user taxonomies, you’ll need to create that. For the sake of simplicity and laziness, I just used the admin page WordPress already uses for other taxonomies.

The problem with this is that WordPress doesn’t recognize that the “Professions” admin page is a sub-menu of the “Users” admin page when viewing it. The sub-menu is placed correctly, but when clicking on it, the “Posts” menu is opened in the admin. I’d really love to see some WordPress core support for this.

Update: See the comment by James below to get a fix for this.

The following code is what I used, but you can definitely create a custom admin page for managing your terms.

/* Adds the taxonomy page in the admin. */
add_action( 'admin_menu', 'my_add_profession_admin_page' );

/**
 * Creates the admin page for the 'profession' taxonomy under the 'Users' menu.  It works the same as any
 * other taxonomy page in the admin.  However, this is kind of hacky and is meant as a quick solution.  When
 * clicking on the menu item in the admin, WordPress' menu system thinks you're viewing something under 'Posts'
 * instead of 'Users'.  We really need WP core support for this.
 */
function my_add_profession_admin_page() {

	$tax = get_taxonomy( 'profession' );

	add_users_page(
		esc_attr( $tax->labels->menu_name ),
		esc_attr( $tax->labels->menu_name ),
		$tax->cap->manage_terms,
		'edit-tags.php?taxonomy=' . $tax->name
	);
}

This will at least allow you to create and manage custom terms of the profession taxonomy. If you have a better solution for this, please post it in the comments for other people to see.

Fixing the “Posts” column

After creating the admin page, you probably noticed a column on it called “Posts.” Instead, it should display a “Users” column. The following code will fix this issue and list the number of users with each term from the profession taxonomy.

/* Create custom columns for the manage profession page. */
add_filter( 'manage_edit-profession_columns', 'my_manage_profession_user_column' );

/**
 * Unsets the 'posts' column and adds a 'users' column on the manage profession admin page.
 *
 * @param array $columns An array of columns to be shown in the manage terms table.
 */
function my_manage_profession_user_column( $columns ) {

	unset( $columns['posts'] );

	$columns['users'] = __( 'Users' );

	return $columns;
}

/* Customize the output of the custom column on the manage professions page. */
add_action( 'manage_profession_custom_column', 'my_manage_profession_column', 10, 3 );

/**
 * Displays content for custom columns on the manage professions page in the admin.
 *
 * @param string $display WP just passes an empty string here.
 * @param string $column The name of the custom column.
 * @param int $term_id The ID of the term being displayed in the table.
 */
function my_manage_profession_column( $display, $column, $term_id ) {

	if ( 'users' === $column ) {
		$term = get_term( $term_id, 'profession' );
		echo $term->count;
	}
}

Assigning terms to users

Thus far, you’ve got a custom taxonomy and can add terms for it, but you need a way to assign these terms to individual users. For this example, you’ll be adding a custom section to the edit user/profile page in the admin. It will display a list of radio select boxes so the user can choose their profession.

This is just an extremely basic example. You have tons of room for customization. You can do select elements, checkboxes, a text input, or whatever best works for you.

The following PHP code will add this section to the edit user/profile page.

/* Add section to the edit user page in the admin to select profession. */
add_action( 'show_user_profile', 'my_edit_user_profession_section' );
add_action( 'edit_user_profile', 'my_edit_user_profession_section' );

/**
 * Adds an additional settings section on the edit user/profile page in the admin.  This section allows users to
 * select a profession from a checkbox of terms from the profession taxonomy.  This is just one example of
 * many ways this can be handled.
 *
 * @param object $user The user object currently being edited.
 */
function my_edit_user_profession_section( $user ) {

	$tax = get_taxonomy( 'profession' );

	/* Make sure the user can assign terms of the profession taxonomy before proceeding. */
	if ( !current_user_can( $tax->cap->assign_terms ) )
		return;

	/* Get the terms of the 'profession' taxonomy. */
	$terms = get_terms( 'profession', array( 'hide_empty' => false ) ); ?>

	<h3><?php _e( 'Profession' ); ?></h3>

	<table class="form-table">

		<tr>
			<th><label for="profession"><?php _e( 'Select Profession' ); ?></label></th>

			<td><?php

			/* If there are any profession terms, loop through them and display checkboxes. */
			if ( !empty( $terms ) ) {

				foreach ( $terms as $term ) { ?>
					<input type="radio" name="profession" id="profession-<?php echo esc_attr( $term->slug ); ?>" value="<?php echo esc_attr( $term->slug ); ?>" <?php checked( true, is_object_in_term( $user->ID, 'profession', $term ) ); ?> /> <label for="profession-<?php echo esc_attr( $term->slug ); ?>"><?php echo $term->name; ?></label> <br />
				<?php }
			}

			/* If there are no profession terms, display a message. */
			else {
				_e( 'There are no professions available.' );
			}

			?></td>
		</tr>

	</table>
<?php }

After adding the preceding code, you’ll get a new section near the bottom of your edit user/profile page that looks like the following screenshot.

You’ll need a way to save the selected term (profession) for the user. The next code block will handle that.

/* Update the profession terms when the edit user page is updated. */
add_action( 'personal_options_update', 'my_save_user_profession_terms' );
add_action( 'edit_user_profile_update', 'my_save_user_profession_terms' );

/**
 * Saves the term selected on the edit user/profile page in the admin. This function is triggered when the page
 * is updated.  We just grab the posted data and use wp_set_object_terms() to save it.
 *
 * @param int $user_id The ID of the user to save the terms for.
 */
function my_save_user_profession_terms( $user_id ) {

	$tax = get_taxonomy( 'profession' );

	/* Make sure the current user can edit the user and assign terms before proceeding. */
	if ( !current_user_can( 'edit_user', $user_id ) && current_user_can( $tax->cap->assign_terms ) )
		return false;

	$term = esc_attr( $_POST['profession'] );

	/* Sets the terms (we're just using a single term) for the user. */
	wp_set_object_terms( $user_id, array( $term ), 'profession', false);

	clean_object_term_cache( $user_id, 'profession' );
}

Displaying user taxonomy terms

You can use any of the standard WordPress taxonomy functions for listing out your terms. For example, wp_list_categories() and wp_tag_cloud() will both work fine. Each will link to the term archive page (covered in the section below).

If you wanted to show a tag cloud with all of your “professions” (profession cloud) in a theme template, your code would look something like the following.

<?php wp_tag_cloud( array( 'taxonomy' => 'profession' ) ); ?>

One thing to look out for though is that the title attribute for links in the tag cloud will read “1 topic” or “X topics.” An easy way to change this is to write a custom callback function to modify the text. In the following screenshot, you can see this changed from “topics” to “users”.

The following code block is a function that will handle that.

/**
 * Function for outputting the correct text in a tag cloud.  Use as the 'update_topic_count_callback' argument
 * when calling wp_tag_cloud().  Instead of 'topics' it displays 'users'.
 *
 * @param int $count The count of the objects for the term.
 */
function my_profession_count_text( $count ) {
	return sprintf( _n('%s user', '%s users', $count ), number_format_i18n( $count ) );
}

You’d use it when displaying your tag cloud like so:

<?php wp_tag_cloud(
	array(
		'taxonomy' => 'profession',
		'topic_count_text_callback' => 'my_profession_count_text'
	)
); ?>

Templates for term archives

The template for term archives is handled the same as any other taxonomy. So, if you wanted to create a custom template (you probably should) for your theme to display users by profession, you’ll want to create a template named taxonomy-profession.php.

I won’t cover creating theme templates here. It’s outside the scope of this tutorial.

The big difference between this template and a normal template is there’s no post loop. Instead, you need to create a user loop. The following code should replace your normal post loop in this template.

<?php
$term_id = get_queried_object_id();
$term = get_queried_object();

$users = get_objects_in_term( $term_id, $term->taxonomy );

if ( !empty( $users ) ) {
?>
	<?php foreach ( $users as $user_id ) { ?>

		<div class="user-entry">
			<?php echo get_avatar( get_the_author_meta( 'email', $user_id ), '96' ); ?>
			<h2 class="user-title"><a href="<?php echo esc_url( get_author_posts_url( $user_id ) ); ?>"><?php the_author_meta( 'display_name', $user_id ); ?></a></h2>

			<div class="description">
				<?php echo wpautop( get_the_author_meta( 'description', $user_id ) ); ?>
			</div>
		</div>

	<?php } ?>
<?php } ?>

The most important function used in the code above is the WordPress get_objects_in_term() function. By putting in a term ID and taxonomy name, you can grab an array of all the object (user) IDs with that term (profession). With the user ID, you can load any information about a user you want with any standard WordPress functions.

Of course, you’re free to customize this however you want. The preceding code merely loops through each of the users with a specific profession. It then displays each user’s avatar, name with a link to their posts archive, and description.

Disabling the ‘profession’ username

When you registered the profession taxonomy, you created the slug author/profession so that the profession archive pages would have a URL like yoursite.com/author/profession/designer. The problem with this that “profession” could potentially be a username someone signs up to your site with.

The following code will make sure no one can sign up with this username:

/* Filter the 'sanitize_user' to disable username. */
add_filter( 'sanitize_user', 'my_disable_username' );

/**
 * Disables the 'profession' username when someone registers.  This is to avoid any conflicts with the custom
 * 'author/profession' slug used for the 'rewrite' argument when registering the 'profession' taxonomy.  This
 * will cause WordPress to output an error that the username is invalid if it matches 'profession'.
 *
 * @param string $username The username of the user before registration is complete.
 */
function my_disable_username( $username ) {

	if ( 'profession' === $username )
		$username = '';

	return $username;
}

Of course, if you use a different rewrite structure for your taxonomy, don’t worry about that code.

Time to create your own user taxonomies

Whoah! That was certainly a ton of information to cover in a single tutorial. I’m sure some of you have questions, so please ask away in the comments.

Now it’s time for you to venture out on your own and create some cool stuff. I’d love to hear what ideas you have and see any projects that you use this code in. I’m definitely interested in seeing some practical, real-world use cases of user taxonomies.

One final note: The code in this tutorial is just something I played around with in about a two-hour span. It’s still a work in progress. Honestly, it took me much longer to write this tutorial. Therefore, I leave it up to you, dear reader, to improve upon the code.

If you haven’t already done so, you need to read through the earlier posts in this tutorial series to do some catching up. From this point forward, you’ll be expected to know the lessons taught in previous tutorials.

Basic template structure

Most WordPress themes will have a few basic templates that define the overall structure of the theme:

• index.php
• header.php
• footer.php
• sidebar.php

The following screenshot shows a simple overview of what these templates might look like in a finished theme design.

What are templates?

The term “template” can be a bit confusing, especially since it’s easily interchangeable with the terms “theme” and “skin.” In WordPress it means something different. A template in WordPress is a PHP file that is used for the display of content on the front end of the site.

For those of you familiar with creating HTML Web pages, you’re probably accustomed to creating a single HTML file and having it display all of the content on the page. In WordPress, each part of the page is broken into separate sections. The reason for this is that WordPress is a dynamic system, which runs an entire Web site rather than just a single page.

Having the templates separated allows you to re-use templates across different page views. For example, the header.php file contains all of the content the header of a site would display. Instead of creating many files with the same header information over and over, you can use a single file (template) to display this information on all pages.

index.php

The index.php template is the default template for displaying content (blog posts, pages, etc.) on a site. There are other files that can overwrite it, but you’ll learn about those in a later tutorial. For now, you’ll learn about its most important function: holding everything together.

When any page on a WordPress site is loaded, it looks for a template. In our case, this is the index.php template. It will be the template that’s expected to display the page.

In part 1 of this tutorial series, you created an empty index.php file. You need to open this file in your text editor. Type the following code in this file.

<?php get_header(); // Load the header.php template. ?>

<div id="content">

</div><!-- #content -->

<?php get_footer(); // Load the footer.php template. ?>

This code does several things:

• Uses the WordPress function get_header() to load the header.php template.
• Defines some basic HTML for the structure of our future content.
• Uses the WordPress function get_footer() to load the footer.php template.

Don’t worry if you don’t understand those PHP functions. You’ll learn more about them in the next tutorials.

header.php

In the previous section, you used a PHP function called get_header() to load a template called header.php. Since this file doesn’t exist yet, you’ll need to create it. So, create a new file using your text editor called header.php and save it within your theme folder.

Remember, your theme folder’s name is super-mario, so the files in your theme should look like the following at this point.

• super-mario
  • header.php
  • index.php
  • style.css

Once you’ve created your header.php template, type the following code into it.

<!DOCTYPE html>
<html>
<head>

<title>Example</title>

<link rel="stylesheet" href="style.css" type="text/css" media="all" />

</head>

<body class="wordpress">

	<div id="container">

		<div id="header">

		</div><!-- #header -->

		<div id="main">

What the preceding code does is define a simple HTML structure for your header. Those of you familiar with basic Web pages and HTML, this should look familiar to you. There’s no PHP code involved at all at this point for the header. You’ll learn about that later.

footer.php

The footer template should close out all open HTML tags that were opened in the header template.

In the index.php section of this tutorial, you used the get_footer() function to load the footer.php template. Just as you did with the header template, create a new file with your text editor called footer.php and place it within your theme folder.

Now, type the following code into the file.

			<?php get_sidebar(); // Load the sidebar.php template. ?>

		</div><!-- #main -->

		<div id="footer">

		</div><!-- #footer -->

	</div><!-- #container -->

</body>
</html>

As you can see, these are mostly all closing HTML tags. You probably also noticed the PHP function call to get_sidebar(), which is a WordPress function for loading the sidebar.php template.

sidebar.php

A sidebar is a template in WordPress for displaying content in addition to the main page content. For now, you’ll just be building the basic HTML structure for a single sidebar.

Once again, crack open your favorite text editor. This time, create a new file called sidebar.php and place it within your theme folder alongside your new header.php and footer.php templates.

Type the following code in your sidebar.php template.

<div id="sidebar">

</div><!-- #sidebar -->

When do we get to the good stuff?

I know. I know. You’re really itching to make your theme actually do something. Remember, you need to learn to crawl before you can walk. It’s better to learn how some of the basic functionality comes together before you dive head first into more advanced things. You’ll get lost later without a solid foundation to build from.

In the next three tutorials, you’ll learn how to make your header.php, footer.php, and index.php templates display content from WordPress, so get ready. This tutorial series is about to get a little more complex. Therefore, you should feel good in knowing that you’re learning the basics now.

Downloads

If you want to see all of today’s lesson files, download a zip file of the theme. This version builds on the version from the previous tutorial, so there’ll be files included from that lesson too.

Good. I’ll assume you’ve already read through the introduction post of this series and prepared yourself. If not, go ahead and do that now.

In this tutorial, you will learn how to create your first WordPress theme.

Naming your theme

I’ll assume you’re already thinking up some crafty names for your first theme. The one thing you might not have thought of is that there are some rules for naming WordPress themes. Technically, you can name your theme anything. However, if you want to have it hosted on the WordPress theme repository, you’ll need to follow its guidelines on naming.

In short, don’t put these things in your theme name:

• The term “WordPress”.
• The term “Theme”.
• Version-specific or markup-related terms.
• Your name or site name.

Basically, don’t put things that are irrelevant to the actual theme. Be creative. Come up with something fun that represents your theme.

Throughout this series, we’ll be building a theme from start to finish. The name of the theme will be Super Mario. Why? Well, it’s just cool. And, we have to name it something.

Creating a theme folder

Before diving into any files or code, you need to have a theme folder. All theme files are kept within a single folder, so your theme will need one.

Since the name of the theme is “Super Mario,” the theme folder name should be super-mario.

As a sidenote, any theme folders or filenames you create should contain all lowercase letters and use hyphens if it has multiple words. This is the general standard used in WordPress file/folder naming.

Your theme folder should be placed within your wp-content/themes directory. The directory structure should be set up like the following.

• wp-content
  • themes
    • super-mario

Or, if you prefer, take a look at how this is set up in the following screenshot.

The style.css file

All WordPress themes require at least two files to work. The first of these files is style.css. This is the most important file because it houses your theme information.

So, the next step you should take is to create a new file called style.css with your preferred text editor. This file should be saved within your super-mario theme folder.

Using your text editor, type the below code into your style.css file.

/**
 * Theme Name: Super Mario
 * Theme URI: http://devpress.com
 * Description: An example theme description.
 * Author: Your Name
 * Author URI: http://devpress.com
 * Version: 0.1
 * Tags: threaded-comments, translation-ready, two-columns, fixed-width
 * License: GNU General Public License v2.0
 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
 */

This information is called the Theme File Header. Each new line in the file header is called a “header” and represents a distinct key/value pair.

• Theme Name: This is the name of your theme. Remember the rules you learned earlier on properly naming your theme.
• Theme URI: This is the URI to your theme’s page. If submitting your theme to the WordPress theme repository, make sure to follow the guidelines on credit links.
• Description: The description of your theme. Simple enough. Don’t write a novel here. Keep it short and descriptive.
• Author: Your name.
• Author URI: This should be a link to your personal or WordPress site. Again, make sure to follow the theme review guidelines on credit links if submitting to the repo.
• Tags: These are a way to label what features your theme has. WordPress.org has a standard set of allowed tags you can use.
• License: What license your theme is under. This is not currently a standard in WordPress but is required for repository-hosted themes.
• License URI: A link to a page where your theme’s license can be read in full.

Once you’ve gotten all of your theme information added, you can save your style.css file. You won’t need it for the remainder of this tutorial. Most likely, you’ll edit your theme info later as you figure out the features your theme will have.

The index.php template

I won’t cover templates in detail just yet. You’ll learn about them in another tutorial. However, you do need one template to have a real WordPress theme: index.php. This is the second required file for a WordPress theme to work.

Open your text editor and create a new file called index.php. Save this file in your super-mario folder. Don’t type anything in this file just yet. You’ll learn what to do with it later. For now, you’re done.

Congratulations!

You’ve just created your first WordPress theme! Of course, your theme doesn’t actually do anything yet. It doesn’t show blog posts, have nav menus, or display widgets. You’ve still got a long journey ahead of you.

Now, pat yourself on the back and relax. There’s lots more to come in the next tutorial.

Downloads

In each tutorial of this series that has code, I’ll provide a download link to the day’s lesson in theme form. This will be a a zipped theme folder with the current, combined code of the theme you’re learning to build.

So, go ahead and download a copy of today’s version of the theme.

I want to start this post by giving credit where it’s due. When I first started creating my own WordPress themes, this tutorial taught me everything. I know a ton of other theme developers who learned from him. Honestly, I should’ve just written a post thanking him for what he gave back to the community during that time.

It’s amazing how time flies. It’s now been just over four years since the completion of the series. Things have changed quite dramatically in the WordPress theme landscape since then. The original series still has a lot to offer, but it’s definitely showing its age.

Many have attempted to recreate the magic of that old set of tutorials, but no one has truly topped it. That will be my goal. I will attempt to write a better tutorial series on the topic, one that’s now long overdue in the WordPress community.

What this tutorial series is about

I have a strict philosophy on what belongs in WordPress themes. That philosophy will be the driving force behind this series. I will teach you how to create themes that use WordPress standards and don’t have a ton of plugin functionality thrown into the mix.

I plan to strip theme development down to its bare essentials. You will be taught the standard functions and be given the skills you need to get started creating your own themes.

If you create a theme after following this tutorial series, your theme will have a high likelihood of passing the theme review guidelines. Therefore, you shouldn’t have any issues getting your theme hosted on the WordPress theme repository. You will also have a more solid code base than 90% of the commercial themes I’ve seen.

This series of tutorials will be geared toward absolute beginners to theme development. However, there will be bits and pieces that seasoned developers can use.

Skills you need

Technically, you don’t need any skills to learn from this series aside from some familiarity with WordPress and themes. It will be a major plus if you have some beginning knowledge of:

• HTML: You can probably get by with little HTML know-how by just following this series. I highly recommend learning this in your free time though.
• CSS: I will be covering some standard WordPress CSS elements throughout the tutorial, but I can’t teach you how to design. Once you learn how to create a WordPress theme, it will be up to you to decide how to style it. You might actually want to create something pretty.
• PHP: You don’t need to know any PHP at all. WordPress actually makes this fairly simple for theme developers. I will also explain all PHP used throughout the series, but knowing some basics will help tremendously.

Tools you need

I’ll keep this simple. Make sure you have these things before the first tutorial is posted:

• WordPress: You need to have a test installation of WordPress set up. I’ll assume you know how to do this beforehand. Preferably, you would set up a test install on your computer (locally). If you’re unfamiliar with this process, read Installing WordPress and Xampp.
• Test data: You can create your own test data or use the theme unit test data. This will give you some content to test your theme.
• Text/code editor: There are tons to choose from. I’m a fan of Notepad++ for its simplicity and code highlighting.

Ready to be a theme designer?

I’ll try not to overwhelm you with each tutorial in the series and break each post up into digestible parts. Just let me know if you get lost.

So, before we get started, make sure you have the proper tools. Then, you’ll be ready for the first tutorial when its published.

Fortunately, WordPress eventually introduced the wp_login_form() function, which allows you to easily display a login form anywhere on your site. Couple that with a custom shortcode and you have a recipe for some awesomeness.

This tutorial will walk you through the steps required for creating a login form shortcode to use in any shortcode-ready area (e.g., your post/page editor).

Creating a login form shortcode

The first step is opening either your theme’s functions.php file or, preferrably, a custom plugin file. You’ll want to use the following PHP code to create a function that registers shortcodes.

add_action( 'init', 'my_add_shortcodes' );

function my_add_shortcodes() {

	add_shortcode( 'my-login-form', 'my_login_form_shortcode' );
}

What the above code does is add your shortcodes registration function to the init hook. It then calls the WordPress function add_shortcode(), which creates a new shortcode called [my-login-form].

Before the [my-login-form] shortcode will work, you need to create the callback function that outputs the login form. The following code does this.

function my_login_form_shortcode() {

	if ( is_user_logged_in() )
		return '';

	return wp_login_form( array( 'echo' => false ) );
}

The above code checks if the current user is logged into the site. If not, it calls wp_login_form(), which returns the WordPress login form for display on the page.

As far as most shortcodes go, this one is actually fairly simple. That’s all you have to do to create a login form shortcode.

Using the login form shortcode

You would use the shortcode just like you’d use any other shortcode. You can put it within your post or page editor. Or, if you have any other shortcode-aware areas, feel free to add it to one of those.

Add the following code to your page editor and save.

[my-login-form]

Advanced tips and tricks

The following part of the tutorial is only for people who want to take their login form shortcode to the next level. None of these tips are required.

Displaying a message for logged in users

The shortcode function from earlier in this tutorial doesn’t display anything for users who are logged into the site. To display a message such as “You are already logged in!”, you only need to tweak a single line. Your shortcode function code would look like:

function my_login_form_shortcode() {

	if ( is_user_logged_in() )
		return '<p>You are already logged in!</p>';

	return wp_login_form( array( 'echo' => false ) );
}

Creating shortcode parameters

Shortcode parameters are outside the scope of this tutorial, so I won’t cover them in complete detail. This subject is covered in the shortcode API documentation. However, I will show you an example of adding in customizable “Username” and “Password” labels.

Your shortcode function would look like the following code.

function my_login_form_shortcode( $attr ) {

	if ( is_user_logged_in() )
		return '';

	/* Set up some defaults. */
	$defaults = array(
		'label_username' => 'Username',
		'label_password' => 'Password'
	);

	/* Merge the user input arguments with the defaults. */
	$attr = shortcode_atts( $defaults, $attr );

	/* Set 'echo' to 'false' because we want it to always return instead of print for shortcodes. */
	$attr['echo'] = false;

	return wp_login_form( $attr );
}

Suppose you wanted to change the “Username” text to read “Enter Username” and the “Password” text to read “Enter Password.” You’d use the following in your post editor.

[my-login-form label_username="Enter Username" label_password="Enter Password"]

CSS classes

In the screenshot of the shortcode in action earlier in the tutorial, you’ll notice that it doesn’t look too fancy. WordPress generates a few CSS classes that you can use to customize the design of your login form.

/* Username wrapper paragraph. */
.login-username {}

/* Username label. */
.login-username label {}

/* Username input. */
.login-username .input {}

/* Password wrapper paragraph. */
.login-password {}

/* Password label. */
.login-password label {}

/* Password input. */
.login-password .input {}

/* Remember me wrapper paragraph. */
.login-remember {}

/* Remember me label. */
.login-remember label {}

/* Remember me checkbox. */
.login-remember input[type="checkbox"] {}

/* Submit button wrapper paragraph. */
.login-submit {}

/* Submit button. */
.login-submit .button-primary {}

You can also define custom IDs for use in your CSS. These can be defined as arguments for the wp_login_form() function.

This tutorial will walk you through the steps of properly checking the post type of a post and in what situations to use the functions presented.

Checking the post type within The Loop

Sometimes, you may need to check a post type of a given post within the posts loop. This would most commonly be used within a theme’s templates, but there are other applications for it.

For this, you need the get_post_type() function, which returns the name of the post type.

The following code checks the post type of the current post in the loop and runs some code if the post type is either movie or book.

<?php

if ( 'movie' == get_post_type() ) {

	/* Custom code for 'movie' post type. */

} elseif ( 'book' == get_post_type() ) {

	/* Custom code for the 'book' post type. */
}

?>

Yes, it’s really that simple. If you know how to use if/else statements in PHP, you’re good to go.

Checking a post type outside of The Loop

Checking a post type either inside or outside of The Loop is nearly the same. You’d use the same function in this case: get_post_type(). However, this time, you’d need to either put in the post object or the post ID of the specific post you want to check the post type for.

Suppose you wanted to check if the post with the ID of 100 has the product post type. You’d use the following code to do so.

<?php

if ( 'product' == get_post_type( 100 ) ) {

	/* Run some code if this post has a post type of 'product'. */
}

?>

Checking a singular post’s post type

If viewing a single/singular view of a post, WordPress has a nifty function that handles this check for you: is_singular(). This function’s main purpose is to check if viewing a singular post. However, it can also be used to check if viewing a singular post of a given post type by entering the $post_type parameter as shown in the following code snippet.

is_singular( 'post' )

You can also check for multiple post types by entering an array of post types as the $post_type parameter as shown in the following code.

is_singular( array( 'post', 'page', 'attachment' ) )

Suppose you wanted to check if a user was viewing a singular post with the post type of testimonial. You can use the next code sample to perform this check.

<?php

if ( is_singular( 'testimonial' ) ) {

	/* Run some code if viewing a singular testimonial. */
}

?>

There you have it. It’s fairly easy to run these types of checks, and the required functions are already built into WordPress for you.

This is not good.

The problem with loading JavaScript like this is that it creates conflicts with other plugins and even WordPress itself. And, quite frankly, I’m tired of my number one support question response being, “Please deactivate all your plugins to see if this corrects the issue.”

In this tutorial, I will walk you through the steps of loading your JavaScript only on the pages that are specific to your plugin.

Do you need JavaScript?

Before moving on, you should ask yourself if you plugin/theme actually needs JavaScript in the admin. If you’re trying to create some fancy-schmancy tabbed interface that doesn’t use the WordPress standard UI, you’re doing it wrong.

The only time you need to load JavaScript in the WordPress admin is when it’s absolutely necessary for what your plugin or theme is doing. In most cases, you simply need to be using the standard functions already built for you in the Settings API. This requires no JavaScript whatsoever.

There are cases when additional JavaScript is necessary. That’s what this tutorial is about — appropriately loading JavaScript on your plugin pages when JavaScript is crucial to your plugin’s functionality.

The proper hooks

Forget every other bit of code you’ve seen that loads JavaScript in the admin. There’s two hooks that you can use:

• admin_enqueue_scripts: For enqueuing JavaScript files.
• admin_head-$pagename: For printing code directly to the header.

Those are the only two hooks you need to worry yourself with. Under no circumstances should you use admin_init or admin_menu (as many plugins/themes do) to load JavaScript. You should also never load scripts without a hook, which is extremely common in themes.

Loading JavaScript files

First, let’s take a look at adding a standard options page for a plugin. Your code would look something like the following.

add_action( 'admin_menu', 'my_example_settings_page' );

function my_example_settings_page() {
	add_options_page( 'DevPress Example', 'DevPress Example', 'manage_options', 'my-example-page-name', 'my_callback_function' );
}

This is fairly standard for most developers. The trick is to figure out how to load JavaScript only on that page.

Let’s assume you need to load a JavaScript file using the wp_enqueue_script() function. Your code would look like the following.

add_action( 'admin_menu', 'my_example_settings_page' );

function my_example_settings_page() {
	global $my_settings_page;

	$my_settings_page = add_options_page( 'DevPress Example', 'DevPress Example', 'manage_options', 'my-example-page-name', 'my_callback_function' );

	add_action( 'admin_enqueue_scripts', 'my_admin_enqueue_scripts' );
}

function my_admin_enqueue_scripts( $hook_suffix ) {
	global $my_settings_page;

	if ( $my_settings_page == $hook_suffix )
		wp_enqueue_script( 'my-example' );
}

When you add an action to the admin_enqueue_scripts hook, your action (function) gets passed the parameter of $hook_suffix. What this allows you to do is check if $hook_suffix matches the name of the plugin’s settings page. $hook_suffix will change depending on the page that’s currently being viewed in the admin. Therefore, your script will only load when it’s needed.

Printing JavaScript in the admin <head>

Let’s suppose you’re just adding an extremely small snippet of code to the admin <head> area. Again, you don’t want to load this on all pages in the admin, even if it’s just a couple of lines. It can still conflict with other plugins. So, let’s build off your original settings page function. Your code would look like the following.

add_action( 'admin_menu', 'my_example_settings_page' );

function my_example_settings_page() {

	$my_settings_page = add_options_page( 'DevPress Example', 'DevPress Example', 'manage_options', 'my-example-page-name', 'my_callback_function' );

	add_action( "admin_head-{$my_settings_page}", 'my_admin_head_script' );
}

function my_admin_head_script() { ?>

<script type="text/javascript"></script>

<?php }

What we’ve done here is use the admin_head-$pagename hook to load a custom script only in the header for the plugin’s settings page. $pagename is just the name of the page currently being viewed in the admin.

Not just for scripts

This isn’t too hard. I’m not asking that you learn how to program nuclear missiles for launch. If you’re knowledgeable enough to add a custom settings page and add JavaScript in the WordPress admin, it should take you all of 30 seconds to appropriately load your scripts so that they don’t load on other admin pages.

Don’t stop with JavaScript though. The exact same rules apply for custom stylesheets too. You should even use the same hooks.

Sure, I could switch over to the visual editor, but I hate the visual editor more than I hate people who kill kittens for fun. I haven’t used it in at least four years and will likely not be switching over any time soon.

There is a growing group of people who would like to see the font reverted. However, Matt Thomas does have a reasonable argument for the change to a monospace font.

Let’s not focus on the argument over what fonts to use though. WordPress makes this extremely easy to change. It only takes a few lines of code.

How to change the font

In your theme’s functions.php file or in a plugin file, add the following lines of code to change the font stack.

add_action( 'admin_head-post.php', 'my_fix_html_editor_font' );
add_action( 'admin_head-post-new.php', 'my_fix_html_editor_font' );

function my_fix_html_editor_font() { ?>
<style type="text/css">#editorcontainer #content, #wp_mce_fullscreen { font-family: Georgia, "Times New Roman", "Bitstream Charter", Times, serif; }</style>
<?php }

This will give you a font stack of:

• Georgia
• Times New Roman
• Bitstream Charter
• Times
• serif

You are, of course, free to change this font to whatever you want. I’m about to play around with my font size and line height a bit to make the writing experience even more enjoyable.

What the change looks like

The original font will look like the following screenshot.

The new look, using the code from above, will look like the next screenshot.

In this tutorial, I will walk you through using, designing, and customizing the output of the [caption] shortcode.

How to add images with captions

Many of you might already be aware of how to do this, but let’s cover the basics for those WordPress users who don’t.

To add an image caption, you must first upload an image using the WordPress media uploader. Once you’ve uploaded an image, you should see an input box labeled “Caption,” which is where you’d add your image caption, as shown in the following screenshot.

To insert the image with a caption into your post, you’d simply click the “Insert into Post” button just like you would with any other image.

What this looks like on the front end of your site will depend entirely on your theme’s design, but it will look something like the following screenshot.

That’s pretty much everything you need to know about the most common use of captions in WordPress. Keep reading though. You might learn a few more neat tricks.

How to add captions to other elements

Many WordPress users are unaware that captions can be used for more than just images. Yes, you can wrap any element with a caption. You can even wrap other shortcodes with a caption. In fact, let’s give that a try.

In this example, let’s wrap a Vimeo video using the [embed] shortcode with a custom caption.

When you normally embed a video using the [embed] shortcode, it would look like the following line of code in your post editor.

[embed]http://vimeo.com/14580921[/embed]

Let’s take one more step and add a custom caption. There are two requirements for using the [caption] shortcode: you must input both the width and caption attributes. Here’s what your new video/caption combo should look like in the the post editor:

[caption width="600" caption="A football video"][embed]http://vimeo.com/14580921[/embed][/caption]

When viewing the post on the front end of your site, you should see a caption for your video as shown in the following screenshot.

One thing I do need to note is that not all themes were designed to handle anything other than images within captions. This is simply because the most common use of captions is to wrap images. So, don’t be too hard on your theme developer if the design is a little off when trying this out.

[caption] attributes

The [caption] shortcode has several attributes that you may customize:

• id: A unique HTML ID that you can change to use within your CSS.
• align: The alignment of the caption within the post. Valid values are: alignnone (default), aligncenter, alignright, and alignleft.
• width: How wide the caption should be in pixels. This attribute is required and must have a value greater than or equal to 1.
• caption: The actual text of your caption. This attribute is required, of course.

Let’s go back to the first example from this tutorial (adding an image caption) and look at the shortcode that WordPress added.

[caption id="attachment_6" align="alignright" width="300" caption="The Great Wave"]<img src="http://localhost/wp-content/uploads/2010/07/800px-Great_Wave_off_Kanagawa2-300x205.jpg" alt="Kanagawa" title="The Great Wave" width="300" height="205" class="size-medium wp-image-6" />[/caption]

As you can see, each of the attributes are used in this example. You can customize those attributes to your liking within the post editor.

Designing image captions

I’m not going to teach you how to design your captions (we might get Tung to do that in a later post). But, I am going to give you some basic CSS to start with. Let your imagination run wild.

Use the following classes in your theme’s style.css file to customize the appearance of captions.

/* The wrapper <div> for the caption and captioned element. */
.wp-caption { }

/* The caption text. */
.wp-caption-text { }

/* An image within the caption (you might want to style other elements too). */
.wp-caption img { }

One thing to keep in mind is that WordPress automatically adds an extra 10px of width to the caption using an inline style. You can either wrestle with styles for that or see the next section of this tutorial.

Customizing the caption output

WordPress allows you to modify the HTML output of the [caption] shortcode by using a custom filter on the img_caption_shortcode hook. You can use it to change up things however you want. In this particular example, you’ll learn how to fix a minor issue with captions.

If you’re a WordPress theme developer, you’ve likely had a headache or two from styling the [caption] shortcode in WordPress. Well, if you’ve ever tried to do anything other than the generic box around an image thing, you’ve probably hit some snags. WordPress adds 10px of extra width to its caption wrapper. I assume this was to make it easier to use the box-style captions. However, not all captions are designed to have a basic border and look all boxy.

The following code removes the additional 10px of width that WordPress would normally add.

add_filter( 'img_caption_shortcode', 'cleaner_caption', 10, 3 );

function cleaner_caption( $output, $attr, $content ) {

	/* We're not worried abut captions in feeds, so just return the output here. */
	if ( is_feed() )
		return $output;

	/* Set up the default arguments. */
	$defaults = array(
		'id' => '',
		'align' => 'alignnone',
		'width' => '',
		'caption' => ''
	);

	/* Merge the defaults with user input. */
	$attr = shortcode_atts( $defaults, $attr );

	/* If the width is less than 1 or there is no caption, return the content wrapped between the [caption]< tags. */
	if ( 1 > $attr['width'] || empty( $attr['caption'] ) )
		return $content;

	/* Set up the attributes for the caption <div>. */
	$attributes = ( !empty( $attr['id'] ) ? ' id="' . esc_attr( $attr['id'] ) . '"' : '' );
	$attributes .= ' class="wp-caption ' . esc_attr( $attr['align'] ) . '"';
	$attributes .= ' style="width: ' . esc_attr( $attr['width'] ) . 'px"';

	/* Open the caption <div>. */
	$output = '<div' . $attributes .'>';

	/* Allow shortcodes for the content the caption was created for. */
	$output .= do_shortcode( $content );

	/* Append the caption text. */
	$output .= '<p class="wp-caption-text">' . $attr['caption'] . '</p>';

	/* Close the caption </div>. */
	$output .= '</div>';

	/* Return the formatted, clean caption. */
	return $output;
}

If you really want to try out something cool, try modifying the above code to use the <figure> and <figcaption> elements from HTML5.

Play around with some captions

Now that you’ve learned just about everything you need to know about captions, it’s time to go play around with them a bit.

I highly encourage WordPress theme developers to test out captions with elements other than images. I’m sure you could come up with some neat designs ideas.