tru_tags: A tagging plugin for Textpattern

filed under: , , , ,

5 March 2006

When I first created this blog I wanted it to have tagging support, which doesn’t come built into Textpattern (my blog software). At the time (Christmas 2005), tagging plugins for Textpattern were virtually nonexistent. Hunting around the web, I found ran_tags, chh_keywords, rss_unlimited_categories, and ajw_technorati_tags. They were all unworkable for me, because of bugs or complexity or feature-set, so I was left without tagging support.

So I wrote my own, based on ran_tags. I published it on the textpattern forums and subsequently released about a dozen new versions, each with new features to make it more powerful and/or easier to use. The plugin has seen a lot of adoption, and seems to be popular among the textpattern community. You can see it in use on this site.

It’s written with ease-of-use, simplicity, and security in mind, and it has a very rich feature set. To learn more, please check out the features list. There is one (potential) downside for some users, though. To help keep the code simple, I call out to the Textpattern code to actually do the tag search. That means that articles can only be tagged via the Keywords field, rather than using a custom field. Some people use the keywords field for other purposes, so they can’t use tru_tags. There are also a few other minor annoyances documented on the features page.

tru_tags can be downloaded from the releases page, and you can learn to use it by reading the detailed usage instructions. If you have questions, please post comments to any of these articles, or in the forum, and I’ll get back to you quickly.


  1. aldahlia says:

    Thank you! I’m so glad I held off until today to install ran_tags, or I wouldn’t have found this one!

  2. Nathan Arthur says:

    Great! Please let me know how it turns out.

  3. Nathan Arthur says:

    Update – you might also find interesting discussion about tru_tags in my post to the textpattern support forum or in tru_tag’s entry on

  4. aldahlia says:

    It’s working just fine. I just started using txp about two weeks ago, so I’m still wrapping my head around it.

  5. Thomas says:

    Thanks for the plugin! I tried it, and so far so good. Anyway, is it possible to have the ”+” sign when I have more than one word in they keyword? For example, “daily life” becomes tag?t=daily+life

    Just an idea, but so far, I am happy with it! Many thanks!

  6. Nathan Arthur says:

    By default, no, there’s no way to make that work. But it is possible to make one small change to the Textpattern code to get it to work. Check out this post and if you do make the change, please let me know.

  7. Brian says:

    Nice work! I got one feature request. The “showcounts” is nice, but why not display the count in a “title=” tag on the tag link. So when you hover your mouse over the tag link it will display the number of posts using the tag.


  8. Nathan Arthur says:

    Done, in v1.2. It’s not on by default – if you just want the counts to show up in the title attribute, use showcounts=”title” in tru_tags_cloud. See the documentation for more details.

  9. David Russell says:

    Is it possible to add tags to the ‘post body’ of the Atom feed?

  10. Nathan Arthur says:

    David – not easily. Textpattern’s feed support is essentially “our way or the highway.” Some users figured out how to hack the source to get it to work, as described in this forum thread. I think the code posted there should work just fine with tru_tags, if you changed his fetch_tags() method to have a $delim of ’,’ and a $field of ‘’. If you get it to work, please let us know!

  11. Josh says:

    Are there any plans to incorporate a “Related Posts” feature into tru_tags??? Thanks in advance.


  12. Morgan Aldridge says:

    I was starting to think that Technorati couldn’t be integrated into Textpattern without some hacking, until I realized that Ping-O-Matic does the pinging for you and all I had to get working was the tagging. I noticed that Jon Hicks had integrated tags into his site at some point, so it didn’t take long for me to find myself here.

    Tags fully integrated into Textpattern and no hacking required except a minor edit to the .htaccess file. It’s working great!


  13. Markus Merz says:

    I am not getting the keywords to show up in meta description. Could some kinds soul post an example of the header code to be implemented? I have also tried with txp:keywords but the tag is ignored. Do I have to escape parts of the code?

    (I also wrote a comment on the usage-instructions page about issues with leading dashes)

  14. Nathan Arthur says:

    Josh – I started to write a “related posts” feature, and then discovered chh_related_articles, which looks like it will do exactly what you want (it works with the Keywords field), and it has a million features. I haven’t tried it, though, so please post here if it works!

    Morgan – I’m glad you like it :)

    Markus – per my email, I don’t understand exactly what you’re looking for.

  15. Simon Finch says:

    Hi Nathan. Thank you, this is a wonderful plug-in .. it really opens up lots of possibilities. One added feature I’d really be interested in is the ability to sort tags, for example by most popular or most used. Anyone have any idea how to hack the sort option?


  16. Nathan Arthur says:

    I just posted v1.7, which supports sorting in the tag cloud :)

  17. Christopher says:

    Nathan, I have a question in regards to a tag search result. I understand that one can’t paginate the list – that’s fine by me. But when I go to an article from the resulting list, I would like to be able to navigate to the next article from that list (and not the next article in the section). Is this possible?

    I should note that I’m new to textpattern (love it though) and have yet to install your plugin. My question is derived from James Muspratt’s Widescreen photo gallery template.

  18. Nathan Arthur says:

    No, that’s not possible in the plugin as it stands today. I’m not sure if textpattern will do that with regular search results, even. (Maybe it can do it when you browse by category?)

    I can think of a way to do it, but it would be very hard and hacky. I see why you’d want it, though – it would make browsing by tag very pleasant. I’ll keep cogitating about it, but for now, I wouldn’t expect much.

  19. Vittorio says:

    Hi Nathan. I just installed your great plugin, but i’ve got 2 problems: i get an extra space before each comma in my taglist (like tag1 , tag2 , tag3 while in the keywords field they’re like tag1, tag2, tag3).
    In addiction, when i click on a tag, i see no results. I think i followed your instructions correctly, so…?

    Thanks in advance.

  20. Nathan Arthur says:

    I’m not sure what causes the spacing problem. I’ve had a few reports of it, but it doesn’t happen on my site, nor on most other sites. It looks like you fixed it on your site, though – can you post here and explain what was wrong?

    As for the tag search results not working, it’s almost certainly a problem with your tru_tags_handler call. Do you have everything configured so that when someone goes to the ‘tag’ section, the section is hooked to the right page which is hooked to the right form which calls tru_tags_handler?

  21. Jonathan Howard says:

    There is a small bug in function tru_tags_render_cloud().

    the variables $style and $tag_class are declared locally within if checks, but are used outside of those if checks. So if the if check returns false, they are undefined when trying to use them.

    Instantiating them outside the if checks with a value of ‘’ fixes the problem.

  22. RUDE says:

    I have the ‘extra space after comma’ issue that Vittorio mentions too, since I upgraded to 4.0.4, but the rest of the features are working fine for me.

  23. Nathan Arthur says:

    Jonathan & RUDE – I’ve already fixed both bugs (over this past weekend), but I haven’t published the new version because I’m working on a few enhancements also. It will be out soon.

    RUDE, if you set a wraptag in your tru_tags_cloud function, that should temporarily fix your problem. (I suggest using “p”.)

  24. RUDE says:

    thanks man ;-)

    I’ll be waiting for the new release.

  25. Hiram says:

    I’m very happy with trutags, but there is one thing that bothers me, and that is (let’s call it) tag overlap. If I have a tag ‘sp’ and a tag ‘ispoes’ (which is the case), clicking the ‘sp’ link will produce the entries tagged ‘ispoes’ as well. With some other tags (clicking ‘rain’ also finds ‘rain coat’) this behaviour may serve a purpose, but in many other cases, as in this example, it doesn’t (Ispoes is a cat and SP a political party). Could strict matching of tags be implemented somehow?

  26. Nathan Arthur says:

    Hiram – I agree, it’s a pain. It’s listed as one of the known issues on the feature list. I can’t fix it because it’s actually textpattern code that runs the search, and that code isn’t smart about it (and doesn’t give me any way to override it). Sorry :-(

    Long-term, I may take the time to submit a patch to the textpattern developers so it does what I want, but I’d have to write the patch, submit it to them, get them to apply it, and then wait for that version to be released. I’ve done a similar thing for the Atom/RSS feed code, but it’s a lot of work.

  27. Niko says:

    Would it be useful if you could limit the generated tag list in conjunction with sort=“count”?

    I’d like to have a list of the five most popular tags to be displayed on top of my weblog.

    I would hack the plugin myself, only then I couldn’t benefit from future upgrades – but if you find this feature useful I could send you a patchfile.

  28. Niko says:

    The new listlimit option works just great. Also some minor bugs I noticed in the last version are gone. Thanks!

  29. Gras says:

    Great plug-in! Actually the first plug-in I installed on my site.

    Have you (or someone you know) ever implemented a “Tags modifiable by users” feature?

    I Have a photo-blog (more photos than blog) that I would like to let the users tag. Typically I tag the photos with the names of the people in the picture. (I almost always miss someone!) Truth be told, I’d like to let them update the caption and titles as well.

    If not already done, any idea of the level of effort? (i.e. impossible, due to the design of TxP base code; etc.)

    Thanks for your thoughts (and tru_tags!)

  30. Nathan Arthur says:

    Gras – thanks :)

    I don’t know of a user-based tagging solution, but I can imagine a way to do it. It would require some pretty fancy tricks but I think it’s feasible for a plugin. It would be really hard :) I’ll send you an email. I’d like to see your site, and we can talk feature ideas. I’m not promising anything, but it would be an interesting extension to tru_tags.

  31. Strafverteidiger M√ľnchen says:

    Thanks for the instructions. They are very usefull.

  32. Nathan Arthur says:

    Glad to hear it! Thanks for the feedback.

  33. Ivo Toman says:

    Yes, realy usefull. Thank you very much.

  34. Jcl says:

    Just great. I hacked my way into rss_live_search so it’d use keywords too, which works great along with this plugin.

    I also want to do a small hack so textpattern can make use of a /tags/whatever+whatever2+whatever3 to filter out tags… will do as soon as I have spare time for it, shouldn’t be really difficult.

    Anyway, just wanted to thank ya :)

  35. Mike says:

    It’s very beautifully.

  36. Andreas says:


    thanks for the great plugin.
    Is it possible to integrate an attribute in “txp:tru_tags_cloud” to recognize only tags from the last xx days/articles?
    Or is there any solution for this problem?

  37. Martin says:

    Thanks, this am sought long

  38. Chris says:

    I get this error on the pages that use tags:

    Tag error: <txp:tru_tags_if_has_tags> -> Warning: extract() [function.extract]: First argument should be an array on line 84

  39. Chris says:

    Nevermind, I worked it out.

  40. Nathan Arthur says:

    Glad to hear it :) Let me know if you run into any other problems.

  41. tom says:

    the list of tags gets too long, but i can not delete some of it

  42. Nathan Arthur says:

    Tom: assuming that you are talking about the tag cloud, the listlimit attribute should be able to help you. Check out the the usage instructions for details.

  43. Caravan wise says:

    I’m busy searching about tagging and Ping-o-matic for Textpattern and happened across your site and have become re-enthused on setting up my sites with your plugin.

    Many thanks


    PS I love your header and footer image.

  44. Nathan Arthur says:

    Caravan wise –

    Thanks! It’s really good to hear positive feedback, both on the plugin and on the site.

  45. Rodrigo says:

    Hi I’m looking for someone who can help me with a plugin for Textpattern for a project in college. It would be a plugin that allows users to edit their comments. Thank you.

  46. MyKE says:

    Thank you for this great plugin! It works well on textpattern 4.4.1! :-)

Add a comment

(will not be displayed)

(not required)