tru_tags-docs.html

<p>To learn more about tru_tags, check out the <a href="/tag/tru_tags/">other tru_tags articles on this site</a>.</p>

<ul>
	<li><a href="#install">Installation</a></li>
	<li><a href="#config">Configuration</a></li>
	<li><a href="#optconfig">Optional configuration</a>
	<ul>
		<li><a href="#customtitles">Custom page titles</a></li>
		<li><a href="#customRSS">Custom <span class="caps">RSS</span>/Atom</a></li>
		<li><a href="#archivepage">Archive page</a></li>
		<li><a href="#relatedtags">Related-tags cloud</a></li>
		<li><a href="#customadmin">Admin-side tag display</a></li>
		<li><a href="#adminauto">Admin-side tag auto-complete</a></li>
		<li><a href="#ongoingmaint">Tag maintenance</a></li>
		<li><a href="#customsettings">Advanced settings</a></li>
	</ul></li>
	<li><a href="#reference">Tag Reference</a>
	<ul>
		<li><a href="#tru_tags_handler">tru_tags_handler</a></li>
		<li><a href="#tru_tags_if_has_tags">tru_tags_if_has_tags</a></li>
		<li><a href="#tru_tags_from_article">tru_tags_from_article</a></li>
		<li><a href="#tru_tags_cloud">tru_tags_cloud</a></li>
		<li><a href="#tru_tags_cloud">tru_tags_list</a></li>
		<li><a href="#tru_tags_if_tag_search">tru_tags_if_tag_search</a></li>
		<li><a href="#tru_tags_tag_parameter">tru_tags_tag_parameter</a></li>
		<li><a href="#tru_tags_search_result_excerpt">tru_tags_search_result_excerpt</a></li>
		<li><a href="#tru_tags_search_parameter">tru_tags_search_parameter</a></li>
		<li><a href="#tru_tags_related_tags_from_search">tru_tags_related_tags_from_search</a></li>
		<li><a href="#tru_tags_archive">tru_tags_archive</a></li>
		<li><a href="#tru_tags_current_archive_tag">tru_tags_current_archive_tag</a></li>
	</ul></li>
	</ul>

<hr>

<h3 id="install">Installation</h3>

<ol>
	<li>Go to the <a href="/reference/537/tru_tags-releases">releases page</a> to get the latest release.  Don&#8217;t save it &#8211; just open it in your browser.</li>
	<li>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 -&gt; Plugins.</li>
	<li>Hit “Upload”.</li>
	<li><strong>Remember to switch the plugin to “Active” in the plugin list.</strong></li>
</ol>

<hr>

<h3 id="config">Configuration</h3>

<h4>Step 1: Create a new section</h4>

<p>tru_tags depends on the existence of a special Textpattern section named “tag,” by default<sup class="footnote" id="fnrev163861495258b0fde2547e7-1"><a href="#fn163861495258b0fde2547e7-1">1</a></sup>.  Create that section, using whatever settings you like.  (You won&#8217;t be publishing articles to that section.)  Here&#8217;s what I use<sup class="footnote" id="fnrev163861495258b0fde2547e7-2"><a href="#fn163861495258b0fde2547e7-2">2</a></sup>:</p>

<p><txp:image id="2" class="diagram" /></p>

<p class="footnote" id="fn163861495258b0fde2547e7-1"><sup>1</sup> 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-&gt;tru_tags and update the Preferences.  </p>

<p class="footnote" id="fn163861495258b0fde2547e7-2"><sup>2</sup> Note that I use the ‘default’ page &#8211; 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&#8217;ll want a page that has the correct layout/headers/footers.  I use my default page, with <code>&lt;txp:if_section name=&quot;tag&quot;&gt;</code> to change the page display in this case.  </p>

<h4>Step 2: Call the plugin from that section</h4>

<p>To make tag searching and the default tag cloud work, you&#8217;ll need to call <code>&lt;txp:tru_tags_handler /&gt;</code> from the page you chose in Step 1.  I replaced the default <code>&lt;txp:article /&gt;</code> with something like this:</p>

<pre>&lt;txp:if_section name=&quot;tag&quot;&gt;
  &lt;txp:tru_tags_handler /&gt;
&lt;txp:else /&gt;
  &lt;txp:article /&gt;
&lt;/txp:if_section&gt;</pre>

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

<h4>Step 3: Configure your article form to display tags</h4>

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

<pre>&lt;txp:tru_tags_if_has_tags&gt;
  tags: &lt;txp:tru_tags_from_article /&gt;
&lt;/txp:tru_tags_if_has_tags&gt;</pre>

<h4>Step 4: Drop a custom tag cloud somewhere, if you want</h4>

<p>If you&#8217;d like to show a tag cloud somewhere on your site (other than <code>/tag/</code>), put something like this in that page:</p>

<pre>&lt;txp:tru_tags_cloud /&gt;</pre>

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

<h4>Step 5: Start tagging!</h4>

<p>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<sup class="footnote"><a href="#fn163861495258b0fde2547e7-1">1</a></sup>.  </p>

<p>Make sure that your articles are in a section that is configured to be searchable.  <code>tru_tags</code> will filter out articles from sections that aren&#8217;t searchable.  This is a common question on the <a href="http://forum.textpattern.com/viewtopic.php?id=15084">forum</a>.  Please look there first if you are having problems or have any questions &#8211; they are often addressed there.</p>

<p class="footnote" id="fn163861495258b0fde2547e7-1"><sup>1</sup> 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.</p>

<hr>

<h3 id="optconfig">Other optional configuration</h3>

<h4 id="customtitles">Customize your page titles</h4>

<p>You can use <code>tru_tags_if_tag_search</code>, <code>tru_tags_tag_parameter</code>, and <code>txp:search_term</code> 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.  </p>

<p>If you don&#8217;t like the fact that all tags are shown in lowercase you can use <code>”text-transform: capitalize”</code> in your <span class="caps">CSS</span> stylesheet, in conjunction with an appropriate <code>class</code> attribute on your <code>tru_tags_cloud</code> call, to capitalize the tags.</p>

<h4 id="customRSS">Customize your <span class="caps">RSS</span> and Atom feeds</h4>

<p>By default, tru_tags includes article tags in the <span class="caps">RSS</span> and Atom feeds, using standard <span class="caps">XML</span> elements so that Technorati (and others) will discover the tags.  If you don&#8217;t want this behavior you can turn it off by updating the Preferences on the Extensions-&gt;tru_tags tab in the Textpattern admin.  </p>

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

<p>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 <code>rel=&quot;tag&quot;</code>).  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 <span class="caps">RSS</span>/Atom feed(s).  I suggest using something like this:</p>

<pre>&lt;txp:tru_tags_if_has_tags&gt;
&lt;h4&gt;filed under: &lt;txp:tru_tags_from_article /&gt;&lt;/h4&gt;
&lt;/txp:tru_tags_if_has_tags&gt;</pre>

<p><strong>This feature is even more powerful, though.</strong>  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&#8230;” link to the articles, and to include all the user-posted comments in the feed.  I&#8217;m sure there are other uses.  </p>

<p>For reference, my complete tru_tags_feed_tags form contains:</p>

<pre>&lt;txp:if_excerpt&gt;
&lt;p&gt;&lt;txp:permlink&gt;Read more...&lt;/txp:permlink&gt;&lt;/p&gt;
&lt;/txp:if_excerpt&gt;
&lt;h4 class=&quot;tags&quot;&gt;filed under: &lt;txp:tru_tags_from_article /&gt;&lt;/h4&gt;
&lt;/txp:tru_tags_if_has_tags&gt;
&lt;txp:if_comments&gt;
&lt;hr&gt;&lt;h4&gt;Comments:&lt;/h4&gt;
&lt;txp:comments /&gt;
&lt;/txp:if_comments&gt;
&lt;txp:tru_tags_if_has_tags&gt;</pre>

<h4 id="archivepage">Create a tag-based archive page</h4>

<p>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, <a href="/archive/">check out mine</a>.  </p>

<p>Creating a tag-based archive page is very similar to creating a <a href="http://textpattern.com/faq/134/how-do-i-make-an-archive-page">date-based archive page</a>, so this may be easiest if you follow <a href="http://textpattern.com/faq/134/how-do-i-make-an-archive-page">those instructions</a> first, and then convert over to a tag-based archive from there.  Or you might prefer to just follow these instructions:</p>

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

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

<p><txp:image id="28" class="diagram" /></p>

<p><strong>On the page for that section, call <code>tru_tags_archive</code> and set the <code>form</code> attribute.</strong>  For example, you could do this:</p>

<pre>&lt;txp:if_section name=&quot;archive&quot;&gt;
  &lt;h2 class=&quot;article_title&quot;&gt;&lt;a href=&quot;/archive/&quot;&gt;Archives by tag&lt;/a&gt;&lt;/h2&gt;
  &lt;txp:tru_tags_archive form=&quot;tag_archive&quot; /&gt;
&lt;/txp:if_section&gt;</pre>

<p>You&#8217;ll want to set the <code>form</code> attribute to the name of a form you haven&#8217;t created yet &#8211; so make something up that sounds about right (like “tag_archive”).</p>

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

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

<p>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&#8217;t want the header to appear above every article &#8211; you just want it to appear whenever the tag name switches to a new tag.  That&#8217;s where <a href="http://textpattern.net/wiki/index.php?title=Txp:if_different">if_different</a> comes in.  <code>if_different</code> does exactly what we want &#8211; it only renders the header (the tag name) if it is different from the last time <code>if_different</code> was called.  So, that allows us to do something like this:</p>

<pre>&lt;txp:if_different&gt;
  &lt;h2 class=&quot;archive&quot;&gt;&lt;txp:tru_tags_current_archive_tag link=&quot;1&quot; /&gt;&lt;/h2&gt;
&lt;/txp:if_different&gt;
&lt;div class=&quot;archive&quot;&gt;
  &lt;h3&gt;&lt;txp:permlink&gt;&lt;txp:title /&gt;&lt;/txp:permlink&gt;&lt;/h3&gt;
  &lt;h4&gt;~ &lt;txp:posted format=&quot;%b %Y&quot; /&gt;&lt;/h4&gt;
&lt;/div&gt;</pre>

<p>And if everything was done correctly, that&#8217;s it!  You should have a working <a href="/archive/">archive page</a>.</p>

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


<h4 id="relatedtags">Show a “related tags” cloud</h4>

<p>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.  </p>

<p>Got that?</p>

<p>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&#8217;s a way to say “these other tags may be similar to the tag you just searched”.  </p>

<p><strong>Before you use this on your site, however,</strong> 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.</p>

<p>To use it anyway, put something like this into the appropriate page:</p>

<pre>&lt;txp:tru_tags_if_tag_search&gt;
&lt;txp:tru_tags_related_tags_from_search section=&quot;blog,reference&quot; useoverallcounts=&quot;1&quot; /&gt;
&lt;/txp:tru_tags_if_tag_search&gt;</pre>

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

<p>The <code>useroverallcounts</code> attribute causes the cloud to size the links according to how large they would be in the main cloud.  That&#8217;s probably what you want, but it causes even more performance slowdown.  See the documentation below for all the details. </p>

<h4 id="customadmin">Customize the tag display on the admin side</h4>

<p>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.  </p>

<p><txp:image id="13" class="diagram" /></p>

<p>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 <a href="http://textpattern.org/plugins/434/hpw_admincss">hpw_admincss</a> and customize the admin-side <span class="caps">CSS</span> as follows:</p>

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

<h4 id="adminauto">Turn on tag auto-completion on the admin side</h4>

<p>If you have the <a href="http://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/">jQuery Autocomplete plugin</a> installed, tru_tags can auto-complete tag names in the Keywords field on the Write tab.  In order for this to work, the <code>jquery.autocomplete.css</code> and <code>jquery.autocomplete.min.js</code> 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).</p>

<h4 id="ongoingmaint">Ongoing tag maintenance</h4>

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

<p>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 <span class="caps">URL</span>.  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&#8217;t set a Redirect, tru_tags will generate the standard 404 page (unless you have overridden this behavior &#8211; see below).</p>

<h4 id="customsettings">Admin-side settings</h4>

<p>There are a few other settings that you can control on the Extensions-&gt;tru_tags page, if you need them.  </p>

<p>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.</p>

<hr>

<h3 id="reference">Tag reference</h3>

<h4 id="tru_tags_handler"><code>tru_tags_handler</code></h4>

<p>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 <code>doArticles()</code> (in the Textpattern code) to display tag search results, but if no tag was passed in the url it will call <code>tru_tags_cloud</code> instead.</p>

<p>This tag accepts most of the standard <code>txp:article</code> <a href="http://textpattern.net/wiki/index.php?title=Txp:article_/">attributes</a>, which will be applied during the tag search.  Note that <code>tru_tags_handler</code> <strong>does not</strong> support using multiple sections with the <code>section</code> attribute, when doing a tag search.  If multiple sections are passed, none are used.</p>

<p>If a tru_tags_handler is called for a tag that is no longer valid, it will redirect the user to the site&#8217;s default 404 page.  You can override this behavior with the <code>noarticles</code> attribute, which accepts a <span class="caps">URL</span> that it will redirect to, instead.  You can turn off this behavior by setting the <code>404redirect</code> attribute to <code>0</code>.</p>

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

<p>This tag will also accept all of the attributes used by <code>tru_tags_cloud</code>.  See below for details.  </p>

<h4 id="tru_tags_if_has_tags"><code>tru_tags_if_has_tags</code></h4>

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

<h4 id="tru_tags_from_article"><code>tru_tags_from_article</code></h4>

<p>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 (<code>&lt;a href=...&gt;</code>) to the tag search url for that particular tag.  </p>

<h5>Attributes:</h5>

<ul>
	<li><code>wraptag</code>, <code>break</code>, <code>class</code>, and <code>breakclass</code> attributes<sup class="footnote"><a href="#fn163861495258b0fde2547e7-1">1</a></sup>, as defined by Textpattern.</li>
	<li><code>generatelinks=&quot;0&quot;</code> will show the tags without generating links</li>
	<li><code>linkpath</code> can be used to generate tag links that don&#8217;t go to the default location.  For example, setting <code>linkpath=&quot;http://technorati.com/tag/&quot;</code> will cause tru_tags to generate tag links like <code>http://technorati.com/tag/sometag</code>.</li>
	<li><code>linkpathtail</code> can be used to specify a suffix for the <code>linkpath</code>-based link.  For example, setting <code>linkpathtail=&quot;/&quot;</code> will put a “/” on the end of the generated <code>linkpath</code> url.</li>
	<li><code>texttransform</code> 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 <code>lowercase</code>.  You can also set <code>texttransform</code> to <code>capitalize</code> (Like This), <code>uppercase</code> (<span class="caps">LIKE</span> <span class="caps">THIS</span>), or <code>capfirst</code> (Like this).</li>
	<li><code>title</code> can be used to set the tooltip for all the tags.</li>
	<li><code>usenofollow=&quot;1&quot;</code> will turn on <a href="http://googleblog.blogspot.com/2005/01/preventing-comment-spam.html"><code>rel=&quot;nofollow&quot;</code></a> in the links.  This is off by default.</li>
	<li><code>usereltag=&quot;1&quot;</code> (default) will turn on the <a href="http://microformats.org/wiki/reltag"><code>rel=&quot;tag&quot;</code></a> attribute (used by <a href="http://www.technorati.com/">Technorati</a>), <strong>if you are using clean urls</strong>.  Note that this won&#8217;t work if you turn off links.
	<ul>
		<li><strong>Note:</strong> Article tags are included in the <span class="caps">RSS</span> and Atom feeds (by default).</li>
	</ul></li>
	<li><code>useoverallcounts=&quot;1&quot;</code> will tell the tag list to render as a cloud (where each tag is sized according to its site-wide frequency).  This tag isn&#8217;t sufficient on its own, however; once you set it you also need to set the cloud rendering attributes like <code>maxpercent=&quot;200&quot;</code>, <code>setsizes=&quot;1&quot;</code>, and <code>setclasses=&quot;1&quot;</code> because these are all turned off by default.  You&#8217;ll also then be able to use attributes like <code>showcounts</code> and <code>sort</code>.  See the <code>tru_tags_cloud</code> documentation for details on these attributes.
	<ul>
		<li><strong>Be careful, however,</strong> before turning this on.  This attribute causes <code>tru_tags</code> 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.</li>
	</ul></li>
	</ul>

<p class="footnote" id="fn163861495258b0fde2547e7-1"><sup>1</sup> As with all Textpattern tags, <code>class</code> is only used if you specify an appropriate <code>wraptag</code> and <code>breakclass</code> is only used if you specify an appropriate <code>break</code>.</p>

<h4 id="tru_tags_cloud"><code>tru_tags_cloud</code></h4>

<h4><code>tru_tags_list</code></h4>

<p><code>tru_tags_cloud</code> 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 <code>tru_tags_from_article</code>, but with a <code>style</code> attribute set on each link to give it a font size ranging from 100% to 200%.</p>

<p><code>tru_tags_list</code> 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%.</p>

<p>These two tags do the exact same thing &#8211; <code>tru_tags_cloud</code> just provides different defaults to <code>tru_tags_list</code>.  </p>

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

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

<p>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 <code>tagActive</code> (by default), or to whatever you set in the <code>activeclass</code> attribute.</p>

<p>If you use these classes to create special <span class="caps">CSS</span> rules, you may also want to set the <code>setsizes</code> attribute, described below.</p>

<h5>Attributes:</h5>

<ul>
	<li><code>wraptag</code>, <code>break</code>, <code>class</code>, and <code>breakclass</code> attributes, as defined by Textpattern.  <code>tru_tags_cloud</code> has a default <code>break</code> of a comma.  <code>tru_tags_list</code> has a default <code>wraptag</code> of <code>ul</code> and a default <code>break</code> of <code>li</code>.</li>
	<li><code>activeclass</code> can be used to specify the class that should be given to the tag currently under search, on a tag search page.</li>
	<li><code>countwrapchars</code>, which controls the characters used to show the tag count, if <code>showcounts</code> is turned on.  By default this is <code>[]</code>.  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 <code>countwrapchars=&quot;()&quot;</code> would show: <span class="pre"><a href="/?s=tag&amp;t=life">life</a> (3), <a href="/?s=tag&amp;t=tech">tech</a> (5)</span></li>
	<li><code>excludesection</code> 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 <code>section</code> attribute, below, which is used to limit the tags to those from a specific set of sections.</li>
	<li><code>filtersearch=&quot;0&quot;</code> 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 <code>excludesection</code> attribute to exclude specific sections from the cloud.</li>
	<li><code>generatelinks=&quot;0&quot;</code> will show the tags without generating links</li>
	<li><code>linkpath=&quot;http://technorati.com/tag/&quot;</code> will cause tru_tags to generate tag links like <code>http://technorati.com/tag/sometag</code>.</li>
	<li><code>linkpathtail</code> can be used to specify a suffix for the <code>linkpath</code>-based link.  For example, setting <code>linkpathtail=&quot;/&quot;</code> will put a “/” on the end of the generated <code>linkpath</code> url.</li>
	<li><code>listlimit</code> 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 <code>listlimit=&quot;10&quot;</code> 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&#8217;t able to fit the last set of 8 into the limit of 10.  This behavior can be changed with the following attributes:
	<ul>
		<li><code>cutoff=&quot;exact&quot;</code> will tell <code>listlimit</code> to show exactly the number of tags you specify.</li>
		<li><code>keep=&quot;random&quot;</code> will tell <code>listlimit</code> to keep a random set of tags, but tags with a higher frequency have a better chance of being included.</li>
		<li><code>keep=&quot;alpha&quot;</code> will simply sort the tags alphabetically and keep the ones that come first in the list.</li>
		<li><strong>Note:</strong> setting <code>keep</code> (to anything) will automatically set <code>cutoff=&quot;exact&quot;</code>.</li>
	</ul></li>
	<li><code>minpercent</code> and <code>maxpercent</code>, which can be used to control the weighted font sizes in the tag cloud/list.  <code>tru_tags_cloud</code> defaults to <code>100</code> and <code>200</code>, respectively, and <code>tru_tags_list</code> defaults to <code>100</code> and <code>100</code>.</li>
	<li><code>mintagcount</code> and <code>maxtagcount</code> can be used to hide tags that only have a few articles, or that have too many.  They are defaulted to <code>0</code> and <code>1000</code>, respectively.  For example, <code>mintagcount=&quot;2&quot;</code> 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 <code>/tag/</code>.</li>
	<li><code>section</code>, which tells it to limit the list to tags from the given section or sections.  For example, <code>&lt;txp:tru_tags_cloud section=&quot;blog,reference&quot; /&gt;</code> would only show tags from the “blog” and “reference” sections.  By default, this is set to blank (to show tags from all sections).
	<ul>
		<li><strong>Note:</strong> if you use <code>section</code> to limit the cloud to a particular section, it won&#8217;t limit the tag search feature to that section.  The tag search finds (tagged) articles from all sections, no matter what.  That&#8217;s a side-effect of the use of <code>doArticles()</code>, and I don&#8217;t think there&#8217;s anything I can do about it.</li>
	</ul></li>
	<li><code>setclasses=&quot;0&quot;</code> will turn off the default <code>class</code> attributes.</li>
	<li><code>setsizes=&quot;0&quot;</code> will turn off the default font sizing so you can control the sizes yourself (through <span class="caps">CSS</span>).  It will leave behind the default <span class="caps">CSS</span> classes, which you can use to control the display of your cloud.</li>
	<li><code>showcounts=&quot;1&quot;</code> 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: <span class="pre"><a href="/?s=tag&amp;t=life">life</a> [3], <a href="/?s=tag&amp;t=tech">tech</a> [5]</span> in my tag cloud, if this was turned on.  This is off by default.
	<ul>
		<li>This can also be used to put the counts in the <code>title</code> attribute of the links, which will make it appear in a tooltip.  Use <code>showcounts=&quot;title&quot;</code> or <code>showcounts=&quot;both&quot;</code> (to show it in both places) to turn it on.</li>
	</ul></li>
	<li><code>sort</code> can be used to sort the cloud by tag frequency, rather than the default of alphabetically.  Use <code>sort=&quot;count&quot;</code> to sort by frequency in descending order, and <code>sort=&quot;count asc&quot;</code> to sort by frequency in ascending order.</li>
	<li><code>texttransform</code> 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 <code>lowercase</code>.  You can also set <code>texttransform</code> to <code>capitalize</code> (Like This), <code>uppercase</code> (<span class="caps">LIKE</span> <span class="caps">THIS</span>), or <code>capfirst</code> (Like this).</li>
	<li><code>title</code> can be used to set the tooltip for all the tags.</li>
	<li><code>usenofollow=&quot;1&quot;</code> will turn on <a href="http://googleblog.blogspot.com/2005/01/preventing-comment-spam.html"><code>rel=&quot;nofollow&quot;</code></a> in the links.  This is off by default.</li>
</ul>

<ul>
	<li><code>usereltag=&quot;1&quot;</code> will turn on the <a href="http://microformats.org/wiki/reltag"><code>rel=&quot;tag&quot;</code></a> attribute (used by <a href="http://www.technorati.com/">Technorati</a>), <strong>if you are using clean urls</strong>.  Note that this won&#8217;t work if you turn off links.  Note that this is off by default in <code>tru_tags_cloud</code> and <code>tru_tags_list</code>.
	<ul>
		<li><strong>Note:</strong> Article tags are included in the <span class="caps">RSS</span> and Atom feeds (by default).</li>
	</ul></li>
	</ul>

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

<h4 id="tru_tags_if_tag_search"><code>tru_tags_if_tag_search</code></h4>

<p>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.  </p>

<h5>Attributes:</h5>

<ul>
	<li><code>tag</code> will let you check if the search is for a specific tag (like tag=“tru_tags”)</li>
</ul>

<h4 id="tru_tags_tag_parameter"><code>tru_tags_tag_parameter</code></h4>

<p>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 <code>tru_tags_if_tag_search</code>.</p>

<h5>Attributes:</h5>

<ul>
	<li><code>striphyphens=&quot;1&quot;</code> will convert all hyphens to spaces in tag names.  This is useful because <code>tru_tags</code> 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.</li>
	<li><code>striphyphens=&quot;lookup&quot;</code> 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&#8217;t configured this way by default.</li>
	<li><code>urlencode=&quot;1&quot;</code> will url-encode the tag name, so you can embed it in a link.</li>
</ul>

<h4 id="tru_tags_search_result_excerpt"><code>tru_tags_search_result_excerpt</code></h4>

<p>This tag works exactly like <a href="http://textpattern.net/wiki/index.php?title=search_result_excerpt">search_result_excerpt</a>, except that <code>search_result_excerpt</code> doesn&#8217;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 <code>search_result_excerpt</code>, even for regular (non-tru_tags) searches.</p>

<h5>Attributes:</h5>

<p>This tag supports all the attributes of <a href="http://textpattern.net/wiki/index.php?title=search_result_excerpt">search_result_excerpt</a>.</p>

<h4 id="tru_tags_search_parameter"><code>tru_tags_search_parameter</code></h4>

<p><strong>This tag is deprecated.</strong>  Please use <a href="http://textpattern.net/wiki/index.php?title=Txp:search_term_/">txp:search_term</a> instead.</p>

<p>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.</p>

<h4 id="tru_tags_related_tags_from_search"><code>tru_tags_related_tags_from_search</code></h4>

<p>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:</p>

<ol>
	<li>money, health, life</li>
	<li>money, politics, life</li>
	<li>life</li>
</ol>

<p>&#8230;<code>tru_tags_related_tags_from_search</code> would generate a cloud containing “money”, “health”, and “politics”.</p>

<p>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.</p>

<p><strong>Before you use this on your site, however,</strong> be warned that it&#8217;s not good for your site&#8217;s performance, and it&#8217;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.  </p>

<p>You may want to test this carefully if you have a hosting provider who charges you for <span class="caps">CPU</span> cycles.  :)</p>

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

<h5>Attributes:</h5>

<ul>
	<li>All the attributes of <code>txp:article</code></li>
	<li>All the attributes of <code>tru_tags_cloud</code> / <code>tru_tags_list</code>.</li>
	<li><code>useoverallcounts</code>, which makes the cloud render using the frequency data for the site-wide tag cloud.
	<ul>
		<li>By default, <code>tru_tags_related_tags_from_search</code> outputs a cloud where the weights are based on the frequency of the tags <em>in the search results</em>.  Using the example from above, “money” would have a weight that was double the weight of “health” and “politics”.</li>
		<li>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.</li>
		<li>It will also add an extra database query to the mix (mentioned above), so consider performance carefully before using it.</li>
	</ul></li>
	<li><code>tag_parameter</code>, 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 <a href="http://textpattern.com/weblog/318/tag-parser-part-1#attribute-parsing">attribute parsing</a> features in 4.0.7.</li>
</ul>

<h4 id="tru_tags_archive"><code>tru_tags_archive</code></h4>

<p>This tag allows you to create a tag-based archive page (like <a href="/archive/">this one</a>).  It accepts all the attributes that <a href="http://textpattern.net/wiki/index.php?title=Txp:article_/">txp:article</a> accepts.  Your best bet is to <a href="#archivepage">follow the instructions</a>.</p>

<h4 id="tru_tags_current_archive_tag"><code>tru_tags_current_archive_tag</code></h4>

<p>This tag is only useful in concert with <code>tru_tags_archive</code>.  Using <a href="#archivepage">these instructions</a>, you can make a site-wide tag-based archive page (like <a href="/archive/">this one</a>).  </p>

<p>This tag outputs the name of each tag as it is rendered by <code>tru_tags_archive</code>.  It is meant to be used with <code>if_different</code> (a core <span class="caps">TXP</span> function) to generate headings for the archive page.  </p>

<p>This tag only accepts one attribute:</p>

<ul>
	<li><code>link</code>, which will render the tag name as a link.  By default, tag names are only output as text.</li>
</ul>