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=

  • {link}

 

&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 replies on “Configuring the Post Plugins”

  1. JK: I suspect the best answer to both parts of your question lies in CSS.

    Probably the best way to ‘get rid’ of the styling in the thumbnails is to override it by a more specific style definition. For example, if your images are coming over with a messy extra class you can redefine that class for your situation. Let’s say it’s an unordered list:

    ul img.messyclass: {…}

    I’m not sure I’m making myself clear so get back to me if not.

    The nicely styled block from applepiepatispate isn’t that complicated in code — if you view the source it’s just a bunch of linked images produced by an output template like the one you are playing with. How it actually looks on the page is all a matter of CSS styling. You could experiment with floating the images left or you could contact the page owner and see if Jude is willing to give you some hints.

    Either way … good luck!

  2. David Putnam: This is problem in many situations. Similar Posts has to know what the ID of the current post is. In simple cases it is just a matter of looking at the global variable $post and checking its ID. Unfortunately, many widgets and plugins perform actions that corrupt the value of $post — even though strictly they should clean up after themselves. Similar Post tries a few more convoluted methods to find the ID but is still defeated under some circumstances.

    One workaround is to reorder your widgets to place Similar Posts before the corruption occurs — but that might not be practical for design purposes. Another option is to choose other, better behaved widgets to do the job of the ones which are causing the issue — but again that might not be possible.

    One way — if you are not averse to some coding — is to capture the value of the principal posts ID right after it is displayed:

    
    $my_post_ID = $post->ID;
    

    and then force the ID value just before Similar Posts does its stuff:

    
    $post->ID = $my_post_ID ;
    

    I can probably make that a bit a bit more automatic, now I think about it, and will see if I can sneak it into the release which is waiting in the wings.

    Thanks for stimulating an idea.

  3. Tanks rob for you interesting plugin, but in fact 1 feature missing me =) .

    Because I’m using wordpress for DJing event I need to publish in recent post something like “next 5” event.
    But I have published lots of event in the future. And using “the futur is now plugin” to have them displayed, and by this way I have no futur post, and all published.

    I need something like “newer” instead “old” in the “Ignore posts” configuration to do the trick to have, from today, the X next Gig.

    What are you thinking about the possible to add this feature in the next version ?

  4. Hi Rob,

    This sounds simple but I can’t find a solution. All I want to do is get an excerpt up until the first paragraph break (first sentence).

    Is this possible with your existing syntax or do I need to create a custom function?

    Simon

  5. Simon: Sometime ago I removed the ability for snippets and excerpts to be truncated by sentence–for the life of me I can’t remember why!–but enough people have requested it back to make me look into replacing it!

    In the meantime, I can offer you truncation at the <!--more--> marker which is what WordPress does.

  6. Hi,

    I’m already using a couple of your plugins and would like to start using the Similar Posts plugin.

    I would like to have a Similar Posts section at the end of every post and although I know that it would just be a matter of adding: somewhere within the WP loop or within the Single template (depending on theme). The fact is that I don’t really want to have to fiddle with PHP or CSS.

    Do you have any plans of adding an option that will allow us just to tick a box to automatically include say a Similar Posts section at the end of every post?

    Note that I have been testing a plugin called: “Add footer plugin” but it does not appear to allow execution of PHP code within it’s options fields.

    Any suggestions or tips on how I can go about doing what I want to do will be greatly appreciated.

    Regards,

    R

  7. Robert@PNG: It would be very easy to implement as an option automatically adding Similar Posts to the end of every post but I have been loath to do so for two reasons. First, because it would add the overhead of yet another scan through post content and second, because the territory at the end of a post is contested — there are any number of different ways that people fill it and there is no convention about what comes first or how to sort that out.

    Now maybe the overhead issue is more in my head than real (like so many things! and maybe, if I read around, I will find the battle for the end of post is easily managed. Convince me! In the meantime I recommend using Urban Giraffe’s sniplets plugin which lets you automatically place output at the end of posts and all sorts of other places.

  8. Jazykové pobyty: You don’t have to use the default {link} output tag — you can build your own, e.g.:

    
    <a href="{url}">{title}</a>
    

    Does that make sense or am I misunderstanding your question?

  9. jeferson dos Santos: The next release (out shortly) will support automatic placement.

    You can also manually insert the template tag, similar_posts(), in your theme files to get output anywhere you want it.

  10. Hi Rob,

    Thanks for your response to my query from 23/8 re placement of tag in post footer and the suggestion to use Sniplets Plugin.

    It works great!

    Noticed a later comment that you will be including this function within a future release. Looking forward to it.

    Thanks a mil!

    R

  11. Hi,

    this seems like exactly what i am looking for! I did read the pages but dont completely understand it.

    Can I just show random post (full posts no links) instead of the normal posting by wordpress by date? So that when a user go to my blog he just see a random order of all my posts?

    thank you so much!

    Henk

  12. Henk: You could use Random Posts that way but it isn’t exactly what it was designed for!

    You would have to put a call to the plugin in your theme’s index.php file, effectively replacing the WordPress ‘loop’. You would then use the settings page to create an output template that gave you the title, full post, etc.

    It should work.

  13. Hi!

    I’m using your excellent plugins with utmost satisfaction. I do have a question about recent comments.

    The thing is: I want recent comments to be displayed as they are at my blog with one exception, I just want the latest comment on each post to be displayed. Is it possible? If so – how? I read through this page without really knowing what I was looking for and I don’t know any php to do it myself. 🙂

    Thanks!

  14. Hi

    I am trying to output different text after the 5th recent post. If I have 10-15 in total is there any way I can get something to show between post 5 and 6 ?

    Thanks

  15. Alex: There isn’t a direct way of doing what you want but there is a kludgey workaround: call recent_posts two times and the second time use a parameter string to tell it to skip the first 5 posts.

  16. I could use some help. Using the recent posts plug in. I’m setting up a section on the blog that is for Upcoming Events (at http://brownstonepark.com).

    For posts that I want listed here, I ensure one of the categories is Events, and I add two Custom Fields – event_end_date and event_start_date. I’m using the format yyymmdd.

    I only want to display the events that have not ended yet, with the next event at the top of the list. But…

    For sort output by – I’m using the event_start_date.

    I’m also filtering to show only – in this example – posts 35,64,67.

    It does not seem like the sort output order is working.

    Would someone be willing to take a look and let me know if I should be approaching this a different way?

    Thanks!

  17. Steve: Hi! Maybe you could send the actual options since I’m not very clear on the detail of what you mean in some of the phrases above. It sounds like an interesting problem!

  18. Hi, I just installed your latest similar post plugin but it doesn´t seem to work. No similar posts is shown at all and I am at lost. Can you pls help? Thanks in advance,
    Mellie

  19. Mellie: Could you send a bug report from the similar posts settings screen? That will give me a little more idea what might be the problem. Can you also tell me how you are invoking the plugin?

    Thanks.

  20. Great Plugin!!! I’m trying to replace the default archive page with the output of this plugin. I’ve got it tweaked pretty much the way I want except for a couple of things.

    1. Before, I was using the “Evermore” plugin to truncate my post at the end of a paragraph rather than in the middle of a sentance. Is it possible to have that type of feature with this plugin?

    2. If I can’t have #1, what about this… I’m using {excerpt:75:b:Read More:link} and I’ve altered the library page so that my “more” link is inside a div, floated right and styled to look like a button. How could I put … at the very end of the last word, before the end “p” tag before the “more” link?

    3. Currently, using this in archive.php is useless because if I’m in a parent category or a child category, it outputs the same. Is there a way to have it only output posts from the currently selected category and it’s children only?

  21. Rob,
    Can you be more specific as to what would help you? All of the settings that I\’m using are listed above.

    (Note that your contact form is throwing an error for me.)

    Under Design > Widgets, I\’ve got the Recent Posts widgets in the side bar and the title is Upcoming Events. Showing 5 posts.

    When I create a post, I add two custom fields, one called event_start_date and the other event_end_date. The format for each is yyyymmdd – to help with sort order. As an example event_start_date 20080901 and event_end_date = 20080909.

    Under Settings > Recent Posts > Output, I have the \”Sort Output By:\” set to event_start_date (ascending). Output template is just the headline with a link to the full post ({link}).

    Under Filter, for Posts to include, I have listed the three events that I want to display. Just using post numbers with commas. Currently it is 64,67,35

    For Categories to exclude/include:, I am including the Events category and the news category since some are associated to both categories.

    That\’s the set up – I\’d be happy to provide you with access if you\’d like to look.

    – MY GOAL –
    All posts that are in category \”events\” that are happening in the future – as defined by event_end_date – show up in this Upcoming Events section.

    They should display with the next event at the top of the list – as defined by the event_start_date.

    It would be nice not to have to define the posts I want in the category. It would be nice that when the event ends, it drops out of the list.

    Does that make sense?

  22. Hi there,
    very good job.
    I have used your plugin every where on my news blog site.
    It was like tailor made for me.
    But unfortunately all my post used RECENT POSTS plugin save values and parameters of the first post of the page.
    E.g. BOOKMARKING plugin use overall the same permalink.
    I have used the code:
    <?php if (function_exists(\’recent_posts\’)) { recent_posts(\’limit=1&included_cats=1677&output_template={title}{excerpt:100:b:more:link}\’); } ?>
    For more please check my Site http://www.parsnewz.com/blog to see what I mean.
    Maybe I am using the wrong code if so please tell me which combination of code suit best to my scheme.

    Thanks in advance, Saeid

  23. gw468: The soon-to-be-released next version of the plugins lets you choose to restrict the excerpt to a number of whole sentences … I hope that will serve to answer your first two points.

    To solve your third issue I think you will have to use some PHP in your archive file to discover what category you are ‘in’ and then pass that in a parameter string to the plugin, e.g. ‘included_cats=$cat’. Make sense?

  24. Mellie: I’m afraid the comment box ate your code so I am none the wiser!

    You send a bug report by looking under settings/options for the Similar Posts menu. You should see a submenu entitled ‘Report a Bug’. Click there and follow the instructions. Thanks.

  25. steve: My brain is cramping as I try to understand your setup in the abstract. Let me see if I can duplicate it on my test server and I’ll get back to you.

  26. Steve: If I use

    {custom:event_start_date}

    to sort the output it kind of works the way you want but there are caveats.

    First is that though the five items are listed properly by event start date which actual posts get pulled from the database depends on the post’s publication date. I mean that a new post for a far future event could push out older posts for closer events. A possible solution would be to use the start date (in the future) as the post’s date and then specify that you want to show only future posts in the recent post listing. The catch would be that posts would cease to be marked as future once their start date is reached rather than their end date.

    You could fiddle with the PHP code of the plugin to select and order posts by event_start_date and use the end date as the (future) date of the post and show future. The modification shouldn’t be hard but it would be specific to your need.

  27. Rob: Sorry for my bad English.
    I use \”Odiogo\” and \”Share/Save Buttons\” Plugins within my wordpress blog on every post.
    If you click for example the \”Listen now\” button above the sidebar post, it reads the wrong text namly the very first text of the page.
    The same occurs to \”Share/Save Buttons\” .
    Hope, I could make me understood.
    The code is:

    Thanks very much for your quick reply.

  28. Hi,
    it\\\\\\\’s me again.
    Problem solved.
    For me it was better to use the {exerpt} tag without {:more} option.
    Now I am satisfied with that solution.
    Thanks a lot.

  29. Very useful plugin – thank you.

    My blog has about 50 posts. I have the plug-in set to display 4 similar posts per post. Sometimes the last few of the 4 are not similar at all. Is there a way to show less than 4 if the posts that would show have a low score/are not similar?

    Thank you.

  30. Rob,
    Thanks for the code with the custom part you noted above. I did not know that you had to put in the full {custom:event_start_date}, I was just putting in event_start_date in the Sort Output By: field.

    By doing that, and just sticking with identifying the exact posts I want to include in the Posts to include: Filter section (post numbers separated by commas) it works okay.

    If you get my explanation above, I think it would be a great feature to add to your plug in.

    Not sure what others think?

    Note that I do not think notifications are working for me on this thread – but I will try again.

  31. Steve: Glad you are getting it to do more or less what you want! I’m not sure exactly what you are asking for in terms of new features… whatever they are they would have to be pretty general.

  32. Mark: I’ve been looking into setting a cut-off point in terms of similarity — the problem is that the score which MySQL returns (and I weight) is pretty much a relative measure. Any particular cut-off will be too kind for some posts and too harsh for others.

  33. In terms of new features – for me, it would be nice to automatically display specific posts without the need to specify the posts to include.

    Use custom fields – like start and end date – instead

    Not sure how to go about it. Maybe it won’t work.

  34. Hello there,
    {imagesrc} is great, can i suggest another parameter for default link if no image is found. Thanks

  35. Really a loving Plugin.. I have a little problem with Removing some other plugins Tag from Snippet. The Tag is: {column2} some text {/column2} . Will you pls clarify me WHERE and WHAT to put in the code! Thanks.

  36. bearded: It depends on whether you want to remove the two tags AND all the text between them or just the tags and leave the text intact. I’m going to guess you want to take the text out too.

    If you go to the plugin’s submenu title ‘Other’ you should see two text boxes you can use to remove tags. In the ‘opening’ box enter {column2} and in the ‘closing’ box enter {/column2}. Save! After that the snippets should have the tags removed.

  37. Rob, you are great.. thanks for such quick solution. One thing more, is there any other way to include the Tag Removal code into the Output Template which I am using with on a specific pages. e.g. included_cats=4&limit=1&skip=1&output_template={title:20 method:trim}{image:0:50:50}{snippet:200 method:b more:..}

    please tell me Where and What to include in this code for the Tag Removal. Thanks.

Comments are closed.