How do I output a customized list of series?

There is another function included with Organize Series that you can use to output a list of all the series you've written where you want that acts very similar to the " wp_list_categories()" template tag in the WordPress core. What that means is that if you've already got a handle on how to use wp_list_categories then you'll have no problem with wp_list_series().  Let's take a closer look:

The Widget

For those of you who are uncomfortable with editing your theme files and who are using a theme with widgets enabled there is a widget included with Organize Series that you can use to output the list of series in your sidebar.

The widget name is "Series Widget" (imaginative eh?) and when you activate it you'll see that there are some options you can set for the widget (Click on "Edit").  Here's a breakdown of what the various options are:

  • Widget Title - simply enter what you want to appear as the title of this section in the sidebar.
  • Dropdown/List - This controls how the list of series will appear on your blog.  If you select "Dropdown" it will result in a dropdown list of series (which includes javascript so when a user clicks on a series in the dropdown they'll go immediately to the archives page for that series). I'll talk more about dropdown lists in the next post.  If you select "List" you'll get a typical hyperlinked list of series you've written.
  • Show Post Count - If checked, the number of posts in the series will be located next to each series title in the list.
  • Hide Empty Series - If checked, any series that don't have any posts associated with it yet will not be included in the list.
  • Post List Toggle - If checked, when you are on a single post page that is part of a series a list of other posts in that series will display in the widget.

The Fun Way

If you're anything like me, you like having more fine control over how things appear on your blog.  That's where the handy wp_list_series(); function comes into play.  The usage of wp_list_series is to insert 

<?php 
if ( function_exists('wp_list_series') ) { 
    wp_list_series();
}
?>

wherever you want.  However, the real control comes in when you submit various parameters via the function.

The Defaults:

$defaults =  array(
    'orderby' => 'name',
    'order' => 'ASC', 'show_last_update' => 0,
    'style' => 'list', 'show_count' => 0,
    'hide_empty' => 1, 'use_desc_for_title' => 1,
    'feed' => '', 'feed_image' => '', 'exclude' => '',
    'title_li' => __('Series'),'number' => '',
    'echo' => 1
);

By default wp_list_series() outputs a list...

  • ordered by the names of the series
  • in ascending order
  • that does not show the date/time of the last updated post in the series.
  • outputted in "list" style (i.e. with <li> and </li> surrounding each series item.
  • that does not show the number of posts in the series.
  • hiding series that do not have posts
  • using the description of the series as the "title" attribute for the link to each series.
  • with no feed or feed image used
  • not excluding any series
  • displaying "Series" as the heading over the list,
  • with no "limit" set for the number of series pulled from the database, and,
  • echoed (i.e. displayed) instead of just returning the output (not displaying).

The Parameters

Here's a more detailed summary of each paramater:

orderby - (string) Sort categories alphabetically, by unique Series ID, or by the count of posts in that Series. The default is sort by series name. Valid values:

  • ID
  • name - default
  • count

order- (string) Sort order for series (either ascending or descending). The default is ascending. Valid values:

  • ASC - default
  • DESC

show_last_updated - (boolean) Should the last updated timestamp for posts be displayed (TRUE) or not (FALSE). Defaults to FALSE.

  • 1 (true)
  • 0 (false) - default

style - (string) Style to display the series list in. A value of list displays the series as list items while none generates no special display method (the list items are separated by <br>tags). The default setting is list (creates list items for an unordered list). Valid values:

  • list - default.
  • none

show_count - (boolean) Toggles the display of the current count of posts in each series. The default is false (do not show post counts). Valid values:

  • 1 (true)
  • 0 (false) - default

hide_empty - (boolean) Toggles the display of series with no posts. The default is true (hide empty series). Valid values:

  • 1 (true) - default
  • 0 (false)

use_desc_for_title - (boolean) Sets whether a series' description is inserted into the  title attribute of the links created (i.e. <a title="<em>Series Description</em>" href="...). The default is true (series descriptions will be inserted). Valid values:

  • 1 (true) - default
  • 0 (false)

feed (string) - Display a link to each series'  rss-2 feed and set the link text to display. The default is no text and no feed displayed.

feed_image - (string) Set a URL for an image (usually an rss feed icon) to act as a link to each series' rss-2 feed. This parameter overrides the feed parameter. There is no default for this parameter.

exclude - (string) Exclude one or more series from the results. This parameter takes a comma-separated list of series by unique ID, in ascending order.

title_li - (string) Set the title and style of the outer list item. Defaults to "_Series". If present but empty, the outer list item will not be displayed.

number - (integer) Sets the number of Series to display. This causes the SQL LIMIT value to be defined. Default to no LIMIT.

echo- (boolean) Show the result or keep it in a variable. The default is true (display the series organized). Valid values:

  • 1 (true) - default
  • 0 (false)

CSS selector : .current-series { ... }

Usage:

Let's give an example:

Say you wanted to show the three most recent series you've posted, with the number of posts in each series indicated, not including the crappy "101 ways to watch paint dry" series that you wrote.  First, going to the "manage->series" page in your WordPress Administration you find that the series id of your "101 ways to watch paint dry" series is 33,  equipped with this information here's the code you would write:

<?php
wp_list_series('orderby=id&order=DESC&show_count=1&exclude=33&number=3');