Last updated: 2005-12-08 12:42

List articles in the same category as the current article

<txp:chh_related_articles />

The plugin’s default behavior is to return a list of articles that have one or more categories in common with the current article. You can also explicitly specify this behavior by relation="category".

or in a subcategory of the current article’s categories

<txp:chh_related_articles children="y" />

The children="y" attribute enables subcategory expansion. The tag will return articles in the current article’s category or in any subcategory of the current article’s category.

This option requires that the chh_article_custom plugin be installed and active.

List articles by the author of the current article

<txp:chh_related_articles relation="author" />

The author relationship matches other articles created by the creator of the current article.

List articles related by keywords

Create a list of articles with keywords that match one or more of the current article’s keywords1.

<txp:chh_related_articles relation="keywords" />

and restricted to the current section

<txp:chh_related_articles relation="keywords" section="?" />

You can also specify a list of specific sections as section="news,archives"

and restricted to the current article’s categories

<txp:chh_related_articles relation="keywords,category" section="?" listmode="all" />
  • relation="keywords,category" specifies two article relationships: keywords and categories.
  • listmode="all" tells the tag to only return articles that match all—in this case, both—relationships (listmode="any", the default, will list articles that match either relationship).

and restricted to the current article’s author

<txp:chh_related_articles relation="keywords,category,author" section="?" listmode="all" />

So now we have a tag that will list articles in the current section, with one of the same categories as the current article and created by the same author, and with keywords that match one of the current article’s keywords.

List articles related by a custom field

<txp:chh_related_articles relation="My Keywords" />

This will return articles where the custom field named My Keywords contains the entire contents of the My Keywords field of the current article.

If the field contains a comma-separated list of words like the keywords field, you will need to set the custommode attribute to list so that the returned articles will have a custom field that contains at least one of the keywords1 in My Keywords:

<txp:chh_related_articles relation="My Keywords" custommode="list" />

You may also use the labels custom_1, custom_2, etc. to designate the custom field to use. However, the custom field still must have an associated name (set via Admin > Preferences > Advanced Preferences). Unnamed fields cannot be “seen” by this plugin.

List articles related by linked fields: e.g.,keywords that match a custom field

If you want to list articles that match a certain set of keywords that are different from those in the current article’s keywords field—a sort of one-way relationship—you can use the arrow operator (->) to create a link from one field of the current article to a different field in the article list:

<txp:chh_related_articles relation="My Keywords->keywords" custommode="list" />

This will take a list of terms from the current article’s custom field name My Keywords and return a list of articles with a keywords field containing one or more of those terms.

You may link any relation types, and use a field more than once.

<txp:chh_related_articles relation="keywords->author,keywords->category" listmode="all" />

This will find articles with an author matching one of the keywords and a category matching on of the keywords.

Output articles as a simple list

By default, the tag outputs the same style list of permalinked articles as txp:related_articles and accepts the same wraptag attributes:

<txp:chh_related_articles wraptag="ul" break="li" label="Related Articles" labeltag="h2" />

Output articles as an article list

The tag can also output a txp:article_custom style list. Just set the form attribute to any existing article form.

<txp:chh_related_articles form="article-list" />

A note about keyword matching

1 This plugin uses the same technique for matching keywords (and custom fields) as txp:article_custom: a simple substring match. This means that a search for the keyword "key" will return an article with a keywords field like "monkey,lemur,ape", even though that’s probably not what you wanted. And if you list articles related by keywords to an article with keywords "monkey,lemur,ape", you will get articles with keywords "duct tape" and "Cape Horn".