filed under: geek, tagging, textpattern, tru_tags

Posted Nov 10, 10:11 PM

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

• Installation
• Configuration
• Optional configuration
  • Custom page titles
  • Custom RSS/Atom
  • Archive page
  • Related-tags cloud
  • Admin-side tag display
  • Tag maintenance
  • Advanced settings
• Tag Reference
  • tru_tags_handler
  • tru_tags_if_has_tags
  • tru_tags_from_article
  • tru_tags_cloud
  • tru_tags_list
  • tru_tags_if_tag_search
  • tru_tags_tag_parameter
  • tru_tags_search_parameter
  • tru_tags_related_tags_from_search
  • tru_tags_archive
  • tru_tags_current_archive_tag

---

Installation

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.

---

Configuration

Step 1: Create a new section

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

¹ 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.

² 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 />
</txp:if_section>

Note that tru_tags_handler uses the default “search_form” form for rendering its output, or you can override this with the listform 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:

<txp:tru_tags_if_has_tags>
  tags: <txp:tru_tags_from_article />
</txp:tru_tags_if_has_tags>

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 spaces¹.

You’ll probably want to install Rob Sable’s rss_admin_show_adv_opts, which will automatically expand the “Advanced Options” section of the “Write” page, when you are writing articles. That gives you easy access to the Keywords field.

¹ 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:

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

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:

<txp:if_excerpt>
<p><txp:permlink>Read more...</txp:permlink></p>
</txp:if_excerpt>
<h4 class="tags">filed under: <txp:tru_tags_from_article /></h4>
</txp:tru_tags_if_has_tags>
<txp:if_comments>
<hr><h4>Comments:</h4>
<txp:comments />
</txp:if_comments>
<txp:tru_tags_if_has_tags>

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 listform), 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:

On the page for that section, call tru_tags_archive and set the listform 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 listform="tag_archive" />
</txp:if_section>

You’ll want to set the listform 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 listform). 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 listform).

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:

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

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_if_tag_search>
<txp:tru_tags_related_tags_from_search section="blog,reference" useoverallcounts="1" />
</txp:tru_tags_if_tag_search>

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 */
}

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

tru_tags_handler

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.

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.

tru_tags_if_has_tags

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

tru_tags_from_article

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.

Attributes:

• wraptag, break, class, and breakclass attributes¹, 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="http://technorati.com/tag/" will cause tru_tags to generate tag links like http://technorati.com/tag/sometag.
• 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.

¹ 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

tru_tags_list

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.

Attributes:

• 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="http://technorati.com/tag/" will cause tru_tags to generate tag links like http://technorati.com/tag/sometag.
• 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.

tru_tags_if_tag_search

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.

Attributes:

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

tru_tags_tag_parameter

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.

Attributes:

• 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.

tru_tags_search_parameter

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.

tru_tags_related_tags_from_search

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.

Attributes:

• 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, once attribute parsing is released (in 4.0.7), will let you show a list of related tags for any arbitrary tag. This is meant to be used on your tag-based archive page (documented above) to show related tags for each tag on the archive page.

tru_tags_archive

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.

tru_tags_current_archive_tag