Technology and Lent

filed under: , , , , , , , , , , , , , , , , ,

1462 days ago

This website

The plugin that provided the email notification feature for this website broke with a recent update to my blog software, and it’s not going to be easy to fix. So I’m not going to fix it.

Of course, that means that the affected people aren’t going to hear that they’re affected. Sorry about that! (I’ll tell personally the few I know.)

In fact, I’m likely to switch to ikiwiki …eventually. Textpattern seems to have lost its mojo, and there have been some long-standing issues with it (like no native tagging support!) that seem unlikely to ever get fixed. And I’m hip to the cool technologies now, so a more infrastructure-like framework (i.e. ikiwiki, with git) for my blog feels like a better answer. And schmonz volunteered to do most of the work :)

That also means I’ll probably abandon tru_tags …more than I already have. There hasn’t been anything to do with it in a long while, at least not that I felt was worthwhile to be done. Most of the features that remain to be implemented require a major refactoring of the core Textpattern code, and that just seems very unlikely to happen (by me or anybody else) any time soon. So hopefully it will remain useful to the people who still use it.

This year’s Lent

I have utterly failed at this year’s Lent give-up. I have been better at going to bed at a reasonable hour, sometimes for days at a time. But I simply can’t do everything I need/want to do in my life with the few hours that leaves me between work, kids, and chores. So sleep will continue to lose to projects – although less-so than it used to. There are some nice perks to getting more sleep – I’m much more on-the-ball and willing to take on mental tasks that otherwise seem hard. But that extra value doesn’t offset the lost value from just not being able to do all the things I need to do.


Speaking of Lent, I also broke a 5-year streak of vegetarianism a week or so ago. Benjamin, Liam, and I had some extremely delicious tilapia, also breaking both boys’ life-long vegetarian streaks. Kristina chose not to participate.

We had a bunch of reasons for deciding to do it. And a bunch of reasons to not do it (i.e. to stay vegetarian). I may blog about all the tradeoffs some day soon, but for now, suffice it to say that it was a very close decision, and I’m not sure what’s next.

I made a web app!

If you recall, I started using SmugMug for my online gallery a few years ago. But when I made the switch, I left behind an old gallery site (on Menalto Gallery 1) that I’ve been meaning to clean up for a long time. It broke a while ago, motivating me to finally migrate off that old software – to ZenPhoto, which had been my long-standing plan. It took a few days getting ZenPhoto to work (when it should have been easy!), but I got it there, and I shut off the old site.

I also started this exchange with the ZenPhoto dev in which I start by being too grumpy and then he finished by insisting that his software simply must be unsupportable for him to support it. Net effect: I had to get off ZenPhoto.

But I had no alternate destination for self-hosting my images. My long-term goal is to migrate the images to SmugMug, but I want to filter them down from “every picture I took during that time period” to “just the best ones, tagged and rated” (like all the other pictures I post to SmugMug). And it will take Nathan-weeks of work to get that done, so it keeps getting put off. So in the short term I just needed a new self-hosting product, and there just aren’t any good alternatives. They’re all either old or ugly or badly designed or some combination of those three.

So I made one myself. I’ve never made a web app from scratch before, but I am quite comfortable in perl, had used Catalyst from a prior job, and I’d heard then that Mojolicious is better. So I tried it.

And wow, was it easy. Probably 8 hours total from “install mojolicious” to “the gallery is up and running on the new software”. That’s only just a little more than I spent trying to get ZenPhoto to work. Many kudos to Mojolicious, perl, and pkgsrc.

Now… ZenPhoto does way more stuff. (TONS more… too much, actually.) And this new software isn’t really ready for someone else to use it. And it has no tests. And it only does one extremely simple thing (i.e. serve nested directories of images, in name-sorted order, with no metadata).

But the code is small, easy to read, and easy to modify. (Roughly 300 lines of code, 115 lines of CSS, and 80 lines of HTML template.) The site looks really good (in my opinion). And it doesn’t require a database – just a directory full of images. And with some app-level caching and the help of Mojolicious’s preforking web server and great documentation for setting it up under apache mod_proxy, it’s about as fast is it could possibly be on my old host and slow network connection.

So ZenPhoto is out and my home-grown software is in. Here’s hoping it doesn’t need maintenance!

Add a comment [1]

New "archive" page

filed under: , , , ,

3219 days ago

I’m working on the next version of tru_tags and one of its major features is the ability to create a tag-based archive page, like this one. After implementing the feature, I tried it out, and I liked it so much that I decided to use it on this site. Specifically, I removed the old “About” page, merged some of that content into the “Links” page (and generally edited that page), and put the “Archive” page in where the About page used to be.

This should all make sense if you look at the menu links at the top of the site. For those of you reading this via the feed – click here to see it.

It’s a really interesting page to browse through – I find it strangely fascinating to see so clearly all the articles I’ve written, and how they clump together. I’ve also used it a few times as a faster way to get to a specific page. It’s somehow more powerful than the normal tag cloud, functionally and emotionally, and that surprises me.

Or maybe it’s just late :)

Add a comment [3]

tru_tags: Releases

filed under: , , ,

3426 days ago

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

Current Release

tru_tags 3.7 (for TXP 4.0.7 and above (including 4.2.0)) (download)

Forum announcement

This release includes two major things:

  1. a change to the way URLs are encode for “tags with spaces” and “tags-with-hyphens” and “tags+with+plusses” and “tags that-mix+them”. See this commit message for a great explanation of the problem and the fix.
  2. a performance improvement as suggested by whocarez on the forums


tru_tags: Usage instructions

filed under: , , ,

3426 days ago

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.

Add a comment [129]

tru_tags: Feature list

filed under: , , ,

3426 days ago

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

Core features

  • Tag any article with an unlimited number of tags
  • List all the tags associated with an article
  • Generate a tag cloud or simple tag list
  • Search for all articles tagged with a given tag
  • Clean URLs and rel="tag" support without mod_rewrite or .htaccess modifications
  • RSS and Atom support
  • Support for creating a tag-based archive page
  • Clickable list of tags in the ‘Write’ page of the Textpattern admin
  • Admin-side configurability
  • Admin-side tag maintenance and redirection tools
  • Tag links can go to external sites or alternate locations
  • Show a cloud of “related tags” in the search results page
  • Tag-based archive pages (like this one)
  • Designed with site security in mind
  • Clean, readable code

Advanced features

Adding tags to an article:

  • Tags can be multi-word, with spaces. (use commas to separate tags)

Listing tags for an article:

  • Supports standard textpattern attributes like wraptag / break / class / etc. (the default break is a comma)
  • Don’t have to generate links when showing tags
  • Can render article tags as a mini-cloud, including sorting and advanced cloud features

Tag cloud:

  • Supports standard textpattern attributes like wraptag / break / class / etc. (the default break is a comma)
  • Can filter a cloud to only show tags from specific sections
  • Can exclude specific sections from the cloud
  • Cloud automatically filters out future-dated articles and non-published articles
  • Uses percentages for font sizes, so the cloud can be in any container, with fonts of any specified size
  • Can specify min and max percentage sizes
  • Can show the number of times a tag has been used, after the link or in the title attribute
  • Don’t have to generate links when showing tags
  • Tags have the class attribute set in various ways, so you can take complete control over tag styling
  • Infrequently (or frequently) used tags can be hidden
  • Can sort the cloud by tag frequency (ascending or descending)
  • Can limit the cloud to a max of ‘N’ tags, with the ability to keep only the most-used tags or a random set (weighted by frequency)

Tag search:

  • Site admins can put the name of the tag currently being searched into titlebars or links to external sites (this is careful about scripting attacks)
  • A handy txp tag (tru_tags_search_parameter) to return whatever the user typed into Textpattern’s search field (this is careful about scripting attacks)
  • Renders search results just like the standard article list does. This means you have complete control over the tag search output formatting, and that it supports standard features like article excerpts, override forms, etc.
  • Customizable support for standard 404 pages

RSS / Atom feeds:

  • Includes article tags in the RSS and Atom feeds (which means that Technorati will correctly identify articles)
  • Can include article tags in the feed body
  • Can customise the feed body to change the look of the tags, and/or to add extra items to the feed


  • A few fancy javascript tricks to make it easy to use
  • List can be turned off or styled using CSS (and another plugin) if there are too many tags

Known issues (in the latest release)

  • tru_tags must use the Keywords field, and cannot use a custom field
  • No support for multiple tags at once (e.g. “life AND books”) tag search (but see this post for possibilities)
  • The tag cloud can be limited to just show tags from one section, but when you click a tag link from the cloud it shows articles from all sections
  • The tag search doesn’t support pagination. (It will show all the articles associated with a particular tag, no matter how many there are.)

Add a comment [9]

tru_tags: Roadmap

filed under: , , ,

3426 days ago

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

This post contains an up-to-date list of all the (as-yet-unimplemented) feature requests that I’m aware of, with a rough indication of the order that I plan to implement them. If you have additional feature requests or want to suggest reprioritization of one of the features below, please add a post to the forum thread for this plugin. I’ll see it and update this page, and others will see the request also.

Group 1

  • Fix txp:older and txp:newer, and the broken limit attribute
  • Make txp:page_url work with tru_tags clean urls (see the forum post)
  • Add texttransform="capfirst" to tru_tags_tag_parameter (see forum post)
  • Make it possible to show a tag list in a popup (option/value) (see forum post)

Group 2

  • Limit cloud to tags from X recent articles, or within X time period
    • Order list by (oldest? newest?) article date
  • Color tags by age (of most recent article)

Group 3

  • Related article list (for a single article), based on number-of-matching-tags
    • Filter by section / category
    • Second-level sorting by date?
  • Limit cloud to a specific category

Group 4

  • Multi-tag search (tag1 + tag2)
    • General boolean logic ((tag1 or tag2) and tag3)

Group 5

  • Grouped index of tags – by section, category, alphabetical, etc
    • show articles for each tag?
    • single page per group
    • show tags (on the admin side) based on the category/section chosen
    • see Markus’s forum post about it
  • Grouping related keywords (admin-side)
  • Grouped-tag search (public side)
  • Color tags by category / section

Group 6

  • Move admin-side tag cloud to a better location (for big clouds)
  • Auto-complete typing in the Keywords field (admin-side)

Group “eventually”

  • mintagcount / maxtagcount, but based on percentages
  • Show a “related” cloud for general search-result pages (or other custom-generated article lists)
  • “There are [x] posts tagged: [tag_name]”
  • Alphabetical listing of articles in tag search result
  • Figure out Markus’s ideas about tagging, from the “Pivot” site (see forum post)
  • Sub-tags

Group “depends on the next release of Textpattern”

  • RSS feeds for individual tags

tru_tags is semi-official!

filed under: , ,

3793 days ago

I’m proud to say that tru_tags is the tagging plugin of choice over on Textpattern Resources v2 (a.k.a. That makes it the preferred tag plugin of at least one of the Textpattern developers, and puts it in the spotlight on an official Textpattern site.

Check out the gorgeous tag cloud and the post describing the use of tru_tags.


Add a comment [3]

Massive (paid-for!) update to tru_tags

filed under: , , ,

3910 days ago

I’m pleased to announce the public release of tru_tags v1.8, sponsored by Simon Finch, a consultant / web developer in the U.K.

This release of tru_tags contains two new features: a new type of tag cloud and the ability for article tags to render as a mini-cloud. I also massively refactored and condensed the code, making it much easier to read/understand and hopefully much easier to maintain.

The first new feature can be seen by clicking one of the links in my tag cloud (over in the sidebar). On the resulting page, you’ll see that a second cloud appears (in the sidebar) under the heading “Related Tags”. It is showing you all the tags that are related to the tag you clicked on.

I mentioned that this version was sponsored by Simon Finch, and it’s true – he paid for these specific features, because he needed them for a consulting project he was working on. That has me excited in all sorts of ways:

  1. My plugin is being used in the real world (in an online store!)
  2. Work that I originally did for my own benefit is now helping others
  3. I’m earning income that is derived from that original work
  4. I’m earning income from open-source software!

As usual, you can download this version from the announcement page and you can find out how to use it on the instructions page.

(For those of you waiting for other features, they’ll be coming soon in a v1.9. I wanted to get v1.8 out the door with just the features for Simon, so I’ve had to delay the rest of these.)

Thanks, Simon!

Add a comment [1]

tru_tags: A tagging plugin for Textpattern

filed under: , , , ,

4042 days ago

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.


Add a comment [46]