/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.


The Series Post List Template is used to affect the presentation of all posts belonging to a series on the single page of a post belonging to a series. In other words, the series postlist box you see on this page.

By default, Organize Series inserts the contents of this template into your blog whenever a post page is displayed for a post that belongs to a series. However you can disable this by unchecking the “Display list of series on post pages” checkbox (I know, I need to change the wording – it’s misleading!).

Let’s take a look at a screenshot of the Series Post List template:

seriespostlisttemplate

In every template you include the following three things:

  • (x)html/css controlling the layout and “looks” of the box.
  • Any text you want displayed.
  • %token-tags% controlling the placement of series information (see “Series Options Page: Tokens” for more on tokens)

In this particular template we see that I’ve used div containers to control the layout of the postlist “box” (with css class “seriesbox” and “center”). I’ve also decided to make the list of posts (%post_title_list%) an unordered list (ul).

I also decided to not use any custom text in this box. But I could have done something like this:

modifiedexampleseriespostlistbox

which would result in this:

modifiedexamplepostlistdisplay

Next, notice the %tokens% I’ve used:

  • %series_icon_linked% – If the series has an image associated with it then it will be displayed in a div container with the class “center”
  • %postcontent% – the location of this tag tells Organize Series that I want the Series PostList Template contents to be placed before the post content of the post.
  • %post_title_list% – is a marker token that tells organize series where I want the list of posts in that series to be placed.

The %post_title_list% token is a special token because it will consider the contents of the “Series Post List Post Title Template” and the “Series Post List Current Post Title Template” when Organize Series prepares the page for display. Let’s look at these two templates:

seriespostlisttitletemplate

seriespostlistcurrenttitle

Remember how %post_title_list% is surround by <ul> and </ul> tags? Well the Series Post List Title Template (and Series Post List Current Post Title Template) indicates how each post in the list of posts will be outputted. Since this is an unordered list then I need to make sure I use <li></li> surrounding each post title (%post_title% or %post_title_linked%). Why two templates? In case you haven’t figured it out by now – in the list of posts in the post list box I may want to style the current post being displayed differently from the others. In this particular case I decided that I would choose to display the current post as a non-linked title (%post_title% as opposed to
%post_title_linked%) and with a class of “serieslist-li-current” (as opposed to “serieslist-li”). Notice anything else that’s different for the current post being displayed?

This gives the user incredible control over how the “Table of Contents” for posts in a series is displayed on your blog.

One final note:

The functions (“template tags”) that call these templates are:

wp_postlist_display() -> calls the Series Post List Template and replaces the tokens with series related information.

get_series_posts() -> calls the contents of the “Series Post List Post Title Template” and “Series Post List Current Post Title Template” and replaces the %tokens% in them. It does have arguments that can be passed to it and if you must get into it now it is documented in the series-template-tags.php file.