tru_tags: Usage instructions

filed under: , , ,

10 November 2007

To learn more about tru_tags, check out the other tru_tags articles on this site.


  1. Go to the releases page to get the latest release. Don’t save it – just open it in your browser.
  2. Scroll down a slight bit and follow the on-page instructions: copy/paste the big square block of characters into your Textpattern install, under Admin -> Plugins.
  3. Hit “Upload”.
  4. Remember to switch the plugin to “Active” in the plugin list.


Step 1: Create a new section

tru_tags depends on the existence of a special Textpattern section named “tag,” by default1. Create that section, using whatever settings you like. (You won’t be publishing articles to that section.) Here’s what I use2:

tag section configuration

1 You can use a different name, but you have to modify a setting in the plugin admin page to make everything work correctly. To do so, go to Extensions->tru_tags and update the Preferences.

2 Note that I use the ‘default’ page – that choice may not be right for you. This section will be shown whenever you click on a tag, to display the tag search results. You’ll want a page that has the correct layout/headers/footers. I use my default page, with <txp:if_section name="tag"> to change the page display in this case.

Step 2: Call the plugin from that section

To make tag searching and the default tag cloud work, you’ll need to call <txp:tru_tags_handler /> from the page you chose in Step 1. I replaced the default <txp:article /> with something like this:

<txp:if_section name="tag">
  <txp:tru_tags_handler />
<txp:else />
  <txp:article />

Note that tru_tags_handler uses the default “search_form” form for rendering its output, or you can override this with the form attribute.

Step 3: Configure your article form to display tags

To make each article show a list of all the tags associated with it, put someting like this in your article form:

  tags: <txp:tru_tags_from_article />

Step 4: Drop a custom tag cloud somewhere, if you want

If you’d like to show a tag cloud somewhere on your site (other than /tag/), put something like this in that page:

<txp:tru_tags_cloud />

See below for lots of styling and formatting options, including the ability to output a simple list instead of a cloud (using tru_tags_list).

Step 5: Start tagging!

Whenever you write an article, put your tags into the Keywords field in Textpattern. (The Keywords field hides behind the “Advanced Options” link on the left side of the “Write” page.) Tags should be separated by commas, and can have spaces1.

Make sure that your articles are in a section that is configured to be searchable. tru_tags will filter out articles from sections that aren’t searchable. This is a common question on the forum. Please look there first if you are having problems or have any questions – they are often addressed there.

1 Tags with spaces will generate urls with dashes, which will work correctly. Tags with dashes will also work correctly. Tags with both spaces and dashes will not work correctly.

Other optional configuration

Customize your page titles

You can use tru_tags_if_tag_search, tru_tags_tag_parameter, and txp:search_term to customize your page titles or tag search results. See below for details. For an example, do a tag search on this site and look at the titlebar.

If you don’t like the fact that all tags are shown in lowercase you can use ”text-transform: capitalize” in your CSS stylesheet, in conjunction with an appropriate class attribute on your tru_tags_cloud call, to capitalize the tags.

Customize your RSS and Atom feeds

By default, tru_tags includes article tags in the RSS and Atom feeds, using standard XML elements so that Technorati (and others) will discover the tags. If you don’t want this behavior you can turn it off by updating the Preferences on the Extensions->tru_tags tab in the Textpattern admin.

tru_tags also supports adding article tags to the ‘body’ of the feeds. That will let your readers see the tags also. This is off by default to preserve backwards compatibility. You can turn it on by editing the tru_tags preferences.

By default, the tags will show up at the end of your post in a paragraph that looks like “tags: trees, flowers, animals, etc” (with links, and with rel="tag"). If you want to customize this display, simply create a new ‘misc’ form (in the Textpattern admin) named “tru_tags_feed_tags”. Anything you put into that form will be put into the ‘body’ of your RSS/Atom feed(s). I suggest using something like this:

<h4>filed under: <txp:tru_tags_from_article /></h4>

This feature is even more powerful, though. You now have a generalized way to add content to your articles in your feeds. I use my tru_tags_feed_tags form to add a “Read more…” link to the articles, and to include all the user-posted comments in the feed. I’m sure there are other uses.

For reference, my complete tru_tags_feed_tags form contains:

<p><txp:permlink>Read more...</txp:permlink></p>
<h4 class="tags">filed under: <txp:tru_tags_from_article /></h4>
<txp:comments />

Create a tag-based archive page

This one is complicated, but quite useful. The goal is to create an ‘archive’ page that shows all the articles associated with each tag in your cloud. For example, check out mine.

Creating a tag-based archive page is very similar to creating a date-based archive page, so this may be easiest if you follow those instructions first, and then convert over to a tag-based archive from there. Or you might prefer to just follow these instructions:

There are three main steps: create a new section, call tru_tags_archive from that section (specifying a custom form), and use if_different and tru_tags_current_archive_tag in your custom form to display the articles associated with each tag. In detail:

Create a new section. I named mine “archive” and I used the default page, but you may need different settings. Note that you could probably do this without a whole new section, by just calling tru_tags_archive from a specific article or page (e.g. if you wanted it in your site’s sidebar), but this is how I did it. Here are my settings:

archive section settings

On the page for that section, call tru_tags_archive and set the form attribute. For example, you could do this:

<txp:if_section name="archive">
  <h2 class="article_title"><a href="/archive/">Archives by tag</a></h2>
  <txp:tru_tags_archive form="tag_archive" />

You’ll want to set the form attribute to the name of a form you haven’t created yet – so make something up that sounds about right (like “tag_archive”).

Some explanation: tru_tags_archive works by looping over all the tags in your tag cloud, and telling textpattern to search for all the associated articles, and render them – using the form you specified (with form). In the next step, we’ll customize the way each article is rendered to make the output just look like a list of article titles, grouped by tag. That’s the tricky part :)

Create a new form and use if_different and tru_tags_current_archive_tag to render the archive page. Give the form the name you used in the previous step (with form).

This bit is a difficult to explain. Basically, the form should just render each article however you want (usually with just a title and/or date). But something needs to render a header that shows the name of the current tag, so that has to be done here also. The problem is that you don’t want the header to appear above every article – you just want it to appear whenever the tag name switches to a new tag. That’s where if_different comes in. if_different does exactly what we want – it only renders the header (the tag name) if it is different from the last time if_different was called. So, that allows us to do something like this:

  <h2 class="archive"><txp:tru_tags_current_archive_tag link="1" /></h2>
<div class="archive">
  <h3><txp:permlink><txp:title /></txp:permlink></h3>
  <h4>~ <txp:posted format="%b %Y" /></h4>

And if everything was done correctly, that’s it! You should have a working archive page.

One last (optional) step: double-check that the page title for your archive section actually says something useful. Depending on how you manage your titles, it might not.

Show a “related tags” cloud

tru_tags has a feature that lets you show a cloud of tags that are related to the tags used in articles that are found by a tag search.

Got that?

To see an example, do a tag search on this site. (Click a link in the tag cloud.) When the search results come up the sidebar will have a new section in it called “Related Tags”. The cloud in that section contains all the tags used by all the articles in the search result. It’s a way to say “these other tags may be similar to the tag you just searched”.

Before you use this on your site, however, you should read the detailed instructions (below) carefully. This tag can have significant performance implications for your site, which your hosting provider might not be very happy about.

To use it anyway, put something like this into the appropriate page:

<txp:tru_tags_related_tags_from_search section="blog,reference" useoverallcounts="1" />

If you use the section attribute in your main tag cloud you should also use it here. See the documentation below for an explanation of why.

The useroverallcounts attribute causes the cloud to size the links according to how large they would be in the main cloud. That’s probably what you want, but it causes even more performance slowdown. See the documentation below for all the details.

Customize the tag display on the admin side

By default, tru_tags will show a list of tags on the ‘Write’ tab, in the ‘Advanced Options’ flyout, under the Keywords box, in the Textpattern admin.


If the list of tags gets too long, though, you may want to turn it off, which can be done by updating the preferences. Alternatively, you can install hpw_admincss and customize the admin-side CSS as follows:

.tru_tags_admin_tags {
	display: block;
	height: 100px;  /* set this to whatever you want */
	overflow: auto; /* this will cause a scrollbar to appear */

Turn on tag auto-completion on the admin side

If you have the jQuery Autocomplete plugin installed, tru_tags can auto-complete tag names in the Keywords field on the Write tab. In order for this to work, the jquery.autocomplete.css and jquery.autocomplete.min.js files have to be installed in a “js” folder at the root of your site. Once that is done, you will also need to turn on the feature using one of the configuration options on the plugin Extension tab (in the admin side).

Ongoing tag maintenance

Over time, you may find yourself with a number of articles that you’d like to re-tag, but with no easy way to update the tags on all those articles at once. See the Extensions->tru_tags page for a few tools that can help you with that.

That tab also has a feature that will allow you to redirect out-of-date tag searches to newer tags. For example, if you had been using a “netbsd” tag, but then deleted it, search engines might still have the link to the old tag search URL. You can use the Redirections feature to tell tru_tags to redirect all searches for the “netbsd” tag to the “geek” tag instead. If you don’t set a Redirect, tru_tags will generate the standard 404 page (unless you have overridden this behavior – see below).

Admin-side settings

There are a few other settings that you can control on the Extensions->tru_tags page, if you need them.

There are also a number of attributes available for each of the tru_tags tags. The attributes can significantly change the behavior of the tag(s), including enabling some features. Please read the instructions below for details.

Tag reference


This is the main function that drives tag search and shows the generic tag cloud. It should be called from the page that is used in the ‘tag’ section. It usually calls doArticles() (in the Textpattern code) to display tag search results, but if no tag was passed in the url it will call tru_tags_cloud instead.

This tag accepts most of the standard txp:article attributes, which will be applied during the tag search. Note that tru_tags_handler does not support using multiple sections with the section attribute, when doing a tag search. If multiple sections are passed, none are used.

If a tru_tags_handler is called for a tag that is no longer valid, it will redirect the user to the site’s default 404 page. You can override this behavior with the noarticles attribute, which accepts a URL that it will redirect to, instead. You can turn off this behavior by setting the 404redirect attribute to 0.

Note: In Textpattern, the limit attribute is defaulted to 10, to limit the output to 10 articles per page, and the txp:older and txp:newer tags are used to paginate the full list. The txp:older and txp:newer tags do not work with tru_tags, but the limit is still used by Textpattern when it outputs the articles. Therefore, tru_tags uses a default limit of 1000 when doing an article search. You can override this limit by setting the limit attribute on tru_tags_handler.

This tag will also accept all of the attributes used by tru_tags_cloud. See below for details.


This conditional tag can be used in an article form, and will render its contents if the current article has tags.


This tag can be used in an article form to return a list of tags associated with the current article. Typically (see below), each tag in the list will be a link (<a href=...>) to the tag search url for that particular tag.

  • wraptag, break, class, and breakclass attributes1, as defined by Textpattern.
  • generatelinks="0" will show the tags without generating links
  • linkpath can be used to generate tag links that don’t go to the default location. For example, setting linkpath="" will cause tru_tags to generate tag links like
  • linkpathtail can be used to specify a suffix for the linkpath-based link. For example, setting linkpathtail="/" will put a “/” on the end of the generated linkpath url.
  • texttransform can be used to change the capitalization of the tags. By default, tags will be displayed in lowercase, which is equivalent to setting this attribute to lowercase. You can also set texttransform to capitalize (Like This), uppercase (LIKE THIS), or capfirst (Like this).
  • title can be used to set the tooltip for all the tags.
  • usenofollow="1" will turn on rel="nofollow" in the links. This is off by default.
  • usereltag="1" (default) will turn on the rel="tag" attribute (used by Technorati), if you are using clean urls. Note that this won’t work if you turn off links.
    • Note: Article tags are included in the RSS and Atom feeds (by default).
  • useoverallcounts="1" will tell the tag list to render as a cloud (where each tag is sized according to its site-wide frequency). This tag isn’t sufficient on its own, however; once you set it you also need to set the cloud rendering attributes like maxpercent="200", setsizes="1", and setclasses="1" because these are all turned off by default. You’ll also then be able to use attributes like showcounts and sort. See the tru_tags_cloud documentation for details on these attributes.
    • Be careful, however, before turning this on. This attribute causes tru_tags to do an extra database query for each article displayed on a page. That extra query is equivalent to the query used to generate the overall cloud. This can cause a significant load increase on your server.

1 As with all Textpattern tags, class is only used if you specify an appropriate wraptag and breakclass is only used if you specify an appropriate break.



tru_tags_cloud can be used on any page, and is generally used to generate a simple tag cloud of all the tags used on your site. The cloud is really just a list of links, much like that generated by tru_tags_from_article, but with a style attribute set on each link to give it a font size ranging from 100% to 200%.

tru_tags_list can be used on any page, and is generally used to output a bulleted list of all the tags used on your site. By default, the tags will all have a font-size of 100%.

These two tags do the exact same thing – tru_tags_cloud just provides different defaults to tru_tags_list.

tru_tags_cloud and tru_tags_list both set the class attribute of each tag, specifying two (or three) classes. The first class groups the tags into categories, with classes of tagSizeSmallest, tagSizeMedium, and tagSizeLargest. Using these, you could make the smallest and largest tags have different styles than all the others.

The second class indicates the “step” of the current tag, with classes of tagSize1, tagSize2, and so on. These give you precise control over each tag size, if you want it.

The third class is only set on one tag, if you are currently on a tag search page. The current tag under search is given a class of tagActive (by default), or to whatever you set in the activeclass attribute.

If you use these classes to create special CSS rules, you may also want to set the setsizes attribute, described below.

  • wraptag, break, class, and breakclass attributes, as defined by Textpattern. tru_tags_cloud has a default break of a comma. tru_tags_list has a default wraptag of ul and a default break of li.
  • activeclass can be used to specify the class that should be given to the tag currently under search, on a tag search page.
  • countwrapchars, which controls the characters used to show the tag count, if showcounts is turned on. By default this is []. The first character will be put on the left side of the number, and the second character will be put on the right. For example countwrapchars="()" would show: life (3), tech (5)
  • excludesection can be set to a section or a list of sections that should be excluded from the tag cloud. This is an alternate to the section attribute, below, which is used to limit the tags to those from a specific set of sections.
  • filtersearch="0" will tell tru_tags to change its default behavior and include tags from all sections the tag cloud, ignoring the “Include in site search?” setting that the site administrator can set on the “Sections” tab (under “Presentation”). By default, tru_tags will filter out any section that is set to “No” on that tab. Note that you can still use the excludesection attribute to exclude specific sections from the cloud.
  • generatelinks="0" will show the tags without generating links
  • linkpath="" will cause tru_tags to generate tag links like
  • linkpathtail can be used to specify a suffix for the linkpath-based link. For example, setting linkpathtail="/" will put a “/” on the end of the generated linkpath url.
  • listlimit will limit the tag cloud to the specified number of tags. By default, it will keep the tags that are most frequently used (and discard the infrequently-used ones). It will not necessarily show exactly the number of tags specified, though. For example, if you set listlimit="10" and your site has 3 tags that have been used 10 times and 4 tags that have been used 7 times and 8 tags that have been used 3 times, the cloud will only show the top 7 tags, because it wasn’t able to fit the last set of 8 into the limit of 10. This behavior can be changed with the following attributes:
    • cutoff="exact" will tell listlimit to show exactly the number of tags you specify.
    • keep="random" will tell listlimit to keep a random set of tags, but tags with a higher frequency have a better chance of being included.
    • keep="alpha" will simply sort the tags alphabetically and keep the ones that come first in the list.
    • Note: setting keep (to anything) will automatically set cutoff="exact".
  • minpercent and maxpercent, which can be used to control the weighted font sizes in the tag cloud/list. tru_tags_cloud defaults to 100 and 200, respectively, and tru_tags_list defaults to 100 and 100.
  • mintagcount and maxtagcount can be used to hide tags that only have a few articles, or that have too many. They are defaulted to 0 and 1000, respectively. For example, mintagcount="2" would hide any tags that were only associated with a single article. If you do this, you may want to add a link to the default tag cloud, usually found at /tag/.
  • section, which tells it to limit the list to tags from the given section or sections. For example, <txp:tru_tags_cloud section="blog,reference" /> would only show tags from the “blog” and “reference” sections. By default, this is set to blank (to show tags from all sections).
    • Note: if you use section to limit the cloud to a particular section, it won’t limit the tag search feature to that section. The tag search finds (tagged) articles from all sections, no matter what. That’s a side-effect of the use of doArticles(), and I don’t think there’s anything I can do about it.
  • setclasses="0" will turn off the default class attributes.
  • setsizes="0" will turn off the default font sizing so you can control the sizes yourself (through CSS). It will leave behind the default CSS classes, which you can use to control the display of your cloud.
  • showcounts="1" will append a number indicating the number of times a tag has been used, to each tag in the list. For example, you might see: life [3], tech [5] in my tag cloud, if this was turned on. This is off by default.
    • This can also be used to put the counts in the title attribute of the links, which will make it appear in a tooltip. Use showcounts="title" or showcounts="both" (to show it in both places) to turn it on.
  • sort can be used to sort the cloud by tag frequency, rather than the default of alphabetically. Use sort="count" to sort by frequency in descending order, and sort="count asc" to sort by frequency in ascending order.
  • texttransform can be used to change the capitalization of the tags. By default, tags will be displayed in lowercase, which is equivalent to setting this attribute to lowercase. You can also set texttransform to capitalize (Like This), uppercase (LIKE THIS), or capfirst (Like this).
  • title can be used to set the tooltip for all the tags.
  • usenofollow="1" will turn on rel="nofollow" in the links. This is off by default.
  • usereltag="1" will turn on the rel="tag" attribute (used by Technorati), if you are using clean urls. Note that this won’t work if you turn off links. Note that this is off by default in tru_tags_cloud and tru_tags_list.
    • Note: Article tags are included in the RSS and Atom feeds (by default).

Note that you can use the attributes to make tru_tags_cloud and tru_tags_list behave exactly the same way. tru_tags_cloud is just a convenience function for generating a tag cloud using tru_tags_list. Therefore, it’s possible to have a tag cloud with tag counts showing, or have a bulleted list with variable font sizes, etc.

This conditional tag can be used anywhere and will render its contents if the current url indicates that there is a tag search going on. This can be useful if you want to do something like customize the titlebar when using the tag search.

  • tag will let you check if the search is for a specific tag (like tag=“tru_tags”)


This tag returns the tag (keyword) you are searching for. This way it is possible to render the ‘keyword’ searched for on a ‘tag search result page’ (/tag/keyword). This is generally used with tru_tags_if_tag_search.

  • striphyphens="1" will convert all hyphens to spaces in tag names. This is useful because tru_tags will convert spaces to hyphens when it does a tag search, and this undoes that conversion so you can display the tag name with spaces.
  • striphyphens="lookup" will actually look up the specific tag name that you have used, and return it. This is useful if you have some tags with hyphens and some with spaces, but it has to go query the database every time so it isn’t configured this way by default.
  • urlencode="1" will url-encode the tag name, so you can embed it in a link.


This tag works exactly like search_result_excerpt, except that search_result_excerpt doesn’t work correctly with tru_tags tag-searches, so this tag works around that problem. Use this tag in any situation where you would have used search_result_excerpt, even for regular (non-tru_tags) searches.


This tag supports all the attributes of search_result_excerpt.


This tag is deprecated. Please use txp:search_term instead.

This tag can be used anywhere and will return the text the user typed into the standard search box, during a regular search. This tag is not specifically related to tagging, but can be handy for customizing the titlebar on search result pages.

This tag is useful on the results page of a tag search. It generates a cloud of all the tags that are used by the articles found in that search, excluding the search tag itself. For example, if a tag search for “life” found three articles that were tagged as follows:

  1. money, health, life
  2. money, politics, life
  3. life

tru_tags_related_tags_from_search would generate a cloud containing “money”, “health”, and “politics”.

This is useful for generating a “related tags” cloud, as you can see in the sidebar of this site when you do a tag search.

Before you use this on your site, however, be warned that it’s not good for your site’s performance, and it’s a little bit of a hack (and therefore may break with newer versions of Textpattern). It is implemented by completely redoing the database query that found all the articles in the first place, which means that your site is essentially performing the search twice. Then, depending on the attributes you use, it may do a second query that is equivalent to the query that generates the “complete” tag cloud.

You may want to test this carefully if you have a hosting provider who charges you for CPU cycles. :)

If you decide to use this tag, be sure to minic the section and limit attributes from your tru_tags_cloud (or tru_tags_list) call, along with any txp:article attributes that you used in your tru_tags_handler call. If you don’t, the set of articles found/used by this tag won’t match the set that are displayed to the user.

  • All the attributes of txp:article
  • All the attributes of tru_tags_cloud / tru_tags_list.
  • useoverallcounts, which makes the cloud render using the frequency data for the site-wide tag cloud.
    • By default, tru_tags_related_tags_from_search outputs a cloud where the weights are based on the frequency of the tags in the search results. Using the example from above, “money” would have a weight that was double the weight of “health” and “politics”.
    • This attribute will change that behavior, making the tag sizes match the sizes used in the site-wide tag cloud. In other words, this cloud will look exactly like a subset of your sitewide cloud.
    • It will also add an extra database query to the mix (mentioned above), so consider performance carefully before using it.
  • tag_parameter, which will let you show a list of related tags for any arbitrary tag. This could be used with a hard-coded tag name, or by using the new attribute parsing features in 4.0.7.


This tag allows you to create a tag-based archive page (like this one). It accepts all the attributes that txp:article accepts. Your best bet is to follow the instructions.


This tag is only useful in concert with tru_tags_archive. Using these instructions, you can make a site-wide tag-based archive page (like this one).

This tag outputs the name of each tag as it is rendered by tru_tags_archive. It is meant to be used with if_different (a core TXP function) to generate headings for the archive page.

This tag only accepts one attribute:

  • link, which will render the tag name as a link. By default, tag names are only output as text.
  1. Markus Merz says:

    I have just implemented this great plugin on my site (please follow link to see the issues). I am using txp:tru_tags_from_article to show the keywords below excerpts and full articles. It works very nice and fast.

    But I am listing keywords with ’, ’ (comma + space) and the clean URL then always has a leading dash for all keywords but the first. The second presentation glitch follows on my tag search result page where I am using txp:tru_tags_tag_parameter in the headline and the keyword shows up with the leading dash.

    Do you have a solution or patch for that?
    It should be sufficient to have an additional search and replace in function tru_tags_handler which would replace ’, ’ (n-spaces) with a single comma. But I don’t want to touch the code.

    The URL is OK when I enter keywords without space after the comma but I don’t want to do that because I am also using txp:keywords to get the keywords in the order as I entered them.

    It would be nice if you could reply with a mail (also).

    PS: The clean URLs in the keyword cloud are OK and don’t have the leading dash.

  2. Nathan Arthur says:

    Fixed in v1.6 :)

  3. Markus Merz says:

    Thanks Nathan! It works like a charm now.

  4. Martin Snížek says:

    That’s really a great plugin, I have just used it on one of my sites. But I would like also to use paging, could you please advice me how to do it?

  5. Nathan Arthur says:

    It essentially can’t be done with this plugin, because of the way it’s designed. Sorry :-(

  6. Adam says:

    please tell me it is possible to make each tag capitalized when they are in a list.

    “Projects, News, Events, Updates” and not “projects, news, events, updates”

    is this possible??? (i even capitalize each word when i enter them into the keyword window)


  7. David says:

    Adam—I’m not sure if tru_tags offers a way to do this, but this would be pretty easy to pull off using CSS. Just put a “text-transform: capitalize” on the element containing your list of tags. Hope that helps :)

  8. akatsuki says:

    I am having a lot of trouble with tru_tags_handler in that it never actually puts up the article, I can get a link cloud from it only.

  9. Nathan Arthur says:

    I took a look at your website, and it seems to be doing sane things. If I look at this page I get a tag cloud, and if I look at this page I get a list of articles. Can you describe your problem in more detail?

  10. Molly says:

    Hi Nathan— I made the additions to .htaccess and set clean URL’s to 1, and the URLs produced look right (clean), but when I click I get 404 Not Found. Any idea what’s wrong?

  11. Nathan Arthur says:

    It’s hard to know exactly what’s wrong, but it’s very likely a problem with the .htaccess file. Can you send me yours in an email, and I’ll see if I can figure it out?

  12. Jaro says:

    Nathan, thanks for the plugin, it’s amazing!

    Could you please advice me how to display a name of a tag in the title? I want to do something similar than you do here on your website – when you click on a tag the title of the tag is displayed in the title. E.g. tag: textpattern. How do I do that?

  13. Nathan Arthur says:

    Jaro –

    In the ‘page’ for my blog section, I have a line that says:

    < txp:output_form form=“page_title_sorter” / >

    (sorry for the spacing around < and > – textpattern won’t accept XML in comments)

    In the ‘page_title_sorter’ it says:

    < txp:if_search >
    < title > / search: < txp:search_term / >< /title >
    < txp:else / >
    < txp:tru_tags_if_tag_search >
    < title > / tag: < txp:tru_tags_tag_parameter / >< /title >
    < txp:else / >
    < txp:article form=“page_article_title” limit=“1” / >
    < /txp:tru_tags_if_tag_search >
    < /txp:if_search >

    That will give you the tag in the titlebar, like you were asking about (and a title for search pages, also). I then use my ‘page_article_title’ form to show the title for normal pages. That form contains:

    < txp:if_section name=”“ >
    < title>< /title >
    < txp:else / >
    < title >< txp:sitename / > / < txp:section / >: < txp:title / >< /title >
    < /txp:if_section >

  14. Jaro says:

    Nathan, thanks a lot! I’m gonna try this.

  15. Jaro says:

    Nathan, I can’t figure it out. I don’t understand this part of the code:

    < title > / tag: < /title >

    How come the name of a tag will be displayed after the colon? Is it somehow automated in the plugin?

    I’m just trying to get the name of the current tag displayed in the title. I know it must be easy but I can’t figure it out.

  16. Nathan Arthur says:

    Sorry, Jaro – there’s supposed to be a

    < txp:search_term / >

    in there, but I forgot to put the spaces in it and textpattern wiped it clean out. I fixed the original comment.

  17. rayc says:

    Nathan – superb work.

    One question – where is the css style defined for:

    tags: tag1, tag2 etc

    cheers from Tallinn.

  18. Nathan Arthur says:

    I’m not sure what you are asking here – if you look at the HTML source for a generated tag cloud, you’ll see that each tag has a number of classes assigned to it. You can create your own CSS rules that use those classes to style the tags. Is that what you’re looking for?

  19. Nathan Arthur says:

    ravc – try using the “setclasses” attribute in your “tru_tags_from_article” call

  20. Markus Merz says:

    A little change in the documentation:


    This tag can be used anywhere and will return the name of the current tag under search, during a tag search. This is generally used with tru_tags_if_tag_search.

    It accepts one parameter, striphyphens, which will convert all hyphens to spaces in tag names. This is useful because tru_tags will convert spaces to hyphens when it does a tag search, and this undoes that conversion.

    Pls. add striphyphens=“1”. I was to dumb to realize that just by reading and tried two other forms first :)

  21. Nathan Arthur says:

    Markus – done.

  22. Markus Merz says:

    Great update of the documentation!

    The only feature I miss right now is a possibility to maintain keywords i.e. Search & Replace.

    An added value of ‘keeping’ changed keywords for a while would be great. Most people starting with tags will have a need for cleaning up their tags after a while. As search engines already indexed the ‘wrong’ pages it would be great to have a redirect possibility.

    Happy New Year to everybody.

  23. Emil W says:

    Thanks for the great plugin. Really useful.
    One question. Is it possible to have the linked tags in the feeds ‘body’ linked to another site than my TxP site? I would like it to be[tag name] but only in the feed.
    Maybe that isn’t possible at all.

  24. Nathan Arthur says:

    Not at the moment, but it could be done. I’ll put it on the list for 2.1 :)

  25. Emil W says:

    That would be great. Thanks.

  26. Tony says:

    Thank god for your plugin!

    I just installed tru_tags and it is working like a charm in every way but one.

    Last night I want back through a bunch of my old posts and started tagging them up — at some point despite me not making any plugin or admin side changes beyond keywords … the clickable tag listed below keyword dissapeared.

    What should I do to get them back? I’ve checked the plugin language and it is still marked to be included.

  27. Tony says:

    I just scrolled down! The tags are still there – but have been corrupted somehow in their layout. What I see is this now:

    <!— var keywordsField = document.getElementById(‘keywords’); var parent = keywordsField.parentNode; parent.appendChild(document.createElement(‘br’)); var cloud = document.createElement(‘span’); cloud.setAttribute(‘class’, ‘tru_tags_admin_tags’); cloud.innerHTML =

  28. Garri says:

    Hi Nathan, just found your plugin – great stuff! I’m going to try and implement this instead of chh_keywords, as I’ve had problems with it. By the way, are you for hire?

  29. Garri says:

    OK, just installed the plugin and get this message in my ‘write’ screen: Fatal error: Call to undefined function: script_js() in … /textpattern/lib/txplib_misc.php(459) : eval()‘d code on line 402

    Do I need to upgrade TXP to latest version? I’m running 4.0.3

  30. Nathan Arthur says:

    Garri –

    Thanks! I am somewhat for hire, in that I’ve done contract work in the past in a few situations. I’ll send you an email so we can chat privately.

    And yes, you’ll need TXP 4.0.4 to use tru_tags 2.0. You can use tru_tags v1.0 with 4.0.3, but v2.0 is a pretty big improvement over 1.0 so I’d suggest upgrading TXP.

  31. Nathan Arthur says:

    Emil W – you can link to alternate locations/sites in the just-released v2.1 :)

  32. Markus Merz says:

    Not to be picky, but …

    # texttransform (...) You can also set texttransform to Capitalize, UPPERCASE, or Capfirst (...)

    Parameters should be written correct and an example should be provided (texttransform=“capitalize”).

    A Question for which I could not find a competent answer. Maybe someone can help:

    # usenofollow=“1” will turn on rel=“nofollow” # usereltags=“1” or usereltags=“0” (default) ... sets the rel=“tag”.

    (“0” is ON? Funny?)

    Is it standard conform to use both and still have a valid anchor??

  33. Nathan Arthur says:

    Markus –

    Good point about the instructions for texttransform. I’ve updated them appropriately.

    I reworded the usereltags instructions to make them clearer.

    And yes, you can include both words in the “rel” attribute and that should work (per the spec).

  34. Markus Merz says:


    I didn’t test it yet (just testing a tru_tags solution for a forum question :) and I did not read the complete spec. Is the correct output rel=“tag nofollow”, rel=“tag, nofollow” or rel=“tag” rel=“nofollow”?

  35. Nathan Arthur says:

    Markus – tru_tags follows the spec :)

  36. Markus Merz says:

    Thanks! Pretty simple … :)

    “The value of this attribute is a space-separated list of link types.”

    Btw: Maybe you could set a new date when editing/updating your plugin posts here. Only then the new version will show up in the RSS feed …

  37. Markus Merz says:

    tag cloud docu: “usereltags=“1” (default) will turn on the rel=“tag” attribute (used by Technorati), if you are using clean urls. Note that this won’t work if you turn off links. Note that this is off by default in tru_tags_cloud and tru_tags_list.”

    Bug in 2.1? It is not only OFF by default in clouds but it also stays OFF when explicitly setting it for a tag cloud. I just did that for a tag cloud on my homepage (sidebar). I used:

    <txp:tru_tags_cloud usereltags=“1” setclasses=“0” texttransform=“capitalize” sort=“count desc” showcounts=“title” mintagcount=“5” minpercent=“100” maxpercent=“160” />

  38. Nathan Arthur says:

    Markus, sorry about that. It was a documentation problem. The correct attribute name is “usereltag” (without the “s”).

  39. Markus Merz says:

    (Re above: Thanks! Working now)

    Nathan, how to get a raw list of related tags? The most naked result I get are tags still surrounded by span tags.

    Here is the more specific Forum comment

  40. Sebastiaan says:

    Hi! I need your help! :)

    I recently installed your plugin but I’ve got a problem. The ‘tag’ section works ( but when I click on a tag, like ‘Zwemmen’ it says ‘page isn’t found’.

    Thesame from the Tag cloud.

    What to do what to do :)

    Greetings from the Netherlands and thanks for your wonderfull plugin.

  41. Nathan Arthur says:

    It looks like this url is generating the right article list, which makes me think this is probably an issue with clean URLs. Does your site have clean urls on? Did you edit your .htaccess file? (You shouldn’t have.) Did you edit the plugin? (You shouldn’t have.)

    Let me know if any of this helps :)

  42. Sebastiaan says:

    Well, no :(

    It sure is right, the URL you gave. But I don;t know how to switch on clean urls, and certainly didn’t edit the htaccess or plugin :)

  43. Nathan Arthur says:

    Sebastiaan – thanks for letting me log into your site. It looks like there’s an incompatibility between rss_superarchive and tru_tags. Both try to rewrite the URL to meet their needs. If I turn off rss_superarchive, it makes tru_tags work.

    At first glance, it looks like rss_superarchive is rewriting all urls, not just the ones from whichever page/section it uses, but I’m not sure. I’ll ping Rob and see if I can figure out what’s up. In the meantime, it looks like you’ll have to choose between them. Sorry :-(

  44. Sebastiaan says:

    Well, I chose your plugin, and everything works just fine right now! :)

    Muchos kudo’s!

  45. Pieman says:

    Nathan… I’m using tru_tags and rss_suparchive together without problems. If you’d like me to test anything out then let me know.

  46. Stellaris says:

    Hi Nathan,

    I just installed your plug-in, no problems with that, thanks!

    However I enter tags in the keywords field, they’re output like below:

    tags: tagging , test , with spaces

    How can I get rid of the space before the commas?

  47. Stellaris says:

    Sorry Nathan,

    that was my own fault, never mind the question :)

    Your plug-in rocks!

  48. Nathan Arthur says:

    No problem at all – I’m glad you like it!

  49. Michael says:

    Great plugin! Thanks a lot for it. I was searching for it yet it did not appear to me until I started a completely different discussion at TXP-forums…

    However, I have a question: Is there a way to batch change tags like you can do it e.g. at flickr?

  50. alesh says:

    I’ve just upgraded from version 1.6, and I have to tell you again how much I love this plugin. It’s such a useful thing, and so well implemented.

    One question: does tru_tags_if_tag_search support ELSE? I would like to customize the tag cloud page at /tag, and this would enable me to do so.

  51. Nathan Arthur says:

    Thanks :)

    Yes, tru_tags_if_tag_search does support “else”. Let me know how it works – I’m interested to see what you do.

  52. khttw says:

    Very nice plugin.

    However, <txp:tru_tags_list> will not display keywords/tags from different sections. (tried on txp v4.0.5 only)

  53. Nathan Arthur says:

    It’s possible that something changed in 4.0.5 to break this, but I’d be surprised. Can you give more detail on exactly what does work and doesn’t work? You should also make sure that “Include In Site Search” is set to “Yes” for all of your sections – this post will help explain why.

  54. khttw says:

    Hi Nathan, thanks for your help. You are right about setting yes to “Include In Site Search” in order for it to put all the tags from different sections. It is working now. Thanks again for the really great plugin.

  55. bastian says:

    Hi Nathan.
    Wonderful Plugin. I just thought of how to realize a tagclod – and now it’s there.
    But I still have a problem [maybe it’s just because im not ver good in understanding textpattern]:
    When I click on a tag in the tag-cloud, all tagged articles are listed. How can stop the comments and the comment-form being listed with them?

  56. Ross Belmont says:

    Hi there,

    This looks great, but the one thing I don’t get is “tag search”…is there a way to actually have a search field post to a page with tru_tags_handler in it and return articles with similar tags? For example, is it possible to search on the term “george” and get back articles tagged with “george washingon” and “george clooney”?

    Or is “tag search” just the function of pulling up a list of articles with a given tag?


  57. Alvin says:

    Hi, I hope you’re still developing this plugin, as i’ve encountered a problem with the admin-side. The tag list isn’t showing, exactly as Tony mentioned. I am no coder, so I can’t be much help on this, but i can tell you that the JS code still appears underneath the “Publish” button.

    Thanks :)

  58. Nathan Arthur says:

    Bastian – did you ever get this sorted out? tru_tags uses the standard search forms, so you should see whatever output you see when you do a search. That’s something you customize on the admin-side, by editing some of the standard forms.

  59. Nathan Arthur says:

    Ross – Sorry for the long delay – I’ve been away from tru_tags for a while. The feature you describe was actually the default behavior before TXP 4.0.5 came out… and it was considered a bug by most :) I prefer it the current way, but sadly, I don’t have any control over it – it’s fixed based on whatever the TXP code does, not based on anything I do in my plugin. Sorry :-(

  60. jean-baptiste says:

    Hi Nathan!
    A small issue: I’d like the /tag/ section to be displayed as a list, so instead of calling
    < txp:tru_tags_handler / >
    I put
    < txp:tru_tags_list / >
    But the tags list it generates, even if clickable, still return to the tag list itself (adding the tag at the end of the url).

    Aside from this, when I use
    < txp:tru_tags_handler / >
    a click on a tag returns a list of article body, not excerpt. Is there a way to tweak this? Any help appreciated.

  61. Nathan Arthur says:

    jean-baptiste –

    You should be using tru_tags_handler, which will in turn render articles using whatever “listform” you define. By default, that will be the form named “search_form” (in the TXP admin), but you can override it via the “listform” parameter to tru_tags_handler. It sounds like you need to either create or customise your “search_form” form.

  62. Magnus Berg says:


    I’m struggling with your pluing and have the same question as Emil W had at Jan 17, 05:30 PM

    “Is it possible to have the linked tags in the feeds ‘body’ linked to another site than my TxP site? I would like it to be[tag name] but only in the feed.
    Maybe that isn’t possible at all.”

    Now I have got tru_tags to point to on my site. But pointing to my site in the feeds. And becuase of that my site doesn’t show up on I will have tru_tags to point to both on my site and in the feeds, but can accept the solution Emil W asked for.

    My site:
    My feed:

  63. Magnus Berg says:

    Hi again!

    I’m not struggling anymore. I’m happy! I find the magic tru_tags_feed_tags solution in your text.
    Now I can go to sleep.

    Thanks anyway, not at least for tru_tags.

  64. Nathan Arthur says:

    Magnus – that’s great :) I’m glad it worked out for you.

  65. Magnus Berg says:

    Sorry to disturb you again Nathan but is there a way to make it possible to combine two words to a keyword, like names, and keep the space between them. Now it always been a – between the words instead of a space.

    I saw your tips about changing in publish.php
    $keywords = “ and (” . join(’ or ‘,$keyparts) . “)”;
    $keywords = “ and (” . join(’ and ‘,$keyparts) . “)”;
    but that didn’t help.

  66. Nathan Arthur says:

    Magnus – I’m not sure what you’re asking. Tags with spaces should work just fine. The dashes only appear in the URL.

  67. Jaro says:

    Hi Nathan,

    thanks for this wonderful plugin. I’ve been using it since its early release and now I uprgarded to the latest version. I’m running into small problem though.

    I can’t seem to find out how to “turn off” the tags from the Writing tab. I don’t want them to be displayed there. In old version of your plugin it was done by editing the source code but now it says that everything is done via Extensions tab. I don’t have there an option to turn off the tag cloud from my Writing tab in Admin tab.

    Under the “Redirections” options I get the following error:

    @Fatal error: Call to undefined function radio_list() in /home/.nba/slape/ : eval()‘d code on line 529@

    I’m using the latest version of your plugin and the latest version of TXP. Do you know what’s wrong there?

  68. Nathan Arthur says:


    That’s great to hear – I’m glad you like it. On the issue with turning off the tags on the Write tab, it’s the very last option on the right side of the configuration tab (in ‘Extensions’). It’s called “Show a clickable list of tags on the Write tab”. Set it to No, and you should be set.

    I’m guessing that the error (with “radio_list”) that you are seeing may be preventing you from seeing that setting, though. radio_list() is a function in TXP 4.0.5 (see here), and in the latest development version. Are you using 4.0.5?

  69. Jaro says:

    Thanks for the answer, Nathan. You are right, I’m using TXP 4.0.3, not the latest version. I’ll update today and I’m sure the radio list will be visible.

  70. Jaro says:

    Updated TXP to 4.0.5. Works like a charm :)

  71. Nathan Arthur says:

    No problem – glad I could help. I didn’t realize that radio_list() was new in 4.0.5, so I updated the ‘releases’ page to make the dependency clear. Enjoy!

  72. johnplum says:

    Excellent plugin, all round. I’ve just installed it into a new textpattern site. Got it to work with my template, after some fiddling.

    I’m seeking to remove the tag cloud that appears by default on the top of the page. I can put the cloud into the sidebar. I don’t see mention of this behaviour by default.

    You can see what i mean at my url given in this comment form.

  73. johnplum says:

    One more question: is it possible somehow to post remotely using a trutags in the body of a post?

  74. de:code says:

    thank you very much: i searched for a way to implement something like extended categories. so i’ve messed around with rss_uc for about a day, without success. tags are anyway the better solution for me, and your plug in worked perfectly well from beginning.
    i love it, thank you very much.

  75. Nathan Arthur says:

    johnplum – thanks! Also, looking at your site, it looks like you’ve worked out the problem you were having. If not, please email me privately. (I’ll email you momentarily.) For the remote-post feature: I don’t think there is a way, now. I imagine that this is because you have a way to email in posts? If that feature supported a way to get things into the Keywords field, that would work.

    de:code – thanks!

  76. johnplum says:

    Yes Nathan…problem solved, somehow. I worked hard and fast in initial customising. THis is a classy plug..

    I can send to trutags/keywords with mt_keywords, and do this with Tinderbox. I don’t have a mail programme doing this, it would need the XLM_RPC protocol in a script…it could be set up, there may be one around already…i shall look shortly.


  77. liberskol says:

    How can I can adjust the plug-in in order to show me only the titles of the articles when I press a tag, not the whole article?

    Best regards and thank you for a useful plug-in!

  78. Nathan Arthur says:

    liberskol – the plugin uses the search_results form to render its output, unless you override that form using the tru_tags attributes. You should be able to customize your search_results form (or other specified form) to get the display you want.

  79. jonn22 says:

    good work

  80. David Zeibin says:

    Thanks for the great plug-in. It’s beautiful so far. I have two questions:

    1. Is it possible to change the separator character in tru_tags_cloud or tru_tags_from_article? I’d like just spaces instead of a comma. I’ve read through this but I don’t seem to see an option. (I can hack it via CSS by changing the color, but…)

    2. Is it possible to somehow extend the tagging to images in Textpattern? I’m working on a site where it would be great to do a tag search and see results for the appropriate tagged articles, images (and I guess files).

    Thanks again!

  81. Nathan Arthur says:


    For #1, yes it is possible – just set the “break” attribute appropriately. For #2, no, it’s not currently possible (without associating an article with every image).

  82. Yazmin says:

    Nathan – this plugin looks to be exactly what I’m looking for. But I have a problem (this is where you say “of course” ;) )…

    I created a “tag” section and my default “search_results” form is still intact and untouched. However, the <txp:tru_tags_handler /> is not showing the list of articles for the tag. I get the title of the section and the current day’s date.

    I’ve verified that I put it in the same page that I specified under my sections. I also know that the “else” portion is working, as it displays my other articles.

    Any suggestions on what else to look for?


  83. Nathan Arthur says:

    Yazmin –

    A few guesses:

    You might just have a problem with a mis-closed tag somewhere. I’ve had a similar problem before, and it turned out to be a missing close tag.

    What happens when you generate a tag cloud – are the tags there? That may give a clue.

    tru_tags_handler doesn’t (by default) show articles that are hidden or future-dated, so are all your articles visible on the normal site? Are all your article sections marked “searchable” in the admin? What happens if you search for words that are in the tagged articles?

    Are you using clean URLs or messy? What happens if you manually construct a messy URL? (Like

    Have you changed any settings on the tru_tags admin page (on the Extensions tab)?

    Any chance there’s a publicly visible example I could see?

    Also, just for future reference, you’ll usually get faster responses on the forum, just because there are more people paying attention. (And I see both posts the same way – through email.) Posting here is totally OK, but I thought you might want to know about the better option.

  84. Yazmin says:

    Thanks Nathan for the quick response! I’ll take my reply to the forums as well. :)

  85. adi says:

    It works perfectly but i have a problem with the encoding – though my site uses unicode cyrillic, nevertheless, tags look like rombs with question mark inside.

  86. Alan Bristow says:

    Wow. I was just thinking what a brilliant add on to many TXP sites and what a shame the list of building tags was not presented in the Admin side when I saw it was — and brilliantly.

    Thanks SO much for this excellent add-on to TXP. Loving it.

  87. Nathan Arthur says:

    Alan – thank you very much for your comments! I’m glad you’re enjoying tru_tags.

  88. jens31 says:

    just wanted to show some love. this plug-in rules. nice with all that tiny little features, all that is really made pro.

  89. Nathan Arthur says:

    jens31 – thank you very much!

  90. Markus Merz says:


    Maybe something like this is better to understand?

    This tag returns the tag (keyword) you are searching for. This way it is possible to render the ‘keyword’ searched for on a ‘tag search result page’ (/tag/keyword). This is generally used with tru_tags_if_tag_search.

  91. Matt says:

    This has to be some of the best textpattern plugin documentation I’ve seen. Fantastic!

  92. Nathan Arthur says:

    Thanks! I’m glad you find it useful.

  93. alan says:

    I’ve recently updated from a somewhat ancient version of tru_tags, and I love the new features. I’ve run into something interesting while addressing an unrelated issue, and I wonder what you think: Though I have clean urls turned on in tru_tags, zem_redirect pro interferes and rewrites all tag urls in the /?=section&tag=etc form. I confirmed this by switching off zem_redirect and checking the tag urls: Nice and clean.

    Do you think there’s any way around this? I’m bewildered by redirects and would gladly ask zem if he were still working in the txp community. Any ideas?

  94. Nathan Arthur says:

    alan –

    Sadly, I can’t do much to help. I don’t really understand how all the clean URL stuff works. There have been many different solutions, and mine is simply the best of the others that I found. I’m not sure what Zem is using, and I don’t have access to his code.

    I also worry because his page says “May not be compatible with custom clean URL plugins and add-ons, or with other URL redirection tools.” That probably means that it won’t work with tru_tags.

  95. alan says:

    Thanks for giving it some investigation, Nathan. The plugin load order in 4.0.7 was a good idea, but didn’t appear to have any affect.

    However, I did have some luck, after a lot of tinkering, with making a small change to the redirect plugin to exclude part of its normal operation when tru_tags is present. I can’t really explain how it works or why it doesn’t [appear to!] break anything, but I tentatively think it may have done the trick. Right now, I have nice and clean tag urls working in conjunction with the redirects. I’m going to try to actually understand what it did — and if I can make sense of it, I’ll post it here or to the forum.

    Thanks again for the help and for a really extraordinary plugin. Cheers!

  96. Alan Bristow says:

    Hi Nathan,

    Weird – I could have sworn I was finding no problems but now I am not seeing the display of tags-available (yellow background) on the Write page.

    I am sure I was seeing this.

    I do have the Extension tab set to display this.

    I have deleted and re-installed tru_tags.

    I am using 4.0.8 RC2, but I was 99% sure I saw the yellow tags before I went from 4.0.7 to 4.0.8 RC2 (but maybe I am wrong there?).

    Any clues, easiest being, do you know if I should be able to see the yellow tag-chooser in 4.0.8 RC2?

    Tags seem to be working fine, just the Admin side display (which is brilliant when working so am sadly missing it).

    Any comment MOST gratefully received.

    Cheers, -Alan

  97. Nathan Arthur says:

    Alan –

    I don’t know of any problem with 4.0.8, although I haven’t tried it myself. There have been a few reports on the forums about this problem, but it’s always been intermittent, and I’ve never been able to figure it out. Sometimes reinstalling the plugin fixes it, but apparently not in your case.

    Would you mind letting me into the admin side of your site to see if I can debug it? If that’s OK, please send credentials to

  98. Matt says:

    Absolutely brilliant. Really professional plugin.

  99. Nathan Arthur says:

    Matt, wow, thanks!

  100. Sergey says:

    Sorry for my english :)
    How i can ?
    On page http://mysite/tag/NNN
    make link
    take NNN as a variable and transfer this in url

  101. Sergey says:

    Sorry, problem solved :)
    <a href=“http://mysite/gallery/main.php/key/<txp:tru_tags_tag_parameter />” target=”_blank”><txp:tru_tags_tag_parameter /> in our gallery </a>

  102. Magnus Berg says:

    Hi Nathan.

    I installed tru_tags 3.5 yesterday on my site and realized that I still miss important things, then it comes to tagging, which should make Txp a real good blog platform for me.

    1. I wrote about it before. To use blogg portals it must be a ‘plus’ sign between two words in tags that have more than one word. Dashes doesn’t work, or work in the way that you will have ha blog portal tag of your own. I use the Swedish blog portal and can only use single word. Here is a description for Technorati tags “Please note that two word tags should be joined by a “+”.”

    2. Sorting the Swedish alphabet doesn’t work correct. Å, Ä and Ö comes last in the Swedish alphabet, but tru_tag sport them first.

    I realize that with my “small” language it is not the best choice to us a CMS with a quite small user base word wide. Anyway, thanks for your work, so far, Nathan.

  103. mave says:

    I’ve used tru_tags before, and I LOVE it. The only problem is, I’m working on a site that needs tagging for different sections in order to function the way I’d like it to. I was thinking that wouldn’t be a problem at all, since the two sections won’t ever need to share the same tag (i.e. If the two sections never share the same tag, then clicking on a tag would never return results from both sections).

    However, I also need the results to display each within their designated section, so the fact that tru_tags works using it’s own section is a limitation for me. I can set that section to display like one of the sections, but then when people from the other section click to list posts for a tag, their results would appear to be displaying in a totally different section.

    For example: section 1 is “Blog”, section 2 is “Testimonials”. I want people to be able to sort blog posts by tag, but I also want the testimonials to be sortable by tag. However, if I set the section page to display like the Blog page (with the sidebar and various section-specific elements in place), then people clicking to sort testimonials will get their results displaying the same way, and think they’ve somehow been redirected to the blog section.

    Any suggestions? I guess I can use categories in the testimonial section, but my greedy self wants to be able to have the functionality and ease of tru_tags in both areas. :^)

  104. Nathan Arthur says:

    Mave, this is a tough problem. After thinking it through for a while, I can’t see a solution that would work with a stock tru_tags, and I can’t think of an easy way to modify tru_tags to support multiple tag sections.

    I can think of a way that you might be able to get it to work, but you’ll have to modify the plugin, and you’ll have to be pretty good with PHP. Specifically, there’s a line near the top of the plugin that says:

    $tru_tags_prefs = tru_tags_load_prefs();

    You could put a new line after that line that says something like:

    $tru_tags_prefs[TAG_SECTION] = (inBlog() ? “blogtags” : “testimonialtags”);

    You’d then have to write the inBlog() function to somehow figure out the user’s current context. I think, then, that you could create the two appropriate sections and tru_tags would handle the rest correctly. But you’d want to test it very thoroughly to be sure.

    I’m very curious to know if you try this, and if it works – please let me know :)

  105. Jean Rajotte says:

    Superb plugin! Thanks.

    Just came across an issue w/ hyphens in tags and I don’t understand from the docs whether there is a solution.

    If a tag has a hyphen (e.g. “photo-electric”), clicking its link generated by tru_tags_cloud or tru_tags_from_article yields a 404 because, basically, I’ve no way to tell tru_tags_handler the equivalent of striphyphens=‘lookup’.

    What am I missing, pretty please?

    Curious: what was the rationale for choosing hyphen as a space replacement, since hyphen is common in natural languages?

    Possibly, a simple solution to alleviate this problem and the need for the striphyphens attribute here, there, but not everywhere, could be to make the space-replacement string a plugin parameter, which authors could be mindful of when introducing new keywords…

  106. Nathan Arthur says:

    Jean –

    Tags with hyphens should “just work” without using striphyphens at all. If you are using striphyphens, try just taking it out and see if that fixes it. If not, I’ll need a more detailed example (feel free to email me directly). I checked my test site, and tags with hypens are working just fine, so I don’t think it’s a bug in the plugin.

    As to the rationale: there isn’t really one. I just didn’t know any better, back when I started tru_tags, and once I did learn better, I didn’t want to break backwards compatibility. I think there might have also been limitations with the way older versions of Textpattern stored keywords, but I can’t remember now.

    Really the only time you should ever need striphyphens is with tru_tags_tag_parameter, if you are planning on displaying the “searched tag” in your search results page. (That’s the common use-case, any way.) I don’t think it should be necessary under most other situations.

  107. Jean Rajotte says:

    p.s. I just implemented a fix in my copy of your source as follows: For every replace() invocation that toggle hyphen/space, I replaced the one hyphen with two hyphens. So the links show “nuclear—non-proliferation” (2 hyphens hard to read here). I don’t see what incompatibility this might introduce… A quick test showed it fixed my issue and didn’t break anything else. I guess this breaks any bookmarks out there, is all.

  108. Caravan wise says:


    I’m just installing your plugin on a local test site before going live. My tag cloud has commas outside of the anchor. Can I get rid of these commas altogether?

    Many thanks


  109. Nathan Arthur says:

    Caravan wise –

    I’m not sure I understand exactly what you are saying, but I’m guessing the “break” attribute on tru_tags_cloud is what you are looking for.

    If that’s not it, please feel free to email me at or post more details over on the forum

  110. Mave says:

    Is there a way to show only the article excerpts in the results of clicking a tag, instead of the entire article? I have listform and form set in my article tag on the page used to display the output, and it totally ignores it and just shows the full article, which means a lot of unnecessary scrolling for the user.

  111. Caravan wise says:

    Hi Mave,

    I have a different form called “search_results” for the tag list and use this code to serve up the correct form.

    <txp:if_section name=“tag”> <txp:tru_tags_handler listform=“search_results” />
    <txp:else />
    <txp:article limit=“1” form=“mainarticle” />

    I use a plugin called rss_auto_excerpt to make an extract limited, in my case to 30 words.

    I hope that this helps. If you want more information Nathan has my email address.



  112. Nathan Arthur says:


    Phil’s method is the right way to do it (for tru_tags). Because of the way textpattern is designed, there’s no (reasonable) way to make “listform” work with tru_tags.

    Thanks, Phil!


  113. Mave says:

    Fab, thanks guys! My heroes! <3

    I know I’ve said it before, but it warrants repeating: tru_tags is awesome. Thanks for the hard work!!

  114. Matthias says:

    Thanks for this great TXP plugin. It’s really the best for tagging at TXP.

  115. melissa says:

    Thanks for the far superior tag system! I’m upgrading from ran_tags and shifted all the tags in my 400+ posts over to the keywords section and have got tru_tags working fine on individual articles, but the tag cloud (or tag list) are ALWAYS empty. Any ideas? There are plenty of tags in the system, as evidenced by the article pages, and the tag pages for each of these are fine, it’s just the cloud that’s empty. :/

    I just using <txp:tru_tags_cloud /> copy/pasted straight from this page… If you’ve got any ideas for troubleshooting, please email me. thanks!

  116. Nathan Arthur says:

    melissa – Did you get this fixed? I see a tag cloud at http://yoursite/tag/, and I see a tag cloud in your left sidebar. Please let me know if you are still having trouble.

  117. melissa says:

    Nathan – yes, I did get it working, thanks! I hadn’t upgraded Textpattern in a few releases so upgrading to 4.3.0 made the Tag Cloud magically work. Might be something to keep in mind for others who are troubleshooting. :)

    (yes, yes, I know, I should always have the latest version! Bad me!)


  118. Nathan Arthur says:

    melissa – What version were you on before your upgrade? tru_tags should work with 4.0.7 or higher, but I haven’t tested it with an old version in a long time. And you’re the first person I know of who upgraded to 4.3.0 (including me), so I’m glad to hear it’s working. Please let me know if you see any problems.

  119. BoJay says:

    Hey Nathan, love your plugin .. and I’m trying to use it as “categories” for a boardgame website. I have 8 categories (strategy, familygame etc) and I’m trying to write a short intro on top of the search-pages telling about the category you have clicked on (followed by the <txp:tru_tags_handler listform=“taglist” />)

    Is there any way for me to know if a search-tag matches a specific string like .. if tru_tags_search_tag tag-name=“wargame” as a container construction ?

    My idea would simply be to make 8 if-statements on the tag section page and output appropriate forms.

    Any thoughts would be greatly appreciated :) Thanks.

  120. Nathan Arthur says:

    BoJay – see tru_tags_if_tag_search, specifically the ‘tag’ attribute :)

  121. BoJay says:

    Hey Nathan,
    I’ve been playing around with the plugin and can’t figure out if I’m trying to use tru_tags for something it’s really not able to. So let me run this by you:

    Subject: Related articles

    Specifically: If you found this article interesting, you may also like this one ..

    I’d like to post a list (thrugh a form) of articles related to the article I’m currently rendering. I’d need the related list to have a limit and a sorting-order plus a section to pick the articles from.

    So in plain english, a random, short list of articles wich has a specific tag and are committed to a specific section. ie. section=“games” .. and I’d like to run that list through a form so I can post the image associated with each item.

    I’m fully aware that one article can have several tags .. but I’m guessing you’re allready doning somthing random .. or I was hoping the random sorting perhaps could come in play.

    Let me know if you think it could be tweaked into such a task. Thanks again for a great plugin .-)

  122. Nathan Arthur says:


    Wow, this is a tricky one. You are right, tru_tags isn’t really designed to provide this feature, but it is a great idea. I think it might be possible, by using tru_tags_archive with the keywords attribute with a carefully constructed version of tru_tags_archive.

    Something like this (totally untested):

    <txp:tru_tags_archive listform=“related_articles” section=“whatever” sort=“whatever” keywords=’<txp:tru_tags_from_article generatelinks=“0” listlimit=“2” />’ />

    Note the single quotes on the keywords paramater (see here for why.

    And I’m not sure if tru_tags_from_article will actually do the right thing with the listlimit attribute; maybe try ‘limit’ if listlimit doesn’t work. And “2” was an arbitrary choice; you might prefer “1”.

    If this works, you’ll need to make the “related_articles” form, to see any output for each article.

  123. jane is ko (jayrope) says:

    Hi Nathan, i am using tru_tags on 4.4.0, works like a charm.
    As I’ve seem to have seen a warning further above about the tag clouds eventually generating server load problems on sites with higher traffic i wonder, if you’d see a way for instance to render tag clouds only once a day/hour and use a sort of stored version of the rendering in the meantime?
    Just a question, much respect to your work.


  124. Nathan Arthur says:


    Thanks for the feedback. For the server load (if you’re seeing a problem), I think aks_cache would probably do exactly what you want.

  125. someone says:

    Tag cloud does not appear.

  126. someone says:

    Finally I got it displayed. Looks like tag font size does not deppend on frequency mention.
    P.S. It is not easy to use (install).

  127. PhilH says:

    Hi Nathan,

    I’ve just installed your Trutags plugin on another blog here This time using Textpattern 4.4.1 and it works perfectly. For those who have difficulty installing the plug-in I have to say that the basic installation is really simple. There are 5 steps as detailed above but they are only little steps and I don’t see how it could be simpler.

    I use it along with Rob Sable’s rss_auto_excerpt plugin which makes pulling an excerpt snippet into the search results for really simple.

    Thanks again for continuing to make this useful plugin available to the Textpattern community.



  128. Melissa says:

    I’m new to Textpattern (coming from WordPress) and I’m confused. Everything works fine. But I’m trying to make it so when you click on a tag in an article, it shows an H1 / H2 tag with the name of said tag followed by the tagged articles on a new page.

    Just kind of stumped trying to show the tag’s name. Everything else works fine.

  129. Nathan Arthur says:


    You should just be able to use tru_tags_tag_parameter ( in an H1 tag. You may want to put that at top of the ‘page’ that renders your tag search results, wrapped in a tru_tags_if_tag_search.

Add a comment

(will not be displayed)

(not required)