For inclusion on Category Templates article for creating a single category.php template for custom category displays. TITLE - What do I call this thing?

Using WordPress variables and queries, multiple category template files can be replaced with one category.php template file instead of mutliples. The following are examples of how you might customize your category pages based on a single category template. The options are open to your imagination and coding skills.

A single category template file (category.php) can be created which collects information, based upon those variables and queries, from the database. For the most part, any information stored in the database could be called onto the page.

For this example, the following information is collected:

• Category Description from the Manage > Categories panel
• Category ID and Name from the Manage > Categories panel
• Category Parent for Children Categories
• Category ID used within a plugin

Featured on our example custom category template are the following, visible on every category page view:

• Menu of the parent category and children categories
• Category Title
• Category Description
• Coffee2Code's Customizable Post Listings Plugin to create a random list of posts within that category

The Menu

The category menu uses two methods to collect information for the links: A simple link to generate a link to the category parent and use of the wp_list_cats() template tag to generate the children of the parent category.

The generated list will look like this:

The first link is a static link generated with a query. This query says:

1. If there are posts, check to see what category is being viewed and call it $this_category.
2. Get the category ID and link.
3. If this category is the parent
   1. Print the category name and link.
   2. If it is the child, find the parent and print that category name and link.

A link to a category page without using permalinks looks basically like this:

<a href="index.php?cat=8">Category Eight</a>

The query will replace the call for the cat=8 so the link generates the parent category link of the category shown.

The code is placed after the template call for the header and after the first style references for the layout of the page, before the WordPress Loop. We've styled the list in a style called cattoc for "category table of contents" as the menu name:

<?php if (have_posts()) : ?>
<div id="cattoc"><ul>
<?php $this_category = get_category($cat); ?>
<!-- If category is parent, list it -->
<?php if ($this_category->category_parent == 0) { ?>
<li>
<a href="<?php echo get_category_link($cat); ?>" title="<?php echo $this_category->cat_name; ?>">
<?php echo $this_category->cat_name; ?>
</a>
<ul>
<?php $this_category->category_parent = $cat; ?>
<?php } else { ?> 
<!-- If category is not parent, list parent category -->
<?php $parent_category = get_category($this_category->category_parent); ?>
<li>
<a href="<?php echo get_category_link($parent_category->cat_ID); ?>" title="<?php echo $parent_category->cat_name; ?>">
<?php echo $parent_category->cat_name; ?></a>
<?php } ?>

In the second part of the menu, we need a list of the children under the parent category, to improve navigation within the category pages. The wp_list_cats() template tag automatically generates a list of the categories and their children, but we need to instruct the template tag to "get the children of the parent category".

<ul>
<?php 
wp_list_cats('list=1&use_desc_for_title=0&child_of=' . $this_category->category_parent); ?>
</ul></li>
</ul></div>

Note: the template tag specifically sets the use_desc_for_title to NO (0). This instructs the tag to NOT use the category description as the "title" in the link, since we will be using it for the custom text on the category page. The template tag may also be modified to include sorting by name or ID and including the number of posts. For more information, see: wp_list_cats().

Custom Category Page Text

Using the category description set in the Manage > Categories panel, whatever information you enter in your category description, with or without HTML tags, will appear for any category page that includes a description. If you do not want custom text to appear on your custom category pages, make sure the category information is blank.

The query is made that says:

If this is a category page, 
     get the category ID and name. 
     Add filters for layout, 
         then display the category title and category description.

The code looks like this:

<?php if ( is_category() ) : ?>
<h2 id="category-name-header">
<?php echo $cache_categories[$cat]->cat_name ?> Category</h2>
<?php add_filter('category_description', 'wpautop'); ?>
<?php add_filter('category_description', 'wptexturize'); ?>
<div id="category-description">
<?php echo category_description(); ?>
</div>
<?php endif; ?>

Avoid Redundant Information

By default, any information added to a template is visible on every use of that template file. For example, the links and information in your header and footer on visible on every page on your site.

With the custom category pages, that means the description information would also be visible on every page. If you have a lot of posts within a category and you click on View Previous Entries and...oh...look...the same information that was on "page one" of your category page view is repeated on "page two", "page three", and so on. The posts change but the information remains.

To clean up this redundancy, we add a query that asks "Is this page one? Then display the info. If it is not, then don't." This way, pages 2, 3, and so on will not have the custom text on the page, getting the user right to the list of past posts within that category.

<?php if ( $paged < 2 ) { // Do stuff specific to first page?>
<?php } else { // Do stuff specific to non-first page ?>
<?php } ?>

Let's put these two together to generate the category title and description, with the check to see which page the viewer is on.

<?php if ( $paged < 2 ) { // Do stuff specific to first page?>
<?php if ( is_category() ) : ?>
<h2 id="category-name-header"><?php echo $cache_categories[$cat]->cat_name ?></h2>
<?php add_filter('category_description', 'wpautop'); ?>
<?php add_filter('category_description', 'wptexturize'); ?>
<div id="category-description">
<?php echo category_description(); ?>
</div>
<?php endif; ?>
<?php } else { // Do stuff specific to non-first page ?>
<?php } ?>

Caveat

NOTE: If you choose to use the Category Description as the text for your custom category pages, you will need to go through ALL of your template files and change all references and uses to the category description in those tags.

Examples

wp_list_cats 

The usage of <?php wp_list_cats('use_desc_for_title=1'); ?> generates the description as the title in the link for the categories in a list. This template tag is often found in the header, sidebar and footer template files in your theme. Change the 1 to a 0 to set this to no and the link title will be changed to "View all posts filed under CategoryName", whatever is the category name.

list_cats 

Another version of wp_list_cats(), the usage may include the use of the use_desc_for_title. This template tag uses a a long query string of arguments to set its parameters. The tenth parameter covers the category description used in the link. It should be set to FALSE:

<?php list_cats(FALSE, '', 'ID',
    'asc', '', TRUE, FALSE, 
    FALSE, FALSE, FALSE); ?>

category_description() 

If you have used this template tag that explicitly calls the category description from within a template file, you will need to remove or change it, or be aware that it will call the category description you are also using for your category pages.

Article Highlights

Using Coffee2Code's Customizable Post Listings Plugin to create a random list of posts within that category, we need to instruct the plugin to recognize which category the random list needs to be generated from.

The normal usage of the plugin tag is:

<?php c2c_get_random_posts(number of posts, "<li>%post_URL%</li>", category ID); ?>

Or, more specifically, display 5 posts in a list from category 8.

<?php c2c_get_random_posts(5, "<li>%post_URL%</li>", 8); ?>

The variable that needs to be set is the category ID. We replace that with a query that collects the category ID and sets it with the $cat variable again.:

$wp_query->query_vars['cat']

Let's put this to work in a section called "Article Highlights" in a list featuring 5 random links to posts within the category being viewed.

<h4>Article Highlights</h4>
<ul>
<?php c2c_get_random_posts( 10, "<li>%post_URL%</li>", $wp_query->query_vars['cat'], $cat); ?>
</ul>

Show the Category Posts

The rest of the page includes The Loop to display the posts within that category, and the ending if/else statements to close off the various queries we've made on the page. While your Loop may look different, here is the Loop for our example custom category page.

<?php while (have_posts()) : the_post(); ?>
<div class="excerpt-post">
<h2 id="post-<?php the_ID(); ?>">
<a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>">
<?php the_title(); ?></a></h2>
<div class="catslist"><?php the_category(' and '); ?></div>
    <div class="entry">
        <?php the_excerpt('Continue Reading...') ?>
    </div>
<!--
<?php trackback_rdf(); ?>
-->
</div>
<?php endwhile; ?>

This is then followed by the page navigation and calls for the sidebar and footer template files.

The Custom Category Template

Let's put the whole thing together so you can see it in action, one category.php that generates custom information for each category on your site.

<div id="content">
   <?php if (have_posts()) : ?>
<div id="cattoc">
   <ul>
   <?php $this_category = get_category($cat);?>
    <?php if ($this_category->category_parent == 0) { ?>
      <li>
<a href="<?php echo get_category_link($cat); ?>" title="<?php echo $this_category->cat_name; ?>">
<?php echo $this_category->cat_name; ?></a>
   <ul>
     <?php $this_category->category_parent = $cat; ?>
<?php } else { ?>
     <?php $parent_category = get_category($this_category->category_parent); ?>
      <li>
<a href="<?php echo get_category_link($parent_category->cat_ID); ?>" title="<?php echo $parent_category->cat_name; ?>">
<?php echo $parent_category->cat_name; ?></a>
     <ul>
<?php } ?>
  <?php wp_list_cats('sort_column=name&optioncount=0&list=1&use_desc_for_title=0&child_of=' . $this_category->category_parent); ?>
     </ul></li>
</ul></div>
<?php if ( $paged < 2 ) { // Do stuff specific to first page?>
   <?php if ( is_category() ) : ?>
     <h2 id="category-name-header"><?php echo $cache_categories[$cat]->cat_name ?></h2>
       <?php add_filter('category_description', 'wpautop'); ?>
       <?php add_filter('category_description', 'wptexturize'); ?>
  <div id="category-description">
    <?php echo category_description(); ?>
  </div>
<?php endif; ?>
<h4>Article Highlights</h4>
   <ul>
<?php c2c_get_random_posts( 10, "<li>%post_URL%</li>", $wp_query->query_vars['cat'], $cat); ?>
   </ul>
<?php } else { // Do stuff specific to non-first page ?>
   <?php } ?>
<?php while (have_posts()) : the_post(); ?>
   <div class="excerpt-post">
     <h2 id="post-<?php the_ID(); ?>">
<a href="<?php the_permalink() ?>" rel="bookmark" title="Permanent Link to <?php the_title(); ?>">
<?php the_title(); ?></a></h2>
   <div class="catslist"><?php the_category(' and '); ?></div>
    <div class="entry">
        <?php the_excerpt('Continue Reading...') ?>
    </div>
<!--
<?php trackback_rdf(); ?>
-->
   </div>
<?php endwhile; ?>

This is just an example and a good start. Use your imagination, PHP, and WordPress query skills to help you create your own customizable category template file.