Textpattern tips, tutorials and code snippets

Custom article groups in Textpattern

Editor note: This article is an update to the Related articles with custom-fields TXP Tip.

Textpattern has a related_articles tag that relates articles by category. This works well for many uses, but sometimes you want finer control. related_articles either looks at both categories assigned to an article, which can be too broad, or only one, which can be too narrow. It also looks only for exact category matches and does not look further up or down the category tree (the chh_related_articles plugin can do so, however).

Say you have groups of articles about each year’s Wimbledon Championships going back several years. All of these articles are closely related and will almost certainly use the same categories, and yet you probably don’t want articles from 2007 showing up on the related articles list for an article about the 2009 tournament, and vice versa. You could create a special category to identify this grouping, but that doesn’t fit well with Textpattern’s limit of two categories per article.

My first solution to this problem was to “hard-code” related article IDs in a custom field. Not exactly “best practice” content management, and it gets out of hand quickly for a large group of articles: you have to update every article in the group when adding or removing an article, exactly the sort of thing a CMS is supposed to avoid.

Despite it’s awkwardness, I’ve used the above solution on a couple of websites, but I finally realized that the process would be much simpler if I treated the custom field as an identifier rather than a container. The only drawback is losing the ability to arbitrarily sort the articles by their order in the custom field. But when this order is important, it’s probably also wanted in standard (e.g. front page) article lists. Indeed, I already had another custom field devoted to sort order in the websites where I use this method.


  1. Assign a custom field. I call it Related.
  2. Enter a group name in this field for each article in the group.
  3. Add the following to your page or article form, where you want the list of related articles to appear (vary the HTML markup to suit; note that individual article context is required):
<txp:if_custom_field name="related">
<txp:variable name="this_id" value='<txp:article_id />' />
<h2>Related articles</h2>
<txp:article_custom related='<txp:custom_field name="related" />' wraptag="ul" break="li">
<txp:if_article_id id='<txp:variable name="this_id" />'><txp:else />
<cite><txp:permlink><txp:title /></txp:permlink></cite>

Unlike the ID-based solution, if you want arbitrary sort order you will need a second custom field. (By the way, don’t name it Sort; that is on the list of forbidden custom field names.) Then add sort="custom_n asc" (or desc), “n” being the custom field number.

Note the use of variable to keep the current article from appearing in its related articles list.

You have to manage these group names without help from Textpattern; with a lot of them it could be a hassle to keep track. I can envision a plugin-based solution to this, but for my needs now the above solution is sufficient.

You could cook up a similar solution with Multidoc, but to me Multidoc is for a different kind of article taxonomy. (It’s also a big plugin for a small problem like this.)

5 Comments Comment feed

Did you mean customfieldname? I do not find such <txp:article_custom related=""> attribute in the docs.

Note that the TextBook listing for article_custom’s customfieldname attribute says:

Replace “customfieldname” with the name of the custom field.

So if you have a custom field named “related”, you can then use:

<txp:article custom related="some value" />

Oh, really. Excuse me and thanks for the note!

This is exactly what I’ve spent the past hour or so attempting to figure out how to do. Steps one and two I had, I just couldn’t quite figure out the proper markup – problem now solved. Thank you very much!

Thanks Jeff. Just used it on a site tonight and it works perfectly!

Add a comment

Use Textile help to style your comments