Chapter 2 35 Some of the more important ones are as follows: Parameter Name Effect Number Pass a numeric value to limit the number of categories retrieved. This is especially helpful for blogs with a large number of categories. Feed Pass true to cause a link to each category's feed to be printed current_ category Pass the ID of a category to force the output to contain the current-cat class on a particular category. For example, say you wanted to limit your category list to the rst ve categories. To do so, you would use the following code: <?php wp_list_categories(array('number' => 5)); ?> For more information on the available parameters, visit http://codex.wordpress.org/Template_Tags/wp_list_categories. Listing all of the tags in use on a blog Generally, tags are used liberally to indicate the subject matter of a post. For this reason, a list of tags is a great way to help visitors to get around a blog and view a wide array of posts that they're interested in. By default, WordPress lists tags in a cloud, varying the size of each tag according to the number of times it was used. However, this default output can be modied to produce a list that might make more sense to your users. How to do it First, decide where you want to generate a linked list of all of your tags. Open the appropriate template le, and insert the following: <?php wp_tag_cloud(array( 'format' => 'list', 'unit' => '' )); ?> Creating Navigation 36 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, the output for this function call should look like the example shown in following screenshot: How it works When you call wp_tag_cloud, WordPress performs a database query, fetching all of the tags that match the parameters you pass to the function. After fetching the tags, WordPress builds the markup for the list. Using the parameters in the previous code, the markup consists of an <li> tag containing a link to the categories archive page for each category that was fetched. The entire list is then wrapped in a containing <ul> tag, producing output similar to the following: <ul class="wp-tag-cloud"> <li> <a style="" title="1 topic" class="tag-link-53" href="http://themes.local/tag/chattels/">chattels</a> </li> <li> <a style="" title="1 topic" class="tag-link-54" Chapter 2 37 href="http://themes.local/tag/cienaga/">cienaga</a> </li> <li> <a style="" title="1 topic" class="tag-link-55" href="http://themes.local/tag/claycold/">claycold</a> </li> <li> <a style="" title="1 topic" class="tag-link-56" href="http://themes.local/tag/crushing/">crushing</a> </li> <li> <a style="" title="1 topic" class="tag-link-58" href="http://themes.local/tag/dinarchy/">dinarchy</a> </li> <li> <a style="" title="1 topic" class="tag-link-59" href="http://themes.local/tag/doolie/">doolie</a> </li> </ul> You'll notice that each of the <a> tags that link to the tag archive page has an empty in-line style attribute. This is a consequence of the processing that wp_tag_cloud does internally. You'll also notice that unlike wp_list_pages and wp_list_categories, this function produces a surrounding <ul> element for its items. There's more In most cases, the default display of wp_tag_cloud will not be the one that is most benecial to your users. This is especially true for business blogs and professional sites. Luckily, there is an easy way to change how wp_tag_cloud displays. Passing parameters As seen earlier, the output from wp_tag_cloud can be modied by using parameters with the function call. Parameters are passed in the same way as with many other WordPress functions, which is in the following format: <?php wp_tag_cloud(array('parameter_name' => 'parameter_value')); ?> You've already seen a couple of the parameters that wp_tag_cloud supports. Another important one is the number parameter, which limits the number of tags placed in the cloud. If you wanted to limit the number of tags to 5, then you'd call the function as follows: <?php wp_tag_cloud(array('number' => 5)); ?> Creating Navigation 38 For more information on the available parameters, visit http://codex.wordpress.org/Template_Tags/wp_tag_cloud. Highlighting the current page in the navigation One easy way to provide a great user experience is to make sure that the user's current location on a website is plainly visible to them. The best way to accomplish this is to visibly highlight the navigation item for the page that the user is on. How to do it First, ensure that you have used wp_list_pages to generate a list of links for use in navigation. Most likely, you'll do this in the site header where your main navigation is located. After you've done this, open your theme's stylesheet (style.css) and add the following CSS: .current_page_item a { color: #fff; background: #000; } If you've done everything correctly, depending on your theme's styles, you'll see something like the following on your home page: After you navigate to the page with the title Lorem Ipsum, you'll see the following on your home page: How it works When wp_list_pages creates output, it adds the current_page_item class to the list item for the page that is currently being viewed. You style this class to ensure that the current page appears differently from other pages. The previous CSS code simply changes the background color of the list item to black, while changing the text color to white. However, you can use any CSS declarations to customize the style of the highlighted item to your heart's content. Chapter 2 39 There's more If your blog has a small number of top-level categories and you are using wp_list_ categories for your main navigation items, you might want to take advantage of the highlighting capabilities demonstrated for pages. Doing so is easy, because you can use the earlier-featured code in full. You just have to change the targeted class from current_page_item to current-cat, as follows: .current-cat a { color: #fff; background: #000; } Adding a search function to a theme In spite of your best efforts, static navigation for a website will always be left wanting when a user wants to quickly and easily nd content matching a specic term or phrase. That is where search comes in, and with WordPress, it is easy to implement. How to do it Open your theme and decide where you want to place the search form. The best place for a search form is either in the header or at the top of a sidebar in the site. When you gure out where you want to place the search form, insert the following code at the appropriate place: <form method="get" id="searchform" action="<?php echo site_url('/'); ?>"> <label class="hidden" for="s"><?php _e('Search for:'); ?></label> <div> <input type="text" value="<?php echo attribute_escape(get_search_query()); ?>" name="s" id="s" /> <input type="submit" id="searchsubmit" value="<?php _e('Search'); ?>" /> </div> </form> After you've inserted the search form markup, style the form elements as desired. By default, you'll end up with output that looks like the following: Creating Navigation 40 How it works In this recipe, you've created the standard markup for a WordPress search form. In the markup, there is a label describing the search input, the search text input itself, and the submit button for the form. When a user types text into the form and submits it, WordPress detects the parameters contained in the query and responds accordingly. Of particular note in this recipe is the use of two WordPress functions. The rst is get_search_ query . This function retrieves the search query text that a user submitted, so that the user can see what they searched for. In addition, the site_url function is used to output the home page for the blog. This function is a handy utility that lets you easily construct URLs to your site. There's more Searching is a complicated thing, and many developers feel that the default search functionality in WordPress is inadequate. Luckily, because of WordPress' extensive plugin system, there is a solution. That solution is the Search Everything plugin by Dan Cameron of Sprout Venture. The Search Everything plugin, found at http://wordpress.org/extend/plugins/ search-everything/ , allows for searching tags, categories, pages, comments, and more. It might be a great addition to your WordPress installation, so check it out. Getting the category page link from a category name There are several situations where a particular category should be linked to directly. If the name of the category is known, but the ID of the category could differ (for instance, between production and development environments), then it is useful to be able to retrieve the category page link directly from the category name. In addition, it is helpful to not display the link at all if the category doesn't exist. How to do it For this recipe, consider the situation where you need to link to three different categories: Testimonials, Portfolio, and Thoughts. You've established each of these categories in your local development environment and in your staging environment, but you haven't yet created them on the blog where you'll be launching your theme. This is a good situation to use conditional linking. Chapter 2 41 Given this situation, you need code similar to the following: <?php $nav_categories = array('Testimonials','Portfolio','Thoughts'); ?> <ul id="site-nav"> <?php foreach($nav_categories as $cat_name) { $cat_id = get_cat_ID($cat_name); if($cat_id) { ?> <li> <a href="<?php echo get_category_link($cat_id); ?>"> <?php echo $cat_name; ?> </a> </li> <?php } } ?> </ul> This code produces a nice list of links for the categories that exist. You remove the chance of fatal errors from using non-existent categories, and you provide your users with a better experience. How it works The get_cat_ID function returns the ID for a specic category name. If a category with that name does not exist, the function returns the value 0. Therefore, the condition that checks the $cat_id variable will prevent the system from trying to retrieve a link for categories that do not exist. If the category does exist, the category link will be displayed appropriately. Displaying page links only if the destination page exists In themes intended for distribution, you may want to provide a link to an About or Contact page somewhere in the theme template. However, you won't want to display the link if the page doesn't actually exist. To get around this, you can use some WordPress functions to see if the destination page exists. Creating Navigation 42 How to do it Identify all of the pages that you wish to link to individually in your theme. For each of them, insert the following code, replacing Page Name with the name of the page you're referencing: <?php $page = get_page_by_title('Page Name'); if( null !== $page ) { echo '<a href="' . get_page_link($page->ID) . '">Page Name</a>'; } ?> How it works The get_page_by_title function returns an object containing all of the information about the page with the specied title if the page exists. If the page does not exist, the function returns null. In this recipe, you check the value of the $page variable to make sure that the page exists. If it does, a link to the page is printed, utilizing get_page_link to retrieve the correct URL for the page. get_page_link respects the front page options of WordPress and bypasses a lot of checks that get_permalink has for non-page links. If you know that you are linking to a page and not a post, you should use get_page_link. Creating a category drop-down menu For highly-categorized and deeply-hierarchical sites, showing a full list of categories and subcategories can take up a lot of space in your design. To get around this, you can change your categories list from static to dynamic by using a simple JavaScript technique. How to do it First, download the Supersh package from http://users.tpg.com.au/j_birch/ plugins/superfish/ and place all of the JavaScript les contained within it in your theme directory. Next, insert the following code in your theme's <head> section, above the wp_head function call: <?php wp_enqueue_script('superfish', get_bloginfo( 'stylesheet_directory' ) . '/superfish.js', array('jquery')); ?> Chapter 2 43 Place the following code after the wp_head call: <script type="text/javascript"> // <![CDATA[ jQuery(document).ready(function() { jQuery('ul.superfish'). superfish(); }); // ]]> </script> Now, open the template le in which you wish to display your Category drop-down. Insert the following: <ul class="nav superfish"> <?php wp_list_categories(array('title_li'=>'','hide_empty'=>false)); ?> </ul> Finally, load your page. Unstyled, you'll see something like the following: When you hover over a category name that has a child, you'll see the following: How it works The Supersh script is a JavaScript solution to realize true cross-browser drop-downs. It takes advantage of the semantic markup generated by the wp_list_categories function to create drop-downs with fully-realized submenus for subcategories. The internals of Supersh are beyond the scope of this recipe. Creating Navigation 44 The empty title_li parameter in this recipe prevents a separate list item containing a title string from being generated and displayed. This extra list item could prove confusing to users and should generally be removed with this parameter, when using categories for navigation. Creating drop-downs using child pages Complex sites can be created with WordPress by using only the system of pages and subpages. In order to allow the user to easily drill down through a topic, it can be benecial to create drop-downs from the parent-child page relationship. Getting started For this recipe to be useful, you must rst create a series of pages and subpages that you'll be using for your site's content. An example of a desirable hierarchical content organization that would be useful to structure in this way would be a top-level "Teams" page with subpages for each team in the league that you're writing about. How to do it Follow the steps for the recipe Creating a category drop-down menu until you get to the point where you use the function wp_list_categories. Then insert the following code: <ul class="nav superfish"> <?php wp_list_pages(array('title_li'=>'')); ?> </ul> Depending on your theme's styles, you should see something similar to the following, before hovering over a parent page: And you should see the following after hovering over a parent page: . into the form and submits it, WordPress detects the parameters contained in the query and responds accordingly. Of particular note in this recipe is the use of two WordPress functions. The rst. href="http:/ /themes. local/tag/chattels/">chattels</a> </li> <li> <a style="" title="1 topic" class="tag-link- 54& quot; Chapter 2 37 . href="http:/ /themes. local/tag/cienaga/">cienaga</a> </li> <li> <a style="" title="1 topic" class="tag-link-55" href="http:/ /themes. local/tag/claycold/">claycold</a>