Now that we know where to save the files within our theme, we need to start building those files. While we’ll probably end up creating several more files, we technically only require two files to set up a valid theme:

The styles.css file is the more crucial of the two, and is the first file that WordPress will look for when it gathers information about your theme prior to activation. Similar to the way in which it recognizes plugins, WordPress searches for a standardized header at the very top of the styles.css file to gather pertinent information about your theme. Since we won’t be creating our own full-blown theme here within this chapter, let’s take a look at how the team over at WordPress.org has done it with their latest and greatest theme, Twenty Eleven:

/*
Theme Name: Twenty Eleven
Theme URI: http://wordpress.org/extend/themes/twentyeleven
Author: the WordPress team
Author URI: http://wordpress.org/
Description: The 2011 theme for WordPress is sophisticated, lightweight, and 
  adaptable. Make it yours with a custom menu, header image, and background -- 
  then go further with available theme options for light or dark color scheme, 
  custom link colors, and three layout choices. Twenty Eleven comes equipped 
  with a Showcase page template that transforms your front page into a showcase 
  to show off your best content, widget support galore (sidebar, three footer 
  areas, and a Showcase page widget area), and a custom "Ephemera" widget to 
  display your Aside, Link, Quote, or Status posts. Included are styles for 
  print and for the admin editor, support for featured images (as custom header
  images on posts and pages and as large images on featured "sticky" posts), and 
  special styles for six different post formats.
Version: 1.0
License: GNU General Public License
License URI: license.txt
Tags: dark, light, white, black, gray, one-column, two-columns, left-sidebar,
  right-sidebar, fixed-width, flexible-width, custom-background, custom-colors,
  custom-header, custom-menu, editor-style, featured-image-header, 
  featured-images, full-width-template, microformats, post-formats, 
  rtl-language-support, sticky-post, theme-options, translation-ready
*/

As you can see, this is fairly standard fare. What’s important to remember is that no two themes loaded in the same WordPress installation can have the same name; so if you are building a theme by copying an existing theme and making modifications from there, make sure you change the header information here to your own unique values.

The remainder of the styles.css file is just standard CSS. You can use it to create all the cool styles you’ll utilize to make your theme look awesome.

The index.php file, on the other hand, is the initial page that a browser will fire upon visiting your site, and serves as the key file to describe the layout of the main page (and potentially the entire site, as we’ll discuss in a moment). We can place whatever HTML we want our theme to display inside this file, but since our goal here is to output our WordPress content via our theme, we’ll take a more structured approach. Let’s take a look at a stripped down index.php file we might commonly see in a theme:

<?php

// Insert the header.php file to begin the page output
get_header();

// Add in page logic via the Loop
if (have_posts()) :
   while (have_posts()) :
      the_post();
      the_content();
   endwhile;
endif;

// Insert the sidebar.php file to include widgetized sidebars
get_sidebar();

// Insert the footer.php file to complete the page output
get_footer(); 

?>

Right away, you’ll notice that this index.php file is broken up into four sections:

Just by looking at the comments in the code, we can deduce that get_header() grabs and inserts the header.php file, while get_sidebar() and get_footer() perform the same function with sidebar.php and footer.php, respectively. Fairly easy, right? There’s no need to define the specific names of those files; WordPress assumes that you’ll follow its nomenclature (a recurring theme, as we’ll see here in a moment). We’ve already covered The Loop in detail in Chapter 3, so we should already be able to see where the content is going to be added. However, this does introduce three more files that we’ll need to add to our theme:

These files aren’t vital, but you’ll find almost every theme makes use of them. And just to keep you on your toes, they won’t necessarily include what you think they might if you try to interpret them literally. For instance, the header.php file will contain all the display code required to create the code of a given page right up to where the content code is added into the outputted source code. This includes the <DOCTYPE> information for your outputted page, all the typical components you’d need in any <head> code such as meta information and links to your stylesheets, and the opening <body> tag to begin your display code. With all that said, there are two tasks you must include when creating your header.php file that will break WordPress without their presence:

Similarly, the footer.php file can cover all the outputted source code from the bottom of the content block to the end of the file, although, in our example, we’ve inserted our sidebar.php file in this space, which serves to include logic for our widgetized areas. Typically, the footer contains the </body> and </html> tags, and must contain wp_footer() to allow core WordPress functions to manage footer settings as required; without it, unexpected results will occur when WordPress uses your theme.

Let’s stop for a moment and draw an analogy to illustrate this point further, using a hamburger (or a veggie burger if you prefer) as an example. Now, the way that we prefer our burgers may well be different from the way you prefer yours. While a lot of people prefer to put their pickles, mustard, and ketchup underneath the meat, with the cheese, lettuce, and tomato on top, we choose to have nothing underneath our burger, instead having all toppings between the meat and the top bun. Other people may choose to skip the mustard and ketchup, favoring mayonnaise as their only condiment. Whatever your preference, what we all have in common on our burger is the fact that there’s a top bun, a bottom bun, and the meat in the middle—what you add to the burger is really up to you.

In the same way, themes are really all about visual flavors and preferences. We all have stuff on the top (a header), stuff on the bottom (a footer), and meat in the middle (the content being added by The Loop). Other than that, as designers we like to be creative and make our themes uniquely our own, much like we do when we prepare our burgers. Consider Figure 6.1.

Figure 6.1.  index.php structure dressed up like a hamburger

What the burger-maker has done here is change the very nature of the meal. It’s no longer a hamburger, but a double cheeseburger, and we’ll need to manage some options that deal with the cheese. Bringing the analogy back to the index.php file within our theme, we’ll call these places where we need to manage options sidebars, and we can move them around however we like. In our initial example, we’d already added one sidebar between The Loop and the footer, but now we have to manage two sidebars that may have different options. The easiest way to do this is to create a left and a right sidebar, which we can do by passing the correct standard parameter to the get_sidebar() function, as is done in the revised example:

<?php

// Insert the header.php file to begin the page output
get_header();

// Add in page logic via The Loop
if (have_posts()) :
  while (have_posts()) :
    the_post();
    the_content();
  endwhile;
endif;

// Insert both widgetized sidebars
get_sidebar('left'),
get_sidebar('right'),

// Insert the footer.php file to complete the page output
get_footer(); 

?>

We’re cooking with gas now, except … wait. We’ve added two sidebars to our theme, but we only have one sidebar.php file. What gives?

Easy—get_sidebar() takes one optional parameter, a name that corresponds directly to a standard nomenclature with sidebar.php. So when you use get_sidebar('left'), get_sidebar('right'), or even get_sidebar('footer'), WordPress will seek out sidebar_left.php, sidebar_right.php, or sidebar_footer.php, respectively. Nomenclature, in fact, plays a very big role in determining how WordPress parses out template files within your theme, as we are about to find out.

The other way to create distinct layouts in WordPress is to use page templates. It’s no surprise to find that you can only use page templates with individual pages, but they’re useful for giving your end user an easy way to change the appearance of a page within the page editing screen.

Creating a new page template is easy as pie. Just copy an existing template you have within your theme and give it a unique name. There’s no requirement to follow a nomenclature for filenames of page templates as it is with the template hierarchy; in fact, you’ll want to make sure that you avoid naming your page templates one of the template names, as it will cause it to behave in a way you don’t want. Instead, you register your page templates with WordPress in what should now be a very familiar way: having a standardized comment format at the top of your template file, as described here:

<?php
/*
Template Name: Antelope General Special Sales Page Template
*/
?>

As the required Template Name: label suggests, the name of your custom page template is defined here, and once saved, you’ll find it immediately in the page templates drop-down on your page editing screen. Nothing to it, as Figure 6.3 shows.

Figure 6.3. Page Templates dialog box

While you can literally add any functions you’d like to the functions.php file, one of the most common functions theme designers use involve setting up custom menus for extended navigation on the site. WordPress gives us an exceptionally easy method for creating as many menus as we’d like, which is useful for producing top header menus, footer menus, contextual menus, and any other type you can dream up. In order to create our menus, we’ll need to register them within our functions.php file using the register_nav_menus() function, which takes an array of menu slugs and descriptive names as its argument. Let’s have a look at it in use:

<?php

if ( function_exists( 'register_nav_menus' ) ) {
     register_nav_menus(
       array(
        'header_menu' => 'Header Menu',
        'footer_menu' => 'Footer Menu',
        'mobile_menu' => 'Mobile Menu'
       )
     );
}

As is fairly plain to see, we’ve registered the availability of three new menu files in this example—a header menu, a footer menu, and a mobile menu. With this code saved to our functions.php, we’ll now have these menu options available to us when we navigate to the Menus screen in the Dashboard at Appearance > Menus; here we can make modifications to our heart’s content. However, we still need to place them in our theme, and to do this we need only use the wp_nav_menu() function in the desired location within our theme, which looks like this in action:

<?php wp_nav_menu('header_menu'), ?> 

Aside from adding customized menus, functions.php is often utilized to extend WordPress’s functionality, creating additional widget-ready areas for use within your theme. Consider the following code:

<?php

// Register Antelope Featured Widgetized Area so it exists and we can use it
if ( function_exists('register_sidebar') )
register_sidebar(array(
  'name' => 'Antelope Featured Widgetized Area',
  'before_widget' => '',
  'after_widget' => '',
  'before_title' => '<h2>',
  'after_title' => '</h2>',
));

?>

Nothing to this, really. Here, we’re just letting WordPress know that we have a new widgetized area called Antelope Featured Widgetized Area that we’ll want to use. WordPress will respond by creating a namespace for you to work with; so now when you go to the Appearance > Widgets area within the admin area, you’ll see a new sidebar named Antelope Featured Widgetized Area. Go ahead and fill it up with whatever widget functionality you’d like, and then we’ll move on to the next (and final) step so that we can actually reap the benefits of our efforts.

Since we’ve just registered a new widgetized area, let’s follow through and add it to our theme in a useful location for our purposes. Widgetized areas can be added anywhere in a theme, but they’re commonly added within sidebar.php templates (or derivatives thereof). Just locate the place in your code where you want to add your new widgetized area, and drop in the following PHP code:

<?php 

// Output Antelope Featured Widgetized Area in our theme
if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar↵
  ("Antelope Featured Widgetized Area") ) : ?>

<!-- Default formatting code here  -->

<?php endif; ?>

We promised we’d avoid delving too deeply into PHP here, but this shouldn’t be too scary. Here we are just being responsible and making sure that our theme has no issues; for example, if the theme is unable to find either the dynamic_sidebar function (highly unlikely, as it’s a core function) or the widgetized area we just registered in our functions.php file (more likely, since everybody is prone to human error). In the event that the theme runs into an issue here, it’ll just display the output code we’ve specified—in this case, a descriptive comment. However, so long as we have coded our widgetized area correctly and added widgets to it, we should see a useful addition here.

It’s typical that users with a particular theme on their website will want to change the header to one of their own creations, and WordPress gives us a really easy, standardized method of doing so. In order to make this happen, WordPress provides us with a set of code additions that we’ll need to build our functions.php file:

<?php

// Four constants that must be defined in order for the custom image 
// header to work properly
define('HEADER_TEXTCOLOR', 'ffffff'),
define('HEADER_IMAGE', get_bloginfo('styesheet_directory') .↵
  '/images/default_header.jpg'), 
define('HEADER_IMAGE_WIDTH', 900); 
define('HEADER_IMAGE_HEIGHT', 150);

// Include the header within the theme
function header_style() {
    ?><style type="text/css">
        #header {
            background: url(<?php header_image(); ?>);
        }
    </style><?php
}

// Include the header within the admin interface
function admin_header_style() {
    ?><style type="text/css">
        #headimg {
            width: <?php echo HEADER_IMAGE_WIDTH; ?>px;
            height: <?php echo HEADER_IMAGE_HEIGHT; ?>px;
            background: no-repeat;
        }
    </style><?php
}

// Enabling the custom image header
add_custom_image_header('header_style', 'admin_header_style'),

You’ll notice that there are four basic blocks of code: the first defines four constants; the second adds the header to the front end of the theme; the third adds the header to the administrative portion of the theme; and the last actually enables it all within WordPress. From an editing perspective, it’s important to pay attention as a theme developer to the first code block where we define our constants. Make sure to input the header dimensions accurately, as well as describe the location of the header image, and the color of any text that is added to the header. Without these constants, the custom header will simply fail to work.

Following the constants definition, the remaining three code blocks comprise pretty much our standard WordPress magic. First, we’ll create a function that will load with the wp_head action hook that adds the header image and its attributes into your theme. The next code block loads the header to the admin Dashboard, followed by our activation function in add_custom_image_header(), which specifically calls the two functions we’ve just defined.

In what may be the granddaddy of easy functionality to add to any theme, WordPress has a simple method that gives your users the ability to add a custom background to their themes. In your functions.php file, add the following line of code:

<?php add_custom_background(); ?>

Doing this will automatically add a set of functionality to your theme that will allow the website administrator to see the existing background image of the theme, upload a background to replace the old one, and tweak several of the commonly modified attributes of the background. Take a look at Figure 6.4.

Figure 6.4. Adding a custom background

If you were expecting a more complicated process, don’t knock it. Every once in a while you’re given a gift, and this is one of them!

The term functionality is a common buzzword that is thrown around fairly loosely these days by developers, designers, and clients alike, but exactly what are we talking about when we reference it? For the most part, just about anybody involved would agree that it’s a general term describing a specific feature set that has been introduced into a system. Within WordPress, almost all types of functionality can be broken down into four primary categories:

Whether you’re looking to add a real-time feed of Tweets to your sidebar or a jQuery image gallery on your home page, or just to set up your site to be ranked better in search engines, the categories listed should cover just about anything you want to throw at WordPress. If we assert that all functionality in WordPress falls within one of these four categories, and consider that WordPress provides a logical location to house operations, we can project whether a specific piece of functionality belongs within a plugin or within a theme.

Core WordPress functionality is included within WordPress, and should never be directly edited at any time (if you do, bad stuff can happen; think “removing random pieces of your engine just to see what happens”). Functionality that either enhances existing WordPress core features or introduces brand new features typically belongs as plugins, so that they can be added and removed as necessary. Likewise, functionality that aids a theme belongs within that theme, but it’s useful to note that it’s scripting that helps display specific pieces of content rather than add or extend functions. In this way, the intent of the scripting is different; it’s more about display logic than it is about site functionality, and it’s probably the most important distinction to make in determining where to place your site’s custom functionality.

Almost all functionality in WordPress is written in one of two languages: PHP or JavaScript. After all, whether you’re creating a custom jQuery script to add a behavior to a slide show or modifying The Loop to add the three most recent posts in the Featured category to the front page, you are really working on the site’s functionality. Right?

Sort of.

The truth is that while you are, indeed, working with functional pieces of scripting on your site, you should be able to squarely place any scripting into one of two categories. The script either adds to or enhances the actual features of your WordPress site (site functionality), or assists you in displaying that information to your audience (display logic). We all have a reasonable idea of what site functionality is, but display logic has everything to do with how we actually display useful data within the context of the theme. Common examples of display logic include:

Incorporating prefabricated site functionality via the plugin system by customizing a theme’s display logic is the most common form of WordPress development performed by the typical WordPress developer, as most of us spend our time finding slicker and more effective ways of integrating existing tools across the Web to create client solutions. Often, the difference between good and poor coding practices is in recognizing the difference between actual site functionality and display logic, and coding each in the appropriate location.

So if this is all as clear as mud, let’s take a look at a practical example. Suppose that we have a new client—ABC Real Estate—who’d like us to develop a new website built upon WordPress with the following functionality requests:

Each of these requests seems more than reasonable and intuitive for a real estate website, but let’s sort out exactly where we’d add each piece of functionality listed.

And to that we say: we completely understand where you’re coming from, but allow us to make a few compelling points that just might change your mind.

First of all, if you are developing site functionality yourself, you’re likely to find it more useful to do so within the context of a plugin for purposes of portability, rather than directly within the theme. After all, even after a job has been completed and the site launched, a large percentage of developers retain the intellectual property rights of programs that they develop and utilize within sites they work on; sooner or later there is a need to reuse the same code (or a version of it) for another project. Plugins make this site functionality portable and easy to install, saving quite a bit of time in the long run.

Because WordPress plugins are structured to maintain all their files in separate directories away from other plugins and core WordPress features, they inherently provide order to the functions written throughout the site. For instance, if you are having an issue with the meta description on the home page and you know you are using an SEO plugin that handles that function (easily looked up by referencing the active plugin listing in the WordPress admin), you’ll know exactly where to begin investigating the source of the issue, even if you weren’t the original developer. In this way, plugins can actually provide a loose form of documentation in and of themselves, giving developers reasonable clues as to where certain functions might live, even in the poorest-documented of sites.

Troubleshooting is another fabulous reason to maintain site functionality within plugins rather than embed it directly into the theme. Adding new features to a WordPress site can occasionally cause conflicts and break a website, causing any number of display or performance issues that need to be corrected. When such issues go bump in the night, most seasoned developers begin examining existing plugins to see where scripting plugins may be happening. Using WordPress’s plugin system to activate and deactivate plugins provides a handy way to eliminate active scripts running on the site, and then bring them back one by one to determine which are the offending scripts. Without the ability to turn plugins on and off, a developer can be stuck trying to sort out exactly which scripts are conflicting with one another and causing a buggy result to the end user.

Finally, don’t underestimate the importance of flexibility in your website functionality. The more of the site’s core functionality that is directly built into the theme, the more difficult it becomes to make design changes to that theme, or even swap it out entirely. It may sound clichéd, but the Web is constantly shifting, and, ultimately, so will your site’s needs. Hard-coding site functionality into a theme can lead to time-consuming edits, changes, and overhauls in the long term (and often the short term) as you realize that what you thought was crucial yesterday—basing your entire site development on it—is entirely obsolete next week. Honestly, it has happened to the best of us.

“All right,” we hear you say. “That’s fine, but I have a good reason to deviate …” Every subjective argument like this has solid reasoning to go your own way, and it’s useful to point out a few here.