Categories
Docs

Latest Series

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 herehere, 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 comes 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:

[cce_php]

<?php if (function_exists(‘latest_series’)) { ?>

<li id=”Latest-Series”>
<h2><?php _e(‘Latest Series’) ?></h2>
<ul class=”no-splitted”>
<li><?php latest_series(); ?></li>
</ul>
</li>

<?php } ?>

[/cce]

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:

\

Now the [cceN]latest_series();[/cceN] function also has other parameters you can use to control what gets returned:

$display

This defaults to true.  If you set $display at false then the [cceN] latest_series() [/cceN] function will just return the data rather than echoing it.

$args

This parameter controls what gets pulled from the database for the latest series.  It is an array with the following data:

‘orderby’: defaults to ‘post_modified’ – This controls how the series are ordered in the returned dataset. It can be post_modified date, post_date, series name, series slug, id, or term id).  Post modified and post date will be taken from the latest or earliest post added to the series depending on the order (ASC or DESC).

order‘: defaults to ASC – Whether the data returned is ordered ascending (ASC) or descending (DESC).

‘postTypes’: defaults to ‘post’ – This gives the ability to only return the latest series in a specific post types (really useful if you have custom post types on your blog/website).  If you want to indicate only one post type then make sure you surround it in quotation marks – i.e. ‘”post”‘.  If you want more than one post type to be included then surround each in quotation marks and separated by commas – i.e. ‘”post”, “custom_post_type”‘.

‘hide_empty’: defaults to true – If true, then empty series will not be returned.  If false, then empty series will be returned.

‘number’: defaults to 5 – This simply indicates the number of “latest series” you want fetched from the database.

Example:

Let’s say we want to echo the latest 3 series, ordered by series name, in ascending order, with no empty series, from the ‘post’ post type, and our ‘apple’ custom post type.  Here’s how the latest_series function would be formed.

[cceN_php]

<?php

$args = array(
‘orderby’ = ‘series_name’,
‘postTypes’ = ‘”post”, “apple”‘,
‘number’ = 3
);

latest_series( true, $args );

?>

[/cceN]

Categories
Docs

Series List

In the last post, I talked about how you can show off the latest series in your sidebar.   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.

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 [cce lang=’php’][/cce] wherever you want.  However, the real control comes in when you submit various parameters via the function.

The Defaults:

[cce lang=’php’]$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
);[/cce]
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 sectionfor 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 titleattribute 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)

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}.
[cce lang=’php’] …

  • [You are on this series page]
  • [Another series]

… [/cce]
You can style that list item with a CSS selector :
[cceNi lang=’php’] .current-series { … } [/cceNi]

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:

[cce lang=’php’] [/cce]

It’s that simple!