Categories
Docs

Series Options Page: Tokens

One of the ways that Organize Series makes it possible to easily and finely tune the various ways in which series related content is displayed on your blog is via the use of a templates combined with a token system. “Tokens” are just a way of referring to text indicators that point the plugin to what you want the token to be replaced with when it executes the code. The token format Organize Series uses is %token%. The “key” is surrounded by “%” symbols.

Here’s an example of one of the templates showing you the token system at work.

templateexample

Notice the highlighted tokens in the image: ‘%series_part%’, ‘%total_posts_in_series%’, %series_title_linked%’, and %postcontent%. The plugin uses the reference keys in each token and the positioning of each token to determine where you want the various series information displayed with this particular template.

In this particular case, the settings for Series Meta indicates that whenever the series meta information is called you want it to be in a ‘<div>’ container of the class “seriesmeta” (styled via .css) and with the text, “This entry is part [the series part] of [total parts in the series] in the series [series title linked to the series archive page]”. The %postcontent% token indicates that when the series meta information is automatically inserted by the plugin (see “Automation Settings“) you want it to appear before the rest of the post content.

This particular template would result in something like this:

screenshot-13

If you have some familiarity with html and css, the token system makes it incredibly easy to modify the series info output without having to make edits to any .php files.

On the Series Options page is a token index that shows all the different tokens you can use in the templates. In most cases these tokens can be used in whatever template you wish but this hasn’t been fully tested. The only way to find out is to try it.

Here’s a list of all the tokens and what they do:

  • %series_icon%: Get’s replaced by the series-icon for the series that the post belongs to.
  • %series_icon_linked%: Same as %series-icon% except that the image is also linked to the series archive page for that series.
  • %series_list%: This token is for use with the orgSeries widget only – it references where you want the list of series titles to be inserted and requires that the template for each series title be also set.
  • %series_title%: Replaced with the title of the series.
  • %series_title_linked%: Same as %series-title% except that it will be linked to the series archive page.
  • %post_title_list%: This gets replaced by the the contents of the Post List Template (also on the series options page).
  • %post_title%: You will use this in the post list template and indicates where you want the post title of a post belonging to the same series to appear.
  • %post_title_linked%: Same as %post_title% except that it’s linked to the actual post.
  • %previous_post%: Indicates where you want the link to the previous post in the series to be displayed. The link text will be the title of the previous post.
  • %previous_post_custom%: Same as %previous_post% except that the link text will be whatever you indicated in the “Custom Previous Post Navigation Text” field (defaults to “Previous Post in Series”).
  • %next_post%: Indicates where you want the link to the next post in the series to be displayed. The link text will be the title of the next post.
  • %next_post_custom%: Same as %next_post% except that the link text will be whatever you indicated in the “Custom Next Post Navigation Text” field (defaults to “Next Post in Series”).
  • %postcontent%: Use this along with the auto-tag insertion to indicate where you want the contents of the template to appear relevant to the post content. In other words if you want the template contents to appear after the post content then you would use this token at the beginning of the template contents. If you want the template to appear before the post content then you would use the token after the template contents (see the series-meta template example at the beginning of this post). NOTE: It is very important that you include this token in the field OR your post content will not show up on your blog!
  • %series_part%: Get’s replaced by the part number of the post that belongs to the series (i.e. if the post is part 3 then %series_part% will be replaced by “3”)
  • %total_posts_in_series%: This get’s replaced by the number of published posts that are part of the series. I’ll repeat, published posts. If a post is assigned to a series but is not published then the total posts will not include that post. This is important to remember when you are viewing your posts on the Manage->Posts page.
  • %series_description%: This will be replaced by the description of the series as set on the “Manage Series” page.

There is an add-on in the works that will add more tokens to Organize Series.  What tokens would you like to see?  Feel free to leave your suggestions in the comments.

Categories
Docs

Series Options Page: Automation Settings

In this next article breaking down the Series Options page let’s look at the Automation Settings section:

The majority of this section controls the automatic insertion of series related information in your blog. In most cases, you will want to leave everything here as is but there are cases where you may want to have more fine control over the addition of series related information in your blog theme so Organize Series makes it possible for you to do so. Here’s a run down of the different options in this section:

“Display list of series on post pages?”
Postlist Box toggle

Default PostList BoxToggling this checkbox indicates whether you want the series postlist box to be displayed on the page of a post that belongs to a series. If you leave this unchecked, the postlist box will not be displayed automatically and you will have to insert the template tag yourself (I’ll be devoting a whole section to template tags in a later post in this series). The style and “layout” of the postlist box is controlled by the `Series Post List Template` in the “Template Tags Section” on the series options page.

“Display series-meta information with posts?”

series meta information toggle

Default Series meta StripSeries Meta basically refers to the series related information that shows up with the posts that belong to a series wherever they are displayed. What is actually included in the series meta strip depends on what you’ve indicated in the `Series Meta Template` in the “Template Tags Section” of the series options page. By default the series meta includes what part the post is in the series, the total posts in the series and the series title linked to the series archive page. Toggling this option will control whether the series meta is displayed automatically or not.

“Use Custom .css?”
Custom CSS toggle

Organize Series comes with it’s own .css file that it uses by default along with the default templates set on series options. This enables the plugin to work out of the box with styling that is at least “semi-presentable” ;). I recognize, however that my layout and design skills aren’t legendary and so it is possible for users to have complete control over the look of all the different series related outputs. Here’s the options:

  1. Modify the existing .css tags (or add new .css) in the `orgSeries.css` file in the organize series plugin directory to your liking and leave the “use custom .css” checkbox checked. If you add new .css then make sure you modify the series templates section to include your new .css code.
  2. Uncheck the “use custom .css” option and include all your series related .css in the `styles.css` file in your theme directory. This is a useful option for theme authors who integrate Organize Series plugin with their themes.

“Series Table of Contents URL”
Series Table of Contents URI

This is where you choose the custom url that will point to the Table of Contents page for all your series that contain posts (series that have no posts associated with them will not display on the Table of Contents Page). In your theme you can use `<?php get_series_toc(); ?>` to display this link on your blog.

“Series Table of Contents Title”
\"The Series Table of Contents Title custom field\"

This field is where you can select what you want to be displayed in your browser title bar when a reader is viewing the Series Table of Contents page.  Here’s what it would look like if you stuck with the default.

\"An example of the custom Series TAble of Contents custom title in browser title bar\"

“Select how posts in series are ordered”
Sort order for series

One of the neat features in organize series is that you can choose how you want the posts to be sorted on your series archive pages. This will also affect the sort order when you filter the list of posts on your Manage->Posts page by series. There are four possible ways of sorting the posts.

  1. By series part, ascending. This displays the post that is part one of the series, then part two, then part three etc.
  2. By series part, descending. This displays the post that is the latest part of the series, then the next latest and so on (i.e. 5,4,3,2,1).
  3. By date, ascending. This displays the posts that are part of the series in order of the date they were published with the earliest date first.
  4. By date, descending. This is how posts are displayed on archive pages by default in WordPress – with the latest post by date first and then the next one is an earlier one (and so on until the earliest.

I should mention here that the number of posts displayed on a series archive page is controlled by the number you’ve selected for display on your blog in the WordPress Options  -> Reading page. Anything over that number will be automatically paginated by WordPress.

Delete Organize Series Data?

Delete Organize Series Data?

In the off chance that you decide you no longer want to use the Organize Series plugin and want to clean up all traces of it from your server and database you can check this option and when you delete the plugin using the built-in WordPress delete link for the plugin all the data from the database related to Organize Series will be removed as well.

That’s all the options that are available in the Automation Settings section of the Series Options page.

Categories
Docs

Series Options Page: Series Post Page Template

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 series post list box?” checkbox.

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 orgSeries-template-tags.php file.