Chapter 1 25 After you've chosen a theme framework, it is time to create a theme based on that framework. To do so, you'll use the technique described in Creating a child theme. After you've created the base child theme, you can start to customize it. In most cases, you override the markup of a parent theme by supplying template les directly in your child theme. With a theme framework, things generally work a little differently. You supply your custom markup by attaching callbacks to custom action and lter hooks, as dened by the theme framework. To nd out what the custom hooks are, you need to read the theme framework's documentation. To add appropriate functionality via the custom hooks, you create a functions.php le inside your child theme, and use the Plugin API to add callbacks to the theme framework's custom hooks. How it works A theme framework is a theme created for the sole purpose of being extended by child themes. They are built to be modied by users for use on their own websites. Although most theme frameworks can be used out of the box, it is the personalization and customization that end users and developers perform that really allow their particular use of the framework to shine. There's more There are several quality theme frameworks in existence at the time of writing this book. The best are as follows: Thematic— http://themeshaper.com/thematic/ Hybrid—http://themehybrid.com/archives/2008/11/hybrid-wordpress- theme-framework Carrington—http://carringtontheme.com/ Vanilla—http://code.google.com/p/vanilla-theme/ Whiteboard—http://plainbeta.com/2008/05/20/whiteboard-a-free- wordpress-theme-framework/ WPFramework—http://wpframework.com/ See also Installing and activating a theme Creating a child theme WordPress Theme Basics 26 Adding expected WordPress hooks WordPress themes should possess a number of different hooks by default, allowing active plugins to alter or add output when pages are rendered. WordPress development guidelines specify the names and locations of the expected WordPress hooks in themes. How to do it There are three WordPress hooks that you need to add to almost every custom theme. They are: wp_head wp_footer comment_form First, add the wp_head hook. Find the end tag of the HTML head element (</head>, often in header.php) and place your cursor on the line before it. Insert the following: <?php do_action( 'wp_head' ); ?> Next, add the wp_footer hook. Find the end tag of the HTML body element (</body>, often in footer.php) and place your cursor on the line before it. Insert the following: <?php do_action( 'wp_footer' ); ?> Finally, insert the comment_form hook. Locate the end tag of the HTML form element for the comment form (</form>, often in comments.php and comments-popup.php) and place your cursor on the line before it. Insert the following: <?php do_action( 'comment_form', $post->ID ); ?> If you are using the default comments form layout, you won't have to explicitly add the comment_form hook because it is provided in the default theme's comments.php le. How it works Plugins use these hooks to add to or modify the rendered output of a theme's template les. Often the modication includes linking to or outputting JavaScript, CSS, or HTML code. Many popular plugins use the above hooks, and making sure that they are present is essential to the plugin's proper operation. Chapter 1 27 There's more Although wp_head, wp_footer, and comment_form are the only hooks necessary for a complete theme, it is possible to add many more custom hooks that allow individuals to customize a theme after it has been fully developed by its author. Including PHP les from your theme For organizational or reuse purposes, you will often separate components of your theme into separate les to be used in several different places. Getting ready Before getting started, you need to identify the pieces of output that will be reused throughout your theme, and separate them into different PHP les. You may wish to separate common post listing structures or advertisement blocks. How to do it First, you should identify the piece of output that you wish to reuse and separate it into a new le. For this recipe, we'll say that you have a notice snippet that you may wish to include in several places. Place the following code in a new le called notice-snippet.php: <div class="notice-snippet"> Thanks for visiting my site! </div> After you've separated it, you need to decide where you want to display the snippet. Wherever you want to display the snippet, insert the following: <?php include TEMPLATEPATH . '/notice-snippet.php'; ?> You'll notice that your snippet is now shown in the template wherever you inserted the above statement. How it works The include function does exactly what you would think it does: it includes the contents of the separate le wherever you use it. The important thing to remember about this example is the TEMPLATEPATH constant used in the include statement. TEMPLATEPATH is a constant dened by WordPress that holds the directory path to the directory that contains the template used to render output for the theme. You should use the TEMPLATEPATH constant whenever you need to have PHP access les from your theme. WordPress Theme Basics 28 There's more In addition to the TEMPLATEPATH constant, WordPress provides a STYLESHEETPATH constant. Generally, these two constants hold the same variable. However, if a child theme is active, then the STYLESHEETPATH constant will contain the le system path to the style sheet in use, whereas the TEMPLATEPATH constant will contain the le system path to the parent theme directory. 2 Creating Navigation In this chapter, we will cover: Listing all of the pages that exist on a blog Listing all of the categories dened for a blog Listing all of the tags in use on a blog Highlighting the current page in the navigation Adding a search function to a theme Getting the category page link from a category name Displaying page links only if the destination page exists Creating a category drop-down menu Creating drop-downs using child pages Introduction One of the most important aspects of any website is navigation. Making sure that a visitor can get around is paramount to increasing trafc, user engagement, and visit length. By offering a variety of navigation methods, you give the user multiple ways to nd the content that interests them. There are several techniques built into WordPress that you can use to build the navigation that lets your users nd what they need on your site. When thinking about the topic of navigation in the context of this chapter, it is important to also consider the subject as a whole. Don't limit yourself to the concept of a top or side main navigation item. Those types of navigation are very important, but for the purposes of this chapter, you'll consider navigation as a whole—meaning any way that helps the user to get around your site. Creating Navigation 30 Listing all of the pages that exist on a blog WordPress pages often contain static content that should be reachable at any time. Common uses for WordPress pages are website and author descriptions, contact forms, afliate information, and more. Making sure that these pages can be found and navigated to quickly is paramount. How to do it First, decide where you want to generate a linked list of all your pages. If you're comfortable using pages for navigation, then you probably want to put the pages listing directly below your main site identication elements, in header.php. Open your chosen template le and insert the following: <ul> <?php wp_list_pages(); ?> </ul> Next, open your theme in your browser and take a look at the spot where you inserted the appropriate code. Depending on your site's styles and the pages that you've created, the output for this function call should look like the main content area in the following screenshot: Chapter 2 31 How it works When you call wp_list_pages, WordPress performs a database query, fetching the appropriate pages based on the parameters that you pass to the function. After fetching the pages, WordPress builds the markup for the list. The markup consists of an <li> tag containing a link to the page for each page that was fetched. If the title_li parameter is not empty, then the entire list is wrapped in a containing <li>. By default, the previous code will produce markup that is similar to the following: <li class="pagenav">Pages<ul> <li class="page_item page-item-271"> <a title="Affiliates" href="http://themes.local/affiliates/">Affiliates</a> </li> <li class="page_item page-item-269"> <a title="Authors" href="http://themes.local/authors/">Authors</a> </li> <li class="page_item page-item-267"> <a title="Contact" href="http://themes.local/contact/">Contact</a> </li> <li class="page_item page-item-273"> <a title="Terms & Conditions" href="http://themes.local/terms-conditions/">Terms & Conditions</a> </li> <li class="page_item page-item-256 current_page_item"> <a title="WP List Pages" href="http://themes.local/list-pages/">WP List Pages</a> </li> </ul> </li> There's more The default output for wp_list_pages might not t your specic use cases. Luckily, modifying the output from wp_list_pages is easy. Passing parameters The wp_list_pages output can be changed by passing different values for a wide array of parameters, as follows: <?php wp_list_pages(array('parameter_name' => 'parameter_value')); ?> Creating Navigation 32 Some of the more important parameters are as follows: Parameter Name Effect echo Set to false to cause wp_list_pages to return a string containing HTML markup instead of printing the markup child_of Pass a numeric ID to only retrieve child pages of the page with that ID exclude Pass a comma-delimited list of page IDs (for example: '#,#,#') to exclude them from the pages displayed Taking this into account, consider the case where you only want to display pages that are a child of the afliate information page. If the afliate information page has an ID of 4, then you would use wp_list_pages as follows: <?php wp_list_pages(array('child_of'=>4)); ?> For more information on the available parameters, visit http://codex.wordpress.org/ Template_Tags/wp_list_pages . Listing all of the categories dened for a blog Proper categorization of posts is a great way to help visitors nd what they are looking for. To make it even easier, a theme could include a list of all of the categories in which there are posts. This technique works best on blogs with a small number of categories. Alternatively, you can use category drill-downs that change based on the category level that you're at. If you're writing a site about music, you might have Rock, Hip Hop, and Country as top- level categories, each containing second-level categories such as Reviews, Recommendations, and News. In this way, your users can navigate directly to the information that they're looking for, quickly and easily. How to do it First, decide where you want to generate a linked list of all of your categories. If you're taking a drill-down approach as talked about in the introduction to this recipe, then you may wish to put the list of links in the header of your site. Otherwise, category links would be best served in a sidebar or footer. Open the appropriate template le and insert the following: <ul> <?php wp_list_categories(); ?> </ul> Next, open your theme in your browser and take a look at the spot where you inserted the appropriate code. Depending on your site's styles, and the categories that you've created, the output for this function call should look like the following: Chapter 2 33 How it works When you call wp_list_categories, WordPress performs a database query, fetching all of the categories that match the parameters that you pass to the function. After fetching the categories, WordPress builds the markup for the list. The markup consists of an <li> tag containing a link to the categories archive page for each category that was fetched. If the title_li parameter is not empty, then the entire list is wrapped in a containing <li>. By default, the previous code will produce markup that is similar to the following: <li class="categories">Categories<ul> <li class="cat-item cat-item-3"> <a title="View all posts filed under aciform" href="http://themes.local/category/aciform/">aciform</a> <ul class="children"> <li class="cat-item cat-item-41"> <a title="View all posts filed under sub" href="http://themes.local/category/aciform/sub/">sub</a> <ul class="children"> <li class="cat-item cat-item-102"> Creating Navigation 34 <a title="View all posts filed under sub sub" href="http://themes.local/category/aciform/sub/sub-sub/" >sub sub</a> </li> </ul> </li> </ul> </li> <li class="cat-item cat-item-4"> <a title="View all posts filed under antiquarianism" href="http://themes.local/category/antiquarianism/" >antiquarianism</a> </li> <li class="cat-item cat-item-5"> <a title="View all posts filed under arrangement" href="http://themes.local/category/arrangement/">arrangement</a> </li> <li class="cat-item cat-item-6"> <a title="View all posts filed under asmodeus" href="http://themes.local/category/asmodeus/">asmodeus</a> </li> <li class="cat-item cat-item-7"> <a title="View all posts filed under broder" href="http://themes.local/category/broder/">broder</a> </li> <li class="cat-item cat-item-8"> <a title="View all posts filed under buying" href="http://themes.local/category/buying/">buying</a> </li> </ul> </li> There's more The default output for wp_list_categories might not t your specic use cases. Luckily, modifying the output is easy. Passing parameters Similar to wp_list_pages, the categories retrieved by wp_list_categories can be modied by passing parameters to the function. Parameters are passed as follows: <?php wp_list_categories(array('parameter_name' => 'parameter_value')); ?> . follows: Thematic— http://themeshaper.com/thematic/ Hybrid—http://themehybrid.com/archives/2008/11/hybrid -wordpress- theme-framework Carrington—http://carringtontheme.com/ Vanilla—http://code.google.com/p/vanilla-theme/ Whiteboard—http://plainbeta.com/2008/05/20/whiteboard-a-free- wordpress- theme-framework/ WPFramework—http://wpframework.com/ See also Installing and activating a theme Creating a child theme WordPress Theme Basics 26 Adding expected WordPress. expected WordPress hooks WordPress themes should possess a number of different hooks by default, allowing active plugins to alter or add output when pages are rendered. WordPress development guidelines. development guidelines specify the names and locations of the expected WordPress hooks in themes. How to do it There are three WordPress hooks that you need to add to almost every custom theme.