How to Use Tokens in Templates

PublishPress Series has a feature called tokens that makes it possible to control how series related content is displayed on your blog. One method to do this is by using templates combined with tokens. Click here for an introduction to tokens in PublishPress Series.


Tokens in PublishPress Series #

A token is a specific format for indicating where you want series information to appear. The token format PublishPress 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 on the “Templates” settings area:

Series Meta
Series Meta

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 you want it to appear before the rest of the post content.


Using Tokens in Templates #

If you have some familiarity with HTML and CSS, the token system allows you to modify the series info output without having to make edits to any PHP files.

On the “Templates” tab 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. 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%: Gets 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 gets 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 Posts > Manage Serie page.
  • %series_description%: This will be replaced by the description of the series as set on the “Manage Series” page.