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)

Markup and Styling of Series Lists

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!

ShareThis

One of the things that the Organize Series WordPress plugin does well is provide multiple ways for you to promote and “show off” the various series you’ve written. Since some of those possibilities aren’t easily visible to the new user this next few posts in the series will give you a list of all the different ways you can publicize your serial work.

Latest Series - <?php latest_series(); ?>

This template tag is one of the few features of Organize Series that is not automatically enabled right out of the box on fresh Organize Series installs. However, it is a powerful function that provides an easy way for you to promote the latest series you’ve published (or are in the midst of writing).

How to use it:

To use the latest_series() tag you need to be familiar with editing your theme files. There are some great pointers for this here, here, and here. The latest_series() template tag can be placed wherever you want - inside or outside of the WordPress loop. What will happen is that when the page is generated the latest_series template tag will be replaced by what you have included in the Latest Series Template in the Series Options Page. So you can control the output via the series options. By default, the latest_series tag will display the series icon for the latest series.

So let’s take a look at actually using this tag. Let’s say you want to insert the latest series information in your sidebar and you want it to display the series icon, a description of the series, and let’s throw in a list of the posts in that series as well. First, we need to set up the “Latest Series Template” via the series options page. It will look like this:

Notice that I’ve used the following %tokens%: %series_icon_linked% - which gets replaced with the series icon for the latest series (if there is one); %series_description% - which gets replaced with the series description for the latest series (if there is one); and %post_title_list% - which gets replaced with the list of posts in the series (according to the “Series Post List Template” on the Series options page. I’ve also styled it using xhtml and css. If you are familiar with xhtml or css your options are virtually limitless for the actual output of the Latest Series Template tag. Note that you can also control the size (width) of the series icon via the “Series Icons Options” also on the series options page.

Now that you’ve got the Latest Series output customized on your series options page you’ve got to insert code somewhere in your theme. There’s actually TWO ways to do this. The easy way is if your theme is widget enabled you can simply use the super-duper Latest Series Widget that I’ve included with Organize Series! The slightly harder way is to simply insert “<?php latest_series(); ?>” wherever you want the latest series stuff to show up.

For instance, most implementations of this information will be in the sidebar of your blog. In my case I simply followed the style of my sidebar (<ul> and <li>) and inserted the code appropriately in it’s own block - like this:

Notice how the entire “latest series” block is surrounded by the conditional “<?php if (function_exists(’latest_series’))…” statement. This is good coding practice to follow whenever you use template tags from plugins so if you have to disable a plugin or are testing things you won’t disable your blog too. Note as well, that this code is based off of how my theme’s sidebar is structured. When inserting “<?php latest_series(); ?> on your own blog you’ll want to follow the html structure in your theme.

Finally, here’s how the latest series block looks on my blog using the above procedure:

In the next post we’ll look at showing off all the series you’ve written in a list form.

ShareThis

We’re going to conclude our look at the Series Options page in this post by looking at the “Latest Series” Template and the Series Icon Options.

Here’s what the “Latest Series Template” option field looks like (WP2.5):

This is the one template option that is not automatically added to your blog. The contents of this template control the output of the latest_series() function or the latest series widget. You can insert the latest_series() function wherever you want it to appear in your blog (manually into your theme files) or you can simply use the built in widget if you have widgets enabled for your theme.

This is how the default Latest Series output looks on my blog (to the left):

Of course like the other template options on the series options page you can use different tokens to control the contents of the latest_series() ouput.  For instance you might want to use the %series_title% token to display the series title instead of the series icon.  In future versions of Organize Series I’ll be adding more tokens that you can use.

The series icon options is for controlling the width of the series icons in different places where they appear.  These are global values that are applied when the automatic insertion of series display related functions in your blog is enabled (default setting).  Here’s the Series Icons options:

Notice that the width’s you enter are in pixels.  The height of the image will be be relative to the image’s original size and the ratio of the change between the original width and the one you enter in this section.  Notice, this does not resize the actual image file but simply affects the display size of the image (the numbers entered here are what Organize Series uses in the “width” parameter of the <img> tag).

That’s it for the Series Options page.  We’ll be revisiting it at different times through this series as it is so central to controlling the output of series related information in your blog.  But at least the last few posts give a brief overview of the things you control on the Series Options page.

In the next few posts we’re going to be looking at some specific series related pages created by Organize Series.

ShareThis

So far in the Organize Series Usage Tips Series I’ve been writing about the Series Options page and focusing on some of the things you can do there to customize the output of series related information on your blog. In this post of the series I’m going to focus on the customization of the Series Table of Contents Template.

The Series Table of Contents is a page on your blog that lists all the series you’ve written (that contain posts). The output of this page is controlled by three things.

• “Series Table of Contents URL” in the Automation Settings Section of the Series Options Page. This setting is what you want to be the location of the series table of contents page.
• “seriestoc.php” - this is the default file that Organize Series will load when the series table of contents page is requested. The default layout in this file should work with most theme setups but of course it won’t work with all. In some cases, this file will have to be modified to match your theme structure (i.e by looking at your themes index.php or archive.php file). I’ll be writing a post later in this series to go into more detail with this.
• “Series Table of Contents Template” in the Template Tag Options section of the Series Options Page.

Like other templates found on the series options page you can use html, css and %tokens% to control how each series listing will appear on the series table of contents page. For example, this…

Will result in something like this:

For those who want to get more customized with the display of the Series Table of Contents Template here are some template tags (functions) you can use. Remember all of these template tags are found in the “series-template-tags.php” file which contains inline documentation if you are too impatient for me to write a detailed explanation in this series!

Template Tags for Series Table of Contents:
wp_serieslist_display_code(): This will output a formatted output of the indicated series and does not have to be in the WordPress Loop. It accepts two parameters: the series id of the series to be listed (required), and what page is calling this function (not required). Remember this function does not output a list of all the series you’ve written, it only prints the output for the given series. The output is controlled by the “series table of contents template” as explained in this post.

wp_serieslist_display(): This is the function you will use if you want to output the entire list of non-empty series you’ve written. All it does is query the database for the series you’ve written that contain posts and then calls wp_serieslist_display_code() for each series in the list. Again, this function also does not need to be called from within the WordPress Loop.

That’s it for this template.  I’ll cover the last two options on the series options page in the next post of this series.

ShareThis

Once again, if you haven’t yet, you should read about automation settings, tokens, and Templates before reading any further.

In this post I’m going to zero in on the Series Meta. What is the series meta? It’s basically an information strip you can associate with a post that belongs to a series for a quick overview of what part the post is, a total count of the posts in the series, and the name of the series the post belongs to. Of course what you actually put in the series meta is up to you!

Here’s what the template looks like:

And here’s the output on the blog:

Now in the case of the series-meta, it appears wherever the post that is a part of a series is displayed and the location of the output is controlled once again by the %postcontent% token.

If you want to manually insert the series-meta template into your theme then you need to remove the %postcontent% token AND make sure the Display series meta information with posts? checkbox is unchecked.

Template Tag:
Here’s the function you use to call the series-meta template (remember full documentation is found in the series-template-tags.php file):

wp_seriesmeta_write(); - To use this in your theme make sure you echo it (i.e. <?php echo wp_seriesmeta_write(): ?>)

ShareThis