== In-Series ==
Tags: series, sequential, connected, article series, linking posts, post series
Contributors: Lorelle (http://codex.wordpress.org/User:Lorelle), ColdForged (http://www.coldforged.org)

In-Series provides an easy, future-proof way to connect a series of posts. If you have a series of articles on your site, and you want to ensure your readers can follow the sequence within the series, In-Series will help you provide the links between the posts and articles, improving your site's navigation.

== Installation ==
1. Install in-series.php into your wp-content/plugins directory.
2. Modify your single.php (http://codex.wordpress.org/Template_Hierarchy#Single_Post_Page) template to call any of the following functions:
   previous_in_series()
   next_in_series()
   all_in_series() 
   series_table_of_contents()

If you're not using (or don't have) single.php, then place these template tags in index.php after your post content and before your next and previous page navigation tags.

== Usage ==
To create a connected series of posts, add two custom field (http://codex.wordpress.org/Using_Custom_Fields) key/value pairs to each post in the series.

series_name 
    a unique name for the series. 
series_order 
    the current post's position in the series. 

The step-by-step instructions for usage follow. Assume you are writing a tutorial on WordPress plugins.

1. Create the first post in the series.
2. Before saving, move to the Custom Field section under Advanced Editing.
3. In the KEY field, type series_name.
4. In the VALUE field, type in a unique name for this series such as "Writing A WordPress Plugin".
5. Click Add Custom Field.
6. Again, in the KEY field, type series_order.
7. In the VALUE field, type in the number "1", as this is the first post in the series.
8. Click Add Custom Field.
9. Click Save or Publish. 

For the second post or article in the series, repeat the process, incrementing the series_order number by 1.

The custom fields for each post, by themselves, don't do anything. If the In_Series plugin is deactivated, they will not appear.

When the In-Series plugin is activated, though, several new template tags are available which do use these custom fields. These new template tags only output when viewing a single post. When these new template tags are called on an index, archive, category, or any non-single-post view template file, they will silently do nothing. The tags will generate the series information when viewing a single post that is part of a series as defined by the custom fields series_name and series_order.

By default, if there is no next or previous article in the series, that link will not appear. The default usage also does not highlight the current page in a link.

The following functions will output links as described below. If the post is not part of a series (as defined by the custom fields), the template tags will not display anything; so it's safe to add these tags to your default template(s). If the plugin is deactivated, you will need to remove or comment out these tags.

<?php previous_in_series(); ?>
displays a link to the previous post in the series, if there is one. If the current post is the first post in the series, this template tag will not display anything. 

<?php next_in_series(); ?>
displays a link to the next post in the series, if there is one. If the current post is the last post in the series, this template tag will not display anything. 

<?php all_in_series(); ?>
displays a list of links to each post in the series. The current post is not linked, to ensure the reader knows where in the series they are. 

<?php series_table_of_contents(); ?>
displays each post's title as a clickable link to that post, as <li> elements in an ordered list.  The current post is not linked, to ensure the reader knows where in the series they are.

<?php all_series(); ?>
displays a list of each unique series, listed by series name with a link to the first post in each series.

== Advanced == 
=== Next and Previous ===
The next and previous series template tags can be called with no parameters:
   <?php next_in_series(); ?>
and they output a link that looks something like this:
   Writing a WordPress Plugin Part 2 »

By default, the title of the next post will be used for the link. You can modify the output by passing the following variables to the function:
   <?php next_in_series('format', 'link'); ?>

* format 
    The format parameter features the format for the text before or after the link. The default usage features '%link &raquo;' for next_in_series() and '&laquo; %link' for previous_in_series(). 
* link 
    This parameter sets the link usage. The default, '%title', will use the post's title. 

An example would be:
   <?php next_in_series('<b>Next in the series:</b> ', '%title'); ?>
which would produce   
   Next in the series: Writing a WordPress Plugin Part 2 »

This example will create a link to the next post in the series (if there is one) with the word "NEXT" for the link, instead of the post's title.
   <?php next_in_series('%title %link', 'NEXT'); ?>
   Writing a WordPress Plugin Part 2 NEXT »

This example will create a link to the next post in the series (if there is one) with "Next Up: " followed by the post's title.
   <?php next_in_series('Next Up: %link', '%title'); ?>
   Next Up: Writing a WordPress Plugin Part 2 »

If you want to simply remove the little arrows from the links, use this:
   previous_in_series('%link');
   next_in_series('%link');

=== All in Series ===
The all_in_series() function also works without arguments, producing the following:
   Read the whole series: 1,2,3
Where "1,2,3" are links to the series' posts.  The current page is not linked in the list.

The parameters are:
   <?php all_in_series('separator, before', 'after'); ?>

* separator 
    What to place between the links to the posts. Default is a comma (','). 
* before 
    What to place before the list of links. Default is '&laquo; Read the whole series: ' 
* after 
    What to place after the list of links. Default is ' &raquo;' 

To change the text and put the entire thing in an HTML paragraph tag:
   <php all_in_series(' ', '<p>The whole shebang: ', '</p>'); ?>
   The whole shebang: 1,2,3

You can use get_post_meta (http://codex.wordpress.org/Using_Custom_Fields) to first grab the current series' name, and then use that in all_in_series, like this:

   <php
   $series = get_post_meta($post->ID, 'series_name', TRUE);
   all_in_series(',', "$series_name: ");
   ?>
will produce something like this:
   Writing a WordPress Plugin: 1,2,3,4,5

If you simply want to remove the little arrows (»), use this:
   all_in_series(',', 'Read the whole series: ', ' ');

=== Table of Contents ===
The series_table_of_contents() function will produce HTML list elements for each post in the series:
   <li><a href='http://example.com/x/y/z/part-1' title='Part 1'>Part 1</a></li>
   <li><a href='http://example.com/x/y/z/part-1' title='Part 2'>Part 2</a></li>
   <li><a href='http://example.com/x/y/z/part-1' title='Part 3'>Part 3</a></li>
Note that the tag ONLY outputs the list elements.  This allows you to use ordered or unordered lists as you wish:
   <ol><?php series_table_of_contents(); ?></ol>
will produce an ordered list of your series' posts.

The function accepts three single parameters:
* class
    if specified, this is the name of a CSS class that will be applied to each list element:
       <li class='class'>
* before
    HTML to display before the start of the table of contents.
    Default is "<ol>"
* after
    HTML to display after the table of contents.
    Default is "</ol>"

To include this tag in your default template, use something like this (adjust HTML and CSS declarations as needed):
   <?php
   $series = get_post_meta($post->ID, 'series_name', TRUE);
   if ('' != $series)
   {
   	echo '<h4>Article Series</h4>';
   	echo "<h5>$series</h5>";
	series_table_of_contents();
	echo '<p class="series">';
	next_in_series('<b>Next:</b> %link', '%title');
	echo '<br />';
	previous_in_series('<b>Previous:</b> %link', '%title');
	echo '</p>';
   }
   ?>

===All Series===
The all_series() tag will produce an ordered list of links to the first post in each series, sorted ascending by the series names.

The function accepts three arguments:
* before
    HTML to display before the start of the list.
    Default is "<ol>"
* after
    HTML to display after the end of the list.
    Default is "<ol>"
* order
    Whether to order the list by the name of the series, or by the post ID of the first post in each series.
    Default is "name".

To create an unordered list of series, ordered by the post ID of the first post in each series:
   <?php all_series('<ul>', '</ul>', 'id'); ?>

== Frequently Asked Questions ==
Q. Why do you use two meta keys (series_order and series_name)?
A. So that you can use the series_name for other aspects of your templates.  An example is immediately above, in the demonstration for series_table_of_contents().

Q. Can one post be assigned to two or more series?
A. Not at this time.  It's on my to-do list.

Q. Must I increment series_order by one?
A. No, you can use any increment you choose.  Many users use intervals of 5 or 10, to allow for later posts to be inserted into the series, as needed.  With In-Series 2.0 and above, you may also use negative numbers, to place posts before the first item in a series.

NOTE: WordPress 1.5.2 does not support zero as a postmeta value.  See Ticket #1912:
   http://trac.wordpress.org/ticket/1912

== Credits ==
Copyright (c) 2005 Scott Merrill (skippy@skippy.net)
Released under the terms of the GNU GPL 
Documentation: Lorelle (http://www.cameraontheroad.com/)