Trac Tags
What are tags?
Tags are like hierarchically organized wiki entries, however with them you can categorize a wiki entry under multiple tags and not just under one hierarchy. You can then search for wiki entries categorized under a tag or a collection of tags. In other words, tags provide a faceted classification system for the Trac wiki.
As an added bonus, tags are linked to the wiki entry of the same name, allowing you to describe them explicitly under the wiki entry of the same name. This allows for a flexible means for establishing the context of wiki entries. Besides this, tags also make it incredibly easy to create todo lists or indexes.
Tags don't have to be predefined. As long as there are wiki entries categorized under a tag, it'll be automatically created.
Tags are similar to labels in gmail, tags in the social bookmark manager, del.icio.us and the photo sharing site, Flickr and WikiMedia categories. They are substantially different than the latter because tags are associated with wiki entries of the same name, whereas WikiMedia Categories are just indexes.
This implementation of wiki tagging is specific to Trac. To stay consistent with the way Trac names wiki entries, tags are case sensitive.
Also see the idea's background and improvements being implemented/considered.
Don't forget to check out the examples of tags in action. The excellent Trac Hacks makes extensive use of tagging and is a good example of their use. Also, see http://lists.edgewall.com/archive/trac/2006-April/007646.html for an example of how Alec uses ListTagged to query tickets.
How do I use tags?
Tags are now implemented as a Trac plugin. The installation document describes how you can install tags on your Trac installation.
How do I apply tags?
To create a tag, follow these steps:
- Go to the wiki entry you want to tag.
- Click on Edit This Page
- Under Change information, Tag under:, enter the tags you want to categorize the entry under. Separate the tags by commas. Note that white spaces are currently not supported and will be replaced by commas.
- Click Save changes.
The wiki entry you edit is now categorized under the tags you specified.
How do I remove a tag from a wiki entry?
To remove a tag from a wiki entry
- Go to the wiki entry you want to untag.
- Click on Edit This Page
- Under Change information, Tag under:, remove the tag from the list.
- Click Save changes.
Using the tags
Querying is implemented through the /tags uri handler, the tag:<tag> syntax or Trac Macros as follows
/tags handler
Going to /tags under your project will show a list of all tags in the wiki. /tags/<tag> will show all the objects tagged <tag>. e.g. http://muness.textdriven.com/trac/tags/Java,Examples. This accepts all the parameters that the ListTagged macro does. e.g. http://muness.textdriven.com/trac/tags/Java,Examples?operation=union&amp;showheadings=true.
tagged:<tag> Usage
Using tagged:<tag> will link to the wiki <tag>. If that doesn't exist, it will instead link to a listing of all the objects tagged <tag>.
e.g. tagged:todo or tagged:Java,Examples . This syntax accepts all the options that the ListTagged macro does. e.g. tagged:Java,Examples?operation=union .
Tag expressions
Both the ListTagged macro and the /tags handler use a basic expression language for filtering tagged objects.
Operators supported by the language are:
| Operator | Function |
| + or , | Logical and |
| - | Logical and not |
| unary - | Not |
| | | Logical or |
Sub-expressions can be grouped inside parentheses (, ).
Tags can be quoted with single ' or double '' quotes, in case they contain characters that are operators.
Examples
Intersection of Java and Examples tags:
Union of Java and Examples tags:
Objects tagged Java or Python, and Examples
Macro Usage
ListTagged
[[ListTagged]]List tagged objects. Optionally accepts a list of tags to match against. The special tag . (dot) inserts the current Wiki page name.
[[ListTagged(<tag>, ...)]]
Argument Description tagspace=<tagspace> Specify the tagspace the macro should operate on. tagspaces=(<tagspace>,...) Specify a set of tagspaces the macro should operate on. operation=intersection|union The set operation to perform on the discovered objects. showheadings=true|false List objects under the tagspace they occur in. expression=<expr> Match object tags against the given expression. The supported expression operators are: unary - (not); binary +, - and | (and, and not, or). All values in the expression are treated as tags. Any tag not in the same form as a Python variable must be quoted.
eg. Match all objects tagged with ticket and workflow, and not tagged with wiki or closed.
(ticket+workflow)-(wiki|closed)
If an expression is provided operation is ignored.
ListTags
[[ListTags]]List all tags.
Argument Description tagspace=<tagspace> Specify the tagspace the macro should operate on. tagspaces=(<tagspace>,...) Specify a set of tagspaces the macro should operate on. shownames=true|false Whether to show the objects that tags appear on (long).
TagCloud
[[TagCloud]]This macro displays a tag cloud (weighted list) of all tags.
Argument Description tagspace=<tagspace> Specify the tagspace the macro should operate on. tagspaces=(<tagspace>,...) Specify a set of tagspaces the macro should operate on. smallest=<n> The lower bound of the font size for the tag cloud. biggest=<n> The upper bound of the font size for the tag cloud. showcount=true|false Show the count of objects for each tag? mincount=<n> Hide tags with a count less than <n>.
Note that the macro argument defaults can be customized site-wide. See the installation instructions for details.
See tags/index for a list of all tags defined in this Wiki.
