/organizeserieslogo.gif

I developed the “Organize Series WordPress plugin” to help me manage and make it easier for readers to find various articles I’ve written as part of a series. In this series of articles I am writing about how to use this plugin effectively and in the process I’ll be working through various features of the plugin.


In the last post, I talked about how you can show off the latest series in your sidebar.  One of the caveats of the latest_series() function/widget is that it only shows one series.  The “latest series” function is just a way of giving readers quick insight into the most recent series you’ve published to your blog and is the easiest to customize.

However, there is another more powerful 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 is javascripted so when a user clicks on a series in the dropdown they’ll go 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). See the markup section for more. 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 URI 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)

By default, wp_list_series() generates nested unordered lists (ul) within a single list item (li) titled “Series”.

You can remove the outermost item and list by setting the title_li parameter to an empty string. You’ll need to wrap the output in an ordered list (ol) or unordered list yourself.  If you don’t want list output at all, set the style parameter to none.

If the series list is generated on a Series Archive page, the list item for that series is marked with the HTML class current-series. Each series item also has the class series-item and series-item-{series-id}.

...
<li class="series-item series-item-5 current-series">
  [You are on this series page]
</li>
<li class="series-item series-item-6">
  [Another series]
</li>
...

You can style that list item with a 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'); ?>

It’s that simple!