Configuring the Post Plugins

Caveat

Unfortunately, due to ill-health, these plugins have not been developed or supported properly for some years. They still work under most circumstances with the latest versions of WordPress (including on this website) but could possibly conflict with any WordPress features added after 2008 — e.g. custom post types — if you use them.

The post plugins, Similar Posts, Recent Posts, Random Posts, Popular Posts, and Recent Comments, should work ‘straight out of the box’. For example:

 

will display an unordered list of links to the five posts most relevant to the current one.

Similarly,

 

will show a list of the five most recent comments and their authors (the extra code protects your site from breaking if you should ever deactivate the plugin).

You can style the lists any way you like by playing with your theme’s CSS.

If the latest version of the Plugin Output Cache is installed the post plugins (apart from Random Posts) will have their output cached for efficiency.

Placement

We saw above that you can place the output of the post plugins anywhere you want by editing the code of your theme files. You might, however, not feel comfortable doing that or you might not like to re-edit the theme every time it is updated: the Post Plugins offer several other ways of placing their output without touching your theme files.

If your theme is designed to use widgets you can use the Presentation/Design admin menu to place the plugins as widgets into the sidebar (or anywhere else the theme allows). The plugin’s Placement submenu also lets you pass a parameter string (see below) to the widget and/or decide which pages it should appear on.

You might instead want to place the plugin output after the content of your posts. The plugin’s Placement submenu lets you do just that. Again you can pass a parameter string and/or choose which pages should show the output (e.g., ‘is_single()’ will keep output off the front page and just on single post pages; ‘!is_single()’ will do the opposite). If other plugins are also adding their output after the body of a post the order in which they appear can be important. By adjusting the priority of the the plugin’s placement you can achieve the order you want.

The Post Plugins can also append themselves to your site’s feed. The settings are again reached from the Placement submenu.

Finally, the plugins can be injected into individual posts and pages by inserting special place-holders. The content filter option must be turned on from the Other submenu. The place-holders look like this:

<!--SimilarPosts-->

If the content filter is off the place-holder is invisible but otherwise is expanded to display the plugin output. You can pass a parameter string to the place-holder, e.g., <!--RandomPosts limit=2-->.

Options/Settings

What if you want just three items in the list? Or what if you want to include an indication of how many comments each post has? You need to configure the plugin’s settings.at if you want just three items in the list? Or what if you want to include an indication of how many comments each post has? You need to configure the plugin’s settings.

Each of the post plugins has a Settings page which is accessible if you are logged in with the capability to manage options–in the role of administrator (WordPress 2+) or user level 8 or above (before version 2). All the settings are listed below. Most of the options apply to all of the plugins.

Beware of choosing settings which are contradictory (e.g., include and exclude the same post) or so restrictive as to reduce matches to zero (e.g., matching both the current post’s category and tags).

Number of posts to show
The default is 5.
Number of posts to skip
Allows you to start part way ‘down’ the list of posts. For example, you could call Recent Posts twice, once with skip set to 0 and once set to 5 to produce a two-column listing. The default value is 0.
Omit current post?
On some occasions you may want the current post to be dropped from the output. By default Similar Posts omits the current post while the other post plugins include it.
Show password-protected posts?
By default posts which are password-protected are not shown but they can be included by setting this option.
Show static pages?
WordPress has static pages as well as the normal flow of posts. You can choose to show both pages and posts or either one alone. By default, only posts are included.
Show attachments?
WordPress stores attachments (or links to them) among normal posts and pages. You can choose to show them if you wish. By default, they are not included.
Show by status
WordPress assigns posts a status, e.g., whether they are published or not. This option lets you display posts with chosen states: published, draft, private, and future.
Ignore posts older or newer than…
Sometimes it is useful to only include posts that are more than, or less than, a certain number of days, months, or years old. A news site might want to show random posts from the last week, for example.
Match posts by custom field
If you wish you can use the very flexible post-meta system to select posts. At the most basic you can limit matches to posts where a specific custom field exists. You can also check that a custom field has a certain value. The ‘LIKE’ operator can be used with wildcards (‘_’ matches any single character, ‘%’ matches zero or more characters). You can even use the MySQL REGEXP operator for complex matches. Please bear in mind that matching by custom field may slow down the plugin considerably.
Limit matches to same category?
By default, posts from any category are included but it can sometimes be useful to restrict the display to just those posts which share at least one category with the current post.
Match the current post’s tags
This option (only available for WordPress 2.3+) uses the current post’s tags to restrict the output. It can look broadly for posts with any of the tags, or strictly for all of the tags. If the current post is untagged or there are no matching tags the normal output is produced
Match the current post’s author
This option let’s you restrict output to posts which share the current post’s author
Default display if no matches
Occasionally, for whatever reason, a plugin has no items to display. By default it displays instead the text 'None Found' but you can change the message to fit your blog or language. You could even include a link,say, to your ‘about’ page. The before and after settings are ignored but if you embed output tags they will be expanded.
Show nothing if no matches
As an alternative to displaying a default message, this option causes the plugin to produce no output at all (from v. 2.6.1.0 also works when the pluginj is used as a widget).
Text and codes before the list
Lets you specify text and HTML before the list of items, e.g., to title the list. By default is used.
Text and codes after the list
Lets you specify text and HTML after the list of items. By defaultis used.

Output template
The output template specifies what gets displayed for each item in the output. For example, the default output template for Recent Posts is

  • {link}

 

. Read from left to right it governs the output for each item in the list of recent posts. In this case it is a beginning and ending HTML list tag with something in between. The code, {link}, gets expanded for each item — and displays the post’s permalink with the post title as the text and the date of posting as the ‘tooltip’.
The output template treats anything between ‘{‘ and ‘}’ as a special instruction or tag. A full list of output tags is given below. The tag system allows you to customise the plugin’s output to a high degree, for example,

{link} by {author} ({commentcount} comments)
{snippet:50} …
outputs each item as part of a definition list showing the permalink, the author, and the number of comments the post has, followed by a 50-character snippet of the content and a trailing ellipsis.
The exact way these elements are displayed depends on your theme’s CSS. Applies to each plugin.
Text to trim at start replaced by ‘divider’
usually the plugin output will be some kind of list with each element sandwiched between matching tags. Sometimes, though, you might want to have the output separated rather than wrapped: a comma-separated sequence of items would be an example. The output template ', {link}' would basically do the trick but would produce an unwanted ', ' at the front of the first item. This option lets you enter ', ' and have the offending comma and space trimmed neatly out of existence.
Divider
usually the plugin output will be some kind of list with each element sandwiched between matching tags. Sometimes, though, you might want to have the output divided rather than wrapped: a comma-separated sequence of items would be an example. The output template '{link}' would basically do the trick but with divider set to ‘, ‘.
Authors to exclude/include
By default the plugin selects posts with no attention to who wrote what. By checking the appropriate boxes you can include or exclude posts by certain authors.
Posts to exclude
By default the plugin considers all matching posts in preparing its output. By including a comma-separated list of post IDs you can exclude particular posts from consideration.
Posts to include
By default the plugin considers all matching posts in preparing its output. By including a comma-separated list of post IDs you can only consider particular posts.
Categories to exclude/include
By default the plugin selects posts without caring how they are categorised. By checking the appropriate boxes, however, you can exclude or include posts in certain categories.
Tagging
This option (available for WordPress 2.3+) lets you specify a tag or list of tags to filter the output. For example, TAG A selects any post with that tag; TAG A, TAG B selects any post with either tag; and TAG A + TAG B selects only posts with both tags.
Other plugins’ tags to remove from snippet
If {snippet} is present in the output template the plugin tries to produce a simple glimpse of the post’s content without HTML or markup. However, many plugins insert pseudo-tags of their own which can mess up the snippet. If you want these tags to be fully expanded you can use the {excerpt} output tag instead but if you simply want them cut out from your post you can specify a set of opening and closing pseudo-tags to be removed.
For example, '[tag]' and '[/tag]' will cut out the whole of '[tag]embedded stuff[/tag]' while '[' and ']' will remove '[insert stuff here]'. In these examples it would be very important to place '[tag]' above '[' so they are removed in the right order. Pseudotags which contain modifiers, e.g., [quote comment=12], can be removed with the aid of a wildcard, e.g., [quote.*].
Content filter
Ordinarily, the plugin’s output is displayed wherever you place the tag in your template or, alternatively, where you place the corresponding widget. This option offers a third method of placement: a filter which looks for embedded tags in content. For example, the tag <!--SimilarPosts--> placed in the body of a post would be replaced by a list of similar posts. This lets you insert plugin output on a post by post basis. Use <!--SimilarPosts-->, <!--RandomPosts-->, <!--RecentPosts-->, , or <!--RecentComments-->. You can pass a parameter string to the plugin by putting the string after the tag, e.g., .
Note: even when the content filter is active the tags will not be expanded if they are being shown via one of the plugins, e.g., if Recent Posts is showing the excerpt of a post with a tag in it, the tag cannot be expanded with infinite recursion.
Sorted/Grouped Output
Each plugin produces a number of items sorted in the most usefulmanner for that plugin but you might want to sort the items differently. With these options you can sort the output according to the value of any (combination) of the output tags (though obviously some tags make little sense). You can sort in ascending or descending order and, where relevant, ignore case or not.These options let you choose two levels of sorting. Items will be sorted by the first set and then by the second. It is also possible to specify a group template so that groups of items which sort together can be titled appropriately. Note: The sort order does not change the output of the plguin, only the order in which it is displayed.

Group title template
This ‘title’ for each sorted group of items is specified in exactly the same manner as the output template. It appears whenever the primary sort tag changes.

The following options are only available in Similar Posts:

Maximum number of words to use for match
By default Similar Posts selects 20 words from a post to make its matches but this value can be adjusted to give the best results for your blog.
Relative weight of post title, content, and tags
Similar Posts lets you adjust the contribution the current post’s title, content, and tags make when looking for a match. The three numbers are specified as percentages and should add up to 100. Choose what works best for your particular set of posts.
Manual links
If this option is switched on you can use custom fields to override the automatic matching algorithm. From the write/edit screen enter a custom field named ‘sp_similar’ with the ID of the post or page to which you wish to make a manual link. Multiple links can be made with a comma-delimited list of IDs.
Term extraction algorithm
The quality of the automatic matches depends on the extraction from a post’s content of key terms which represent the post’s meaning. The original algorithm uses relative word frequency to pick terms. You can also choose a more sophisticated method which uses TextRank to extract key terms. In general this leads to better similarity scores but that may or may not correspond to the user’s sense of similarity.
Add output to feeds
Appends a similar posts list to feeds. Previously this was handled by a separate plugin.

The following options are only available for Recent Comments:

Show only one comment per post
The plugin usually lists all comments but you can choose to show only the latest comment for any post.
Type of comment to show
In addition to ordinary comments there are trackbacks and pingbacks. By default Recent Comments only displays ordinary comments but you can choose to show all kinds of comment or just trackbacks and pingbacks.
Type of grouping
The list of recent comments is usually displayed according to the order in which the comments were made but sometimes you might want to group comments by post or by commenter. If you choose to group the comments you may well want to give each group a heading using the group template. (This option is a specific case of the many ways of sorting the output — basically it overrides any sorting options)
Show just current post
Sometimes you want to only list comments for the current post.
Omit author comments
By default the plugin lists all comments but you might want to exclude comments by the author of the post itself. Note that this option relies on the author being logged in while commenting.
Omit user comments
By default the plugin lists all comments but you might want to exclude comments by registered users of your blog. Note that this option relies on the author being logged in while commenting.

The following option is only available for Recent Posts:

Select posts by date modified
Instead of the usual behaviour of ordering output by date of creation you can chose to select the posts which have been changed most recently.

Output Template Tags

Several output template codes or tags were mentioned above. They offer a very flexible way to tell the plugin what aspects of a post to display and new tags are easily added to extend a plugin.

For example, {author} expands to the name of the post’s author and {date} becomes the date the post was created. An output template of 'by {author} on {date}' might expand, for example, to ‘by Rob on January 1, 2007’. Dates, however, can be expressed in different ways. By default {date} uses the same date format as the blog but if you wanted a different format you could specify it as a kind of parameter to the {date} tag. For example {date:Y} would just give the year in 4-figure format.

The general form for an output template tag is '{tagname:parameter1:parameter2:...}', where the curly brackets identify the tag as a tag, the ‘tagname’ picks out the tag from a list of valid tags, and the optional ‘:parameter’ allows some output tags to be fed extra data. If a tag can take a parameter and none is supplied a default value is used and if a tag cannot handle a parameter and one is supplied it is ignored.

The various output tags call the same internal filters as WordPress does so that, if, for example, you have installed a plugin to translate foreign-language characters, the plugin output should also be translated.

The current list of tags is as follows (colon indicate the tag has parameters)

{title:maxlength:method}
The post’s title. If maxlength is specified the title wraps after that many characters. Method can be ‘wrap’, ‘chop’ (which simply truncates), ‘trim’ (which chops but adds an …), or ‘snip’ (which puts the ellipsis in the middle.
{url:maxlength:method}
The post’s permalink as a url. See {title} for parameters.
{postid}
The ID column of the post’s entry in the database.
{author:method}
The name of the post’s author. The default method ‘display’ uses the author’s display name; ‘first’ uses the first name; ‘last’ the last name; ‘full’ is equal to ‘first last‘; and ‘reverse’ to ‘last, first‘.
{authorurl}
The url of the permalink to the archive of the author’s posts.
{date:format}
The date the post was created — a date format can be specified or the blog’s default will be used, e.g. {date:Y, F} would print something like ‘2007, January’. A format of ‘raw’ gives a value sueful for sorting.
{datedited:format}
The date the post was last edited. See {date} for parameters.
time:format}
The time the post was created. See {date} for parameters.
timeedited:format}
The time the post was last edited. See {date} for parameters.
{excerpt:maxwords:method:more:link:sentences}
An excerpt of the post. Maxwords is the desired size of the excerpt (defaults to 55). Method, which can be ‘a’ or ‘b’ governs the way the excerpt is generated: ‘a’, the default, uses the same method WordPress itself employs, taking the post excerpt if available or the post content if not, stripping tags and then truncating to length; ‘b’, respects embedded '<span id="more-523"></span>' tags and tries much harder to preserve formatting. The more parameter, which only applies to method b, lets you specify the text and codes to append to the output (by default, ‘ …’). If the link parameter is ‘link’ whatever you have chosen in more will be linked back to the post. If you set a value for sentences no more than that number of whole sentences will be included in the excerpt. If sentences is set to 0 the excerpt will be trimmed to the end of the last full sentence less than maxwords.
{snippet:maxlength:method:more:link}
A lightweight extract from the post, stripped of tags (and pseudotags). For example, {snippet:50} gives a snippet 50 characters long. The default is 100. Method defaults to ‘char’ but can also be ‘word’ which measures in words instead. Both approaches attempt to handle multibyte characters correctly. See {excerpt} for other parameters.
{fullpost}
Delivers the full post with all relevant filters applied.
{categorynames:separator}
The names of the post’s categories, e.g., {categorynames: | } might produce ‘wordpress | plugins’. Note that the separator parameter needs no quotation marks.
{categorylinks:separator}
As above but with hyperlinks to the appropriate category pages
{categoryid}
The ID of a post’s principal category, i.e., if a post has several categories in the same hierarchy it chooses the most specific; if a post has more than one category the first (i.e., numerically smallest) is chosen. This is most useful when posts have only single categories and can be employed, for example, to display specific icons etc.
{commentcount:zero_text:one_text:more_text}
The number of comments associated with the post. If the extra parameters are supplied different text will be used according to how many comments, e.g., {commentcount:no comments:comment:comments} will give ‘no comments’, or ‘1 comment’, or ‘2 comments’. If the parameters are not supplied a bare numeral is output.
{link:maxlength:method}
Shorthand for '<a title="{date}" href="{url}" rel="bookmark">{title:maxlength:method}</a>'
{custom:name}
The contents of the custom field with the given name. Useful in cooperating with the many other plugins which use custom fields.
{tags:separator}
The post’s tags. For example, {tags:|} might give ‘wordpress|plugins’. The default separator is ‘, ‘.
{taglinks:separator}
The post’s tags as clickable links to the relevant tag pages. The default separator is ‘ ‘.
{totalposts}
The number of posts in the blog.
{totalpages}
The number of pages in the blog.
{php:code}
The output generated by treating code as genuine PHP. This powerful tag should be used with great care as it allows arbitrary code to be executed. You can, for example, incorporate WordPress template tags or other plugin tags into your output.
Write your code as though echoing to output and be careful to remember your semicolons, e.g.,
{php:$s=' '.strtoupper("hello world").' '; echo $s;}
The {php} has access to the $result object variable which contains the values of the columns of wp_posts for the post in question, e.g., $result-&gt;ID is the post’s ID.
Putting {php:random_posts();} as what to display if no real matches are found provides a fallback display.
You can also include other output tags in your PHP code: just remember that they are not PHP variables but evaluate to literal text and may need to be wrapped in the appropriate quotation marks.
{postviews}
Tries to discover how often a post has been viewed by using any of a number of popular plugins. Let me know if the plugin you use isn’t catered for.
{image:number:width:height:timing:link:default}
An <img alt="" /> element, if any exists, from a post’s content. By default, the first image is chosen but number can be used to select another (counting from 0 as the first). If width and height are given (as pixels) the image is scaled accordingly, otherwise it displays full size. If the height is omitted width is used to define a square bounding box into which the image must fit. If either width or height is given as ‘?’ the other of the pair is taken as fixed and the image scaled accordingly. The value of timing decides whether the image is extracted before or after WordPress applies its filters to the post content. The default is ‘pre’ but ‘post’ can be specified when, for example, a gallery plugin inserts images only after processing. If the link parameter is given as ‘link’ then only images wrapped in links will be extracted and displayed. Finally, the default parameter can be used to give an <img alt="" /> tag to output if no ne is found in the content.
{imagesrc:number:timing:suffix}
An image location, if any exists, from a post’s content. By default, the first image is chosen but number can be used to select another (counting from 0 as the first). The value of timing decides whether the image is extracted before or after WordPress applies its filters to the post content. The default is ‘pre’ but ‘post’ can be specified when, for example, a gallery plugin inserts images only after processing. The suffix parameter lets you add a string to the end of the image’s name, e.g., {imagesrc:0::xxx} might return ‘http://path/photoxxx.jpg’ instead of ‘http://path/photo.jpg’. There are two special values of suffix, ‘?t’ and ‘?m’ which use the current settings for thumbnail and medium image sizes to give the name of a reduced image, e.g., {imagesrc:0::?t} might give ‘http://path/photo-150×150.jpg’.
{imagealt:number:timing}
An image tag’s alt attribute, if any exists, from a post’s content. By default, the first image is chosen but number can be used to select another (counting from 0 as the first). The value of timing decides whether the image is extracted before or after WordPress applies its filters to the post content. The default is ‘pre’ but ‘post’ can be specified when, for example, a gallery plugin inserts images only after processing.

In addition, Recent Comments, has the following tags

{commentexcerpt::maxwords:method:more:link}
An excerpt from the comment, applying filters, and stripping tags (apart from smilies if they are activated). For example, {commentexcerpt:20} would give a 20 word excerpt. The default is 55. See {excerpt} for the further parameters.
{commentsnippet:number of characters:method:more:link}
A lightweight extract from the comment, stripped of tags. For example, {commentsnippet:50} gives a snippet 50 characters long. The default is 100. See {excerpt} for the further parameters.
{commentdate:format}
The comment’s date (local timezone). See {date} for parameters.
{commenttime:format}
The comment’s time (local timezone). See {date} for parameters.
{commentdategmt:format}
The comment’s date (UTC/GMT). See {date} for parameters.
{commenttimegmt:format}
The comment’s time (UTC/GMT). See {date} for parameters.
{commenter:maxlength:format}
The comment author’s name. See {title} for parameters
{commenterurl:maxlength:format}
The url left by comment author. See {title} for parameters.
{commenterlink:maxlength:format}
A link to the comment author’s url or, if none was given, just the commenter’s name. See {link} for parameters.
{commenterip}
The IP address of the commenter. It can be used, for example, to display an appropriate national flag.
{commenturl}
The comment’s permalink as a url.
{commentpopupurl}
The url to include in a link to open the comment popup window if the theme allows such.
{commentlink:text}
Shorthand for '<a title="{commentdate} at {commenttime}" href="{commenturl}" rel="bookmark">{commenter} commented on {title}</a>' an alternative to the ‘ commented on ‘ bit can be supplied as the text parameter. The {title} tag is wrapped in a span with class ‘rc-title’ and the {commenter} in a span with class ‘rc-commenter’, so that they can be styled by CSS. <code><code>'

  • {commentlink}

is the default output template for Recent Comments.

{commentlink2:text}
Shorthand for '<a title="{commentdate} at {commenttime} on {title}" href="{commenturl}" rel="bookmark">{commenter}</a> - {commentexcerpt}…'.
{gravatar:size:rating:default}
Displays a globally recognised avatar based on the commenter’s email address. By default, size is 96px. The ‘default’ parameter lets you specify the uri of an image to use when the commenter has no gravatar. Alternatively, you can specify ‘wavatar’, ‘monsterid’, or ‘identicon’ to have an individualised image returned as default.

Similar Posts, has one tag all to itself:

{score}
A measure of similarity ranging from 0 to (very) roughly 100 for an identical post.

There is one special tag which can be used in each plugin:

{if:condition:yes:no}
Lets you specify output conditionally according to the boolean value of condition. If condition evaluates to true the value of yes is output, otherwise the value of no. If yes and/or no are not given they default to the blank string. The conditionmust be a valid PHP expression; it can use WordPress or plugin functions; it has access to the $result object giving the contents of the current item’s row of the posts table; it can even contain further output template tags (but only one level of nesting of ‘{}’ is allowed.In addition, yes and no can contain output template tags of their own. For example, you might want to produce different output depending upon whether the current item is a page or a post:
{if:is_page():{date}:{dateedited}}
Notice the nested tags with {} within {}. Only one level of nesting is allowed.

Parameter Strings: Overriding the Options Page

Using the Options/Setting page and, in particular, the output template, the behaviour of each plugin can be fine-tuned in many different ways. But what if you wanted to use, say, Similar Posts in more than one place in your blog. You might want to have a comma-separated list of three related posts under each post on your blog’s front page but an unordered list of 5 related posts in the sidebar of your single-post pages. Somehow you need to give each use of the function different instructions.

Let’s start easy. Suppose we have set up our settings page to deliver the three links under each post of the main page. We can just use similar_posts() in the right place to get that effect but then we need to override those options when we call similar_posts in the sidebar. We can override an option by passing a ‘query-string style’ argument list to the plugin template tag, e.g., similar_posts('limit=5') tells the plugin to show 5 items rather than three.

To override more than one option at once an ‘&’ is used. In our case we need to override three options: ‘limit’, ‘output_template’, and ‘divider’ (the full list of option names is given below), i.e.,
'limit=5&amp;output_template=

 

&divider=’

.
Notice that 'divider=' assigns an empty string to the option.

It might happen that you need to specify a value that already contains an ‘&’. In that case you can override the default separator by making the query-string begin with ‘&’ followed by whatever character you want to use in its place, e.g.,
'&amp;|title=Bed &amp; Breakfast|limit=10'.

The full list of parameters is as follows:

limit
the maximum number of posts to show
unique (for Recent Comments only)
show only one comment per post
skip
how many posts to skip before listing
just_current_post (for Recent Comments only)
restrict output to the current post
omit_current_post
exclude the current post from output
show_private
include password-protected posts (true/false)
show_pages
include static pages (false/true/but)
show_attachments
include attachment pages (false/true)
status-publish
include published posts(false/true)
status-private
include private posts(false/true)
status-draft
include draft posts(false/true)
status-future
include future posts(false/true)
match_cat
restrict matches to current post’s categories (true/false)
match_tags
restrict matches to the current post’s tags (false/any/all)
match_author
restrict matches to the current post’s author (true/false)
show_type (for Recent Comments only)
which comments to show (all/comments/trackbacks)
num_terms (for Similar Posts only)
number of words used to generate matches
weight_title (for Similar Posts only)
weight given to title (0.0 — 1.0)
weight_content (for Similar Posts only)
weight given to content (0.0 — 1.0)
weight_tags (for Similar Posts only)
weight given to tags (0.0 — 1.0)
hand_links (for Similar Posts only)
whether to check for manual links (true/false)
term_extraction (for Similar Posts only)
the algorithm to use to get key terms (frequency/pagerank)
none_text
what to show if no posts match
no_text
no output at all if no posts match (true/false)
prefix
text and code before the list
suffix
text and code after the list
output_template
what to display
divider
text or codes between items
date_modified (for Recent Posts only)
select output by date modified not date created (true/false)
group_by (for Recent Comments only)
how to group list of comments (none/post/author)
group_template
what to display before each group of comments
tag_str
select posts by tag; ‘taga, tagb’ selects posts with either tag; ‘taga + tagb’ selects posts with both tags
excluded_posts
comma separated list of post IDs to exclude
included_posts
comma separated list of post IDs to include
excluded_authors
comma separated list of author IDs to exclude
included_authors
comma separated list of author IDs to include
no_author_comments (for Recent Comments only)
omit comments by the post author (true/false)
no_user_comments (for Recent Comments only)
omit comments by the post author (true/false)
excluded_cats
comma separated list of category IDs to exclude
included_cats
comma separated list of category IDs to include
content_filter
scan posts for embedded tags (true/false)
age-direction
(before/after/none)
age-length
how long a time
age-duration
(day/month/year)
custom-key
name of custom field
custom-op
comparison operator (=,!=,>,>=,<,<=,LIKE,NOT LIKE, REGEXP, EXISTS)
custom-value
value of custom field
sort-by1
output tag(s) to sort by
sort-order1
SORT_ASC or SORT_DESC
sort-case1
‘true’ or ‘false’
sort-by2
output tag(s) to sort by
sort-order2
SORT_ASC or SORT_DESC
sort-case2
‘true’ or ‘false’

Extending the Plugins by Adding Your Own Output Template Tags

Let’s say you have another plugin that generates output which you want to include in your recent posts list. It’s actually an easy job–it just means adding a your own code in one place.

Each template tag is defined in the library file /post-plugin-library/output_tags.php as a function with the name ‘otf_tagname‘. So, for example, the {postid} output tag corresponds to the function otf_postid(). The function signature is as follows:
function otf_postid ( $option_key, $result, $ext ) { ... }
where $option_key is the key to the plugin’s options (via get_option()), $result is the particular row of the query result as an object with all the database columns available, e.g., $result->ID or $result->post_title, and $ext is the ‘extra’ data passed along to the tag after the colon. Each output tag function returns the tag value as a string.

Looking over the existing output tags should give you the idea.

705 Comments

  • 1. George  |  May 18th, 2009 at 2:40 pm

    Rob: I had popular, similar, recent, random all successfully incorporated in my WP blog, but this weekend had to completely reinstall it due to getting hacked. I also reinstalled all the plugins. Now when I go to configure your plugins, I get this message: “Please install the Post Plugin Library plugin.” But I have Post Plugin Library 2.6.2.1 installed and it shows up in my plugins list where I have activated it already! Any ideas?

  • 2. Curt  |  May 21st, 2009 at 12:00 am

    Great plugin. I’m looking to add a little vertical space between posts. I’m sure I need to do that in the theme’s CSS file but where exactly and what is the code snip I need?
    Thanks!!

  • 3. Andy  |  May 21st, 2009 at 9:26 am

    This is fantastic info – I’ve used some of these in conjunction with the Similar Posts plugin to display a list of posts with clickable post and category links and post excerpts.
    I’d been looking for something like this for ages – a bonus – it works fine on a WP 2.7.1 installation too!
    Many thanks
    Andy
    Also, s tip for Curt: Just use the standard html code for a line break in the Output settings (if you are using Similar Posts)

  • 4. Stylin  |  May 21st, 2009 at 12:34 pm

    Love the plugin, need some help with {php:code}.

    I’m using the custom field to set an image thumbnail to each post. My single.php has the required code in place to check if an image exists for any post but I’m having trouble converting the php code required to show the image thumbnail into code useable by this plugin.

    Here is what I need the plugin to echo

    <?php 
    if($thumb !== '') { ?>
    	<img src="<?php echo $thumb; ?>"
    	alt="<?php { echo the_title(); } ?>"
    	/>	
    <?php } 
    else { echo ''; } ?>

    The if command is important, some posts don’t have a thumbnail. I’m not sure how to convert that.

    Thanks for your help.

  • 5. juma  |  May 21st, 2009 at 9:32 pm

    Hello!

    Great plugin but I need help – is there a tag to get the authors gravatar?

    Tanks for your help!

  • 6. Brian  |  May 22nd, 2009 at 11:18 am

    How would I organize similar posts to do the following:

    I have 6 posts, and for each post I want to indicate manually by post ID which of them show up under similar posts in a side widget.

  • 7. Mike  |  May 24th, 2009 at 6:42 pm

    Hi there. Thanks (again) for the wonderful plugins!

    Quick question, how could I call a HTML character, such as &raquo;
    from within a output template, such as:
    <?php if (function_exists('recent_posts')) recent_posts('included_cats=1&limit=7&output_template=<h4>{link}</h4><p>{excerpt}</p><p><a href="{url}">Read the full article</a></p>'); ?>

    (in which, I want to have the >> of the ‘raquo’ appear just after the “Read the full article” text)

    Thank you for any & all help!

  • 8. david  |  May 27th, 2009 at 4:21 am

    Very nice plugin, the output and css are much easier to adjust than other recent post plugins that I tried.

    I do have one problem. I’m using qtranslate for a multilingual site. In the output I use snippet, but the snippet is only in the default language. The titles are in the current language, but I can’t find where in the code I would add,

    
    if(function_exists('qtrans_useCurrentLanguageIfNotFoundUseDefaultLanguage')) $output = qtrans_useCurrentLanguageIfNotFoundUseDefaultLanguage($output);

    To get the snippet to appear in the current language. Is this the correct approach? Any help would be appreciated. Thanks.

  • 9. Tom  |  May 27th, 2009 at 7:13 am

    I am trying to show the number of views by using “{postviews}” with 2.7.1 and having a problem.

    It gets counted by 2. (eg. 68 to 70, 70 to 72,)

    Is there any way to fix this?

  • 10. Omid  |  June 3rd, 2009 at 8:11 pm

    hey,
    Thanks for the very useful plug-in. I have a problem in making this code work:

    <?php recent_posts(”|limit=5&output_template=
    {php:if (“{custom:night}” > date(“Y/m/d”))
    echo “{title}” . ” {custom:monthday} {custom:age}” . “”;}
    ‘); ?>

    when I take the part that’ is bold out the code work fine obviously :D. any suggestions to get around this problen would be great

  • 11. Omid  |  June 3rd, 2009 at 8:13 pm

    hey,
    Thanks for the very useful plug-in. I have a problem in making this code work: (ignore my prev post plz)

    date(”Y/m/d”))
    echo ‘“{title}”‘ . ” {custom:monthday} {custom:age}” . “”;}
    ‘); ?>

    when I take the part that’ is bold out the code work fine obviously :D. any suggestions to get around this problen would be great

  • 12. Jennifer  |  June 7th, 2009 at 3:54 pm

    Hi all. love love love the similar posts plugin. is anyone having the issue of similar posts duplicating in feeds (I see it in Google Reader, possibly others). Maybe it is a setting that I need to adjust? I am using version 2.6.2.0 Firefox Mac. Thank you!

  • 13. emacrisema  |  June 15th, 2009 at 6:24 pm

    I need to show ratings below posts , but in order to do that I need to set current id . Can I do that in wordpress admin – settings – output ?

  • 14. Sue  |  June 18th, 2009 at 1:50 am

    Hi Rob,
    I am using Recent Posts for my “Featured” section and would also like to use it to present my most recent 8 posts (all categories) in the opposite sidebar.

    How do I need to modify the php tag to accomplish this, or is there a better way?
    Thanks!
    Sue

  • 15. Says  |  June 18th, 2009 at 5:59 pm

    Hi thanks for the plugin.

    Is it possible to have title of the article that is currently displayed along side recent post come up in bold? I tried working around this in CSS with the a:active {font-weight:bold;} but that didn’t work. Also, currently bullet points appear next to each title. I wanted to remove them and instead have an arrow pointe only at the active link.

    Any suggestion would be great. Thanks.

  • 16. David Radovanovic  |  June 21st, 2009 at 12:22 am

    Thanks for a nice plugin.

    According to the directions above: When I use {image:0:75:?} the added ‘?’ is supposed to produce a thumb 75 x 100, though what I get is a 75 x 1 pixel image.

    What might I be missing? Thanks.

  • 17. Chad  |  June 30th, 2009 at 12:21 pm

    This is simply an amazing plugin. Thanks for the hard work.

  • 18. Kris  |  July 2nd, 2009 at 10:50 am

    How can I make two columns? Do I have to put “” twice in the post.php or in the output in similar posts settings? Please help?

  • 19. kernowkid  |  July 2nd, 2009 at 12:48 pm

    I’m trying to get the ‘:sentences’ parameter in the {excerpt} option to work to result in full sentences to be displayed rather than being cut off mid sentence but I can’t figure it out.
    Currently got this:
    {excerpt:50: : : :0 }
    but not working. Can anyone advise?
    thanks

  • 20. smit  |  July 8th, 2009 at 10:13 am

    I testing Similar Posts plugin in my site but I have warning message in menu Similar Posts > Filter Settings

    Warning: str_repeat() [function.str-repeat]: Second argument has to be greater than or equal to 0
    in /…/wp-content/plugins/post-plugin-library/admin_common_functions.php on line 593

    Is there any way to fix this?

  • 21. Brian Bell  |  July 9th, 2009 at 8:06 pm

    Rob,

    I’m wondering if your plugin can be used as a sorting mechanism. What I would like to do is create an un-ordered list in my sidebar.php file with links like: Recently Added, Recently Modified, List Alphabetically, etc. When you click these links in the sidebar.php, the posts in index.php would reorder to fit that sorting, does that make sense?

    It seems that your plugin grabs posts fitting certain criteria, and the displays them where the function was called. What I’m wondering is if your plugin can act as a link in the sidebar, and call the function over in the index.php which would then reorder the posts in the index.php.

    Thanks for any help you can provide. I appreciate your willingness to offer so much support for this, it’s awesome!

    Cheers,
    Brian

  • 22. Lee  |  November 16th, 2009 at 11:32 pm

    I am unable to use the option page from the link in the Random Post widget, I get the message “You do not have sufficient permissions to access this page.”

    is it the same pasge I can get to via settings>random post link?, that is working ok

    any ideas how to fix this?

    Lee

  • 23. Kevin  |  July 19th, 2011 at 8:14 am

    Great plugin.

    I was trying to figure out how to get a thumbnail image for a video clip to display, and I came up with a solution. Here it is:

    1. In the output panel I put:

    
    <p>
    <a href="{url}">{title}</a><br>
    <a href="{url}"><img src="{imagesrc}" width="100" height="75" /></a>
    <p>
    

    2. Then on the post page I used some simple span code to hide what would be an extra image:

    
    <span style = "display:none">
    <img src = "http://yoursite.com/imageToUse.jpg">
    </span>
    

  • 24. Zach  |  July 22nd, 2011 at 5:20 pm

    Hey Rob,

    I’m trying to use your plugin to the the most popular posts. I can list out the posts fine, however I am having difficulty getting the thumbnail to display for each post… I have tried multiple solutions:

    {php: get_the_post_thumbnail($result->ID, array(100,100) ); }

    That code should work in theory… since you’re supposed to be able to pass in any post id and get the thumbnail for it.

    {php: the_post_thumbnail(array(100,100) ); }

    That doesn’t work because it just loops the same picture for each post.

    The thumbnail is being set as a featured image and is NOT being inserted into each post… I wish I could just the whole {image} output tag.

    Any help would be appreciated!

  • 25. How to show from specific category?  |  July 29th, 2011 at 3:44 pm

    Hi,
    I want to show recent post in a side bar from a specific category.
    I don’t know how to write the PHP code for the command.
    I used the plugin in many other sidebars, but there’s a side bar which I want to show the recent post in it from a specific category!

    Thanks a lot!

  • 26. Svensson  |  August 8th, 2011 at 7:39 pm

    Hi!

    Great plugin! Everything works great! But how do I make the image link to the post?

    All the best!
    Svensson

  • 27. Svensson  |  August 9th, 2011 at 9:43 am

    Sorry, found it. I did it like this:

    {image:0:250:125} {link}

    Works great!

  • 28. Rachel McCollin  |  August 10th, 2011 at 10:19 pm

    Hi Rob,

    This is a really useful plugin, thanks. I’m trying to use the popular posts plugin to display custom post types – can you tell me if this is possible and if so how I would do it? I can’t find anything in the settings and I’ve tried looking to see if anyone else has asked the same question above – but to be honest there are so many comments I didn’t look in that much detail!

    Thanks.

    Rachel.

  • 29. Marc  |  August 24th, 2011 at 10:31 am

    Hi,
    I can’t find an option to turn the content filter on. When I insert in a post, it only appears as a html comment if inserted in html and as text if in visual tab.

    Thanks in advance for your help.

  • 30. Marc  |  August 24th, 2011 at 10:37 am

    the is missing in my last comment.

    It should be:
    “…I insert in a post…”

    of course without the spaces before and after the brackets

  • 31. Marc  |  August 24th, 2011 at 10:59 am

    damn 😉
    <!--SimilarPosts-->

  • 32. James  |  August 24th, 2011 at 10:22 pm

    @Zach (comment #674)

    To output the featured image of a post, use the following code:

    {php: echo get_the_post_thumbnail($result->ID, array(100,100) ); }{link}

  • 33. Marc  |  August 30th, 2011 at 2:45 pm

    I found the content filter option:
    Got to Settings -> Similar Posts -> Placement

    There it is the last Option: “Output in content (via special tags)” -> Select yes.

    Now you can put <!--SimilarPosts--> in the html tab of your edit/create post view and the posts will be displayed.

  • 34. franky  |  September 1st, 2011 at 7:06 pm

    <?php popular_posts('limit=10&output_template=<div class="single_img_block_img"><div class="side_img_block">{php:$vthumb = get_post_meta($post->ID, 'video_thumb', true); echo $vthumb.'/default.jpg" height="72px" width="96px" />';}</div></div>'); ?>

    i’m trying to get this working, however, the php part returns a parser error.

    I also tried this <?php popular_posts('limit=10&output_template=<div class="single_img_block_img"><div class="side_img_block">{php: echo' test';}</div></div>'); ?>

    and it also returns same error.

    thanks

  • 35. franky  |  September 1st, 2011 at 7:18 pm

    <?php popular_posts('limit=10&output_template={php:$vthumb = get_post_meta($post->ID, \'video_thumb\', true); echo $vthumb;} ');?>

    I got error message issue resolved. however, i’m only returning the last post’s $vthumb. Is there a way to retrieve all of them?
    1..10

    thanks

  • 36. Jesus Enrique Rosas  |  September 6th, 2011 at 4:52 pm

    Hey Rob, i hope you are doing well. ¿How i can style the text? i´m sure this is a dumb question, but been looking around how can i just adjust the font´s size. Obviously i´m not a PHP wizard, just entry / aficionado level. Thank you very much.

  • 37. Jesus Enrique Rosas  |  September 6th, 2011 at 5:02 pm

    never mind, i got it 😛 thank you for a great plugin!

  • 38. rocktivity  |  September 8th, 2011 at 4:46 pm

    Ideally, I would like my post page to have the current post in its entirely in the main area, and links to the next six posts in the sidebar. Can there me more than one recent post command?

  • 39. Fritz  |  September 11th, 2011 at 1:22 am

    The mysql database table for “similar_posts” has grown to over 9000Kb in size. My blog has around 2000 posts.

    Can I just empty the table to reduce the bloat?

  • 40. Paul Gardner  |  October 2nd, 2011 at 2:59 pm

    I have installed the Popular Posts plugin and activated it (after first installing the post-plugins library). But when I try to enter the configuration page, I get the following error: “You do not have sufficient permissions to access this page.”

    I am using the admin account and this is the first time I’ve ever had a plugin deny me access to it. Any ideas where I might be going wrong here?

  • 41. Ken  |  October 5th, 2011 at 9:09 pm

    I want to have a widget that omits one post on the front page, but then doesn’t omit it on other pages. Is there a way to do this?

  • 42. Bewitched  |  October 6th, 2011 at 11:24 am

    Hi, I’m using Popular Posts and I’m trying to customize the output. Currently it looks like this: {link}

    I’ve tried to add some variables to limit the number of symbols (maxlength:method) but when I add them the plugin seems to stop woking (I see nothing on the web site). So something like {link:maxlength:method} doesn’t work for some reason.

    Thanks!

  • 43. Tom Copeland  |  October 26th, 2011 at 5:26 pm

    Great plugin. Quick question on syntax for output –
    Trying to get the excerpt and sentences to work. What’s the syntax? I’ve tried:
    {excerpt:sentences=1}, {excerpt sentences:1}, {excerpt sentences=1}
    Can you show me an example of how to properly use the string?
    Already rated this bad boy, awesome and super powerful – great work!
    T

  • 44. Susan Kitchens  |  October 31st, 2011 at 9:24 pm

    I’m working with Recent Posts for display in a sidebar of a site.

    I’d like to somehow display the image as a cropped square thumbnail. Or else use the Output Settings to grab the special square-thumb version that I have put in the EXCERPT part of the blog post.

    Here’s the code I’m using for OUTPUT:

    <h4>{link}</h4>
    <a href="{url}">{image}</a>
    <p>
    {excerpt} <a href="{url}">Go &raquo;</a> 
    </p>

    I’ve made special square versions of the photos, and uploaded the square photos in the EXCERPT portion of the WordPress admin section for the blog post in question.

    The plugin seems to be processing the image that’s in the body of the post. They’re showing squashed.

    You can see the current state of things by visiting http://www.oralhistory.org/ and viewing left sidebar under “Feature”

    (I’ll next attempt to force a proportional thumbnail image using width tags)

    Thanks for any help/enlightenment you can provide!

  • 45. Susan Kitchens  |  November 1st, 2011 at 3:21 pm

    p.s. tho the last post said you can see it when you visit the site, I since went and uploaded a very small square thumbnail, so that the image that shows on the front page isn’t squashed. (You see it when you click through to an individual post; there are 2 images, a small square one, and the “real” image.)

    I see from elsewhere that this plugin won’t crop images.

    What isn’t clear to me is whether it can pull from the WordPress-generated thumbnail for an uploaded image.

  • 46. Gero  |  February 16th, 2013 at 1:17 pm

    I’m having problems with the output of a default image. As described for the {image} placeholder, there is a default option. As described this should be filled with an tag. But, if I try something like:

    {image:0:150:150:::}

    Nothing is shown, if no picture is found. How do I have to format the tag to make it displayed?

  • 47. Gero  |  February 16th, 2013 at 1:25 pm

    Ups! The Comment form ate my tag. Replaced the opening and closing with a #

    {image:0:150:150:::#img width=’150′ height=’150′ alt=’Default Image’ src=’/wp-content/themes/wood/img/no_thumb.jpg’#}

  • 48. Rocktivity  |  September 2nd, 2013 at 7:39 pm

    Exactly what do you put where in the Placement section to make it work at a widget, and exactly what do you put in the text box on the widget page? Would a shortcode work?

  • 49. Rocktivity  |  September 25th, 2013 at 7:03 am

    Still having problems, the first five post are not being skipped.