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