Contents
A Tagging System for Trac
Description
This plugin implements both a generic tagging engine and front ends for the Wiki and ticket systems. An extra text entry box is added to the Wiki edit page for tagging Wiki pages, and ticket fields (you can configure which ones) are treated as tags for the ticket system.
This plugin was originally created by Muness Alrubaie, but has since been completely rewritten by Alec Thomas, and now maintained by hasienda. Some other plugins that may fit well and complement your TagsPlugin installation:
- KeywordReplacePlugin Replace keywords with their associated values
- KeywordSuggestPlugin Autocomplete feature for the Keywords field
- LoomingCloudsPlugin Display a tag cloud with a ticket
- QuickTicketPlugin Quickly add a ticket from any page
- TracKeywordsPlugin Add ticket keywords from a configured list
Some of these plugins are also described here.
What are tags?
Tags allow you to organize wiki entries under multiple categories, 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 will be automatically created.
Tags are similar to labels in Gmail, tags in the social bookmark manager del.icio.us and Flickr. They are substantially different from Wikipedia categories, 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 that Trac names wiki entries, tags are case sensitive. This site itself makes extensive use of tagging and is a good example of their use, as it allows for data quality of the wiki pages as well as ticket triage.
Example of tags on a wiki page
Usage
Create and 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 tags with spaces.
- Click Save changes.
The wiki entry you edit is now categorized under the tags you specified.
The tagging process for tickets is similar, and can be found under the keywords
field.
Remove tags
To remove a tag from a wiki entry, follow these steps:
- 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.
The tag removal process for tickets is similar, and can be found under the keywords
field.
Search tags
Querying is implemented through the /tags
uri handler, the tag:<tag>
syntax or WikiMacros as follows.
Tags query
Both the ListTagged
macro and the /tags
handler use a basic query language for filtering tagged objects. Query contains the terms to filter, can have some logical operators and have restrictions for where to search:
- Space-separated terms logically
AND
s them together. - Sub-expressions can be grouped inside parentheses
(
,)
. - Expressions and individual tags can be quoted with single
'
or double"
quotes (#3624). - Operators supported by the query language are:
Operator | Function |
or | Logical or
|
not | Logical not
|
realm:<realm> | Restrict to tags in <realm> where realm is wiki , ticket , etc.
|
- Examples
-
- Intersection of
macro
andplugin
tags:tagged:"macro plugin"
- Union of
macro
andplugin
tags:tagged:"macro or plugin"
- Objects tagged
macro
orplugin
, andexample
:tagged:"(macro or plugin) example"
- Intersection of
/tags handler
Going to /tags under your project will show a list of all tags in the wiki. /tags/?q=<query>
will show all the objects matching <query>, eg tags/. This accepts all the parameters that the ListTagged macro does, eg tags.
tag:<tag>
or tagged:<query>
Both forms are identical and link to the tag search results for the query.
- Example
-
tagged:todo
ortagged:"plugin macro"
.
ListTagged macro
This will display a list of resources whose tags match <query>
.
- v0.6:
[[ListTagged([realm:<realm> ]<query>)]]
- v0.7:
[[ListTagged([realm:<realm> ]<query>[,format=...][,cols=...])]]
Argument | Version | Description & Details | Default |
realm:<realm> | 0.6 | Optional. Restrict tags search to a specific <realm> where <realm> is wiki or ticket (accepts only one realm). | realm:ticket
|
<query> | 0.6 | Displays a list of resources of which the tags match <query> | None
|
format | 0.7 | Rendering Option. oldlist or short list in known ListTagged style; compact - list with results shortend to just the description; table - table view similar to TicketQuery with 'table' option | short
|
cols | 0.7 | Rendering Option. A pipe (| ) separated list of columns to show when used format=table option. Available options are:* realm - identifies to which realm the resource is (wiki or ticket);* id - shows the name of the wiki page (if resource is a wiki) or ticket number (if resource is a ticket); * description - first title (if resource is a wiki) or ticket summary (if resource is a ticket);* tags - all applied tags for such resource | cols=id|description|tags
|
- Examples
-
- Intersection of
macro
andplugin
tags:[[ListTagged(macro plugin)]]
- All resources tagged
macro
but notplugin
:[[ListTagged(macro -plugin)]]
- Tickets tagged with
macro
:[[ListTagged(realm:ticket macro)]]
- Pages tagged with
macro
:[[ListTagged(realm:wiki macro)]]
- Intersection of
TagCloud macro
[[TagCloud]]
Display a cloud of all tags. Optional keyword arguments:
- caseless_sort
- Whether the tag cloud should be sorted case-sensitive.
- mincount
- Optional integer threshold to hide tags with smaller count.
Optional query expressions including realm selection are supported as shown for ListTagged
. Between v0.6 and v0.7 something like [[TagCloud(-Dummy)]]
was strictly required as work-around, assuming you did not use the Dummy tag.
Bugs/Feature Requests
Existing bugs and feature requests for TagsPlugin are here.
If you have any issues, create a new ticket.
defect |
156 / 157 |
||
---|---|---|---|
enhancement |
51 / 67 |
||
task |
6 / 6 |
Download
You can download the zipped source from here.
The plugin is also released on PyPi.
Source
You can check out TagsPlugin from here using Subversion, or browse the source with Trac.
Installation
General instructions on installing Trac plugins can be found on the TracPlugins page.
- For Trac 1.2 use tags/0.11
- For Trac 1.4 use tags/0.12
- For Trac 1.5/1.6 use trunk
Note before upgrading: older TagsPlugin configuration must be removed. In particular, trac.wiki.web_ui.wikimodule = disabled
and default_handler = TagsWikiModule
.
Steps to install and configure this plugin:
- Install
$ pip install TracTags
- Configure
- Tags v0.6 has two options under the
[tags]
section of your TracIni file (../conf/trac.ini
):ignore_closed_tickets = <bool>
- Whether to gather tags from closed tickets.
ticket_fields = <field>[, <field> ...]
- Ticket fields from which to gather tags. Defaults to
keywords
. Custom fields are currently not supported.
- Ticket fields from which to gather tags. Defaults to
- Example:
[tags] ignore_closed_tickets = true ticket_fields = component, keywords, milestone
- For v0.7, after install see the TracIni page for the available configuration options.
- In particular, to alter the following list of realms enable the tag change records (default: wiki-only as shown here):
[tags] revisable_realms = wiki
- In particular, to alter the following list of realms enable the tag change records (default: wiki-only as shown here):
- Tags v0.6 has two options under the
- Enable plugin by updating your TracIni file with:
[components] tractags.* = enabled
- Run on your Trac environment:
$ trac-admin <env> upgrade
- Restart web server:
$ sudo /etc/init.d/apache2 restart
- Grant
TAGS_VIEW
andTAGS_MODIFY
permissions to your users according to the policies that you like to implement. Permissions are assigned since v0.7 for a new install to anonymous and authenticated users respectively, and you will only need to adjust that to your needs. - Test the plugin and you should see a text control for tags in your Wiki edit page. You should also see an entry in the main navigation bar labeled Tags.
About i18n/l10n support
Since 0.7 this plugin is prepared for localization, and English message texts are still the (POSIX) default. If this isn't your preferred language, you can
- check if it's already available from the Trac plugin l10n project at Transifex or
- do it yourself, see the l10n cookbook page for Trac plugins for more details.
You've done a new translation? Superb! Contributing your translation is highly appreciated.
You could send it to the plugin's maintainer or contribute to Trac plugin l10n project via Transifex:
Top translations: Trac_Plugin-L10N » tractags
Left: Status for tractags-0.7, right: following trunk
Preparing the plugin from source requires no additional steps for compiling message catalog files. Only to include translations marked as # fuzzy
by the translator, you'll want to do a manual message catalog compilation with the extra -f
argument before packaging:
cd tagsplugin/
python setup.py compile_catalog -f
python setup.py bdist_egg
Due to a known Trac issue Babel has to be installed prior to Trac, to get it all working as expected. Again, for more details see the l10n cookbook page for Trac plugins.
Recent Changes
- 18666 by jun66j5 on 2024-10-31 22:39:05
-
TracTags: enable
[bdist_wheel] universal
option
- 18665 by jun66j5 on 2024-10-31 10:13:39
-
TracTags: use
@lazy
decorator to avoid fetching records on component initiation as a workaround (refs #14360)
- 18664 by jun66j5 on 2024-10-31 09:47:08
-
TracTags: install xmlrpcplugin when running tests
(more)
Author/Contributors
Author: athomas
Maintainer: Ryan J Ollos
Contributors: hasienda, itamarost, jun66j5, osimons, rjollos
Attachments (2)
-
transifex_top-translations_tractags-0.7_chart.png (13.8 KB) - added by 11 years ago.
coverage of translations per language for v0.7
-
tags_example.png (69.7 KB) - added by 4 years ago.
Screenshot of tags from a wiki page
Download all attachments as: .zip