[[PageOutline(2-5,Contents,pullout)]] {{{ #!NewsFlash = News = 2012-09-28:: Getting ready for `tags-0.7` now: #9521 has been addressed - Trac 1.0 support in `trunk`. 2011-07-06:: Version 0.6 is a complete rewrite for Trac 0.11. This page documents that version. Refer to ["TagsPlugin/0.5"] for information on older versions of the plugin. Also works on Trac 0.12. = !ToDo = * release `tags-0.7` * resolve performance issues, i.e. #4503 }}} = A Tagging System for Trac = The TagsPlugin implements both a generic tagging engine, and frontends 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. The TagsPlugin was originally created by [wiki:muness Muness Alrubaie] but has since been completely rewritten by [wiki:athomas Alec Thomas], and now maintained by hasienda. See also: KeywordSuggestPlugin, LoomingCloudsPlugin, TracKeywordsPlugin === 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 [http://en.wikipedia.org/wiki/Faceted_classification 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 Flickr. They are substantially different from Wikipedia categories, because tags are associated with wiki entries of the same name, whereas [http://meta.wikimedia.org/wiki/Categories WikiMedia Categories] are just indexes. This implementation of wiki tagging is specific to [wiki:TracGuide Trac]. To stay consistent with the way Trac names wiki entries, tags are case sensitive. Trac Hacks itself makes extensive use of tagging and is a good example of their use. == Usage == === Apply tags === To create a tag, follow these steps: 1. Go to the wiki entry you want to tag. 2. Click on ''Edit This Page'' 3. Under ''Change information'', ''Tag under:'', enter the tags you want to categorize the entry under. Separate tags with spaces. 4. Click ''Save changes''. The wiki entry you edit is now categorized under the tags you specified. Almost equivalent steps for tag entry at tickets, usually under `keywords` field. === Remove tags === To remove a tag from a wiki entry, follow these steps: 1. Go to the wiki entry you want to ''untag''. 2. Click on ''Edit This Page'' 3. Under ''Change information'', ''Tag under:'', remove the tag from the list. 4. Click ''Save changes''. Almost equivalent steps for tag removing at tickets, usually under `keywords` field. === Searching tags === Querying is implemented through the `/tags` uri handler, `the tag:` syntax or [http://projects.edgewall.com/trac/wiki/WikiMacros Trac Macros] 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: 1. Space-separated terms logically `AND`s them together. 2. Operators supported by the query language are: ||'''Operator'''||'''Function'''|| ||`or`||Logical `or`|| ||`not`||Logical `not`|| ||`realm:`||Restrict to tags in `` where realm is `wiki`, `ticket`, etc.|| 3. Sub-expressions can be grouped inside parentheses `(`, `)`. 4. Expressions and individual tags can be quoted with single `'` or double `"` quotes. (check #3624) Examples:: 1. Intersection of `macro` and `plugin` tags: `tagged:"macro plugin"` 1. Union of `macro` and `plugin` tags: `tagged:"macro or plugin"` 1. Objects tagged `macro` or `plugin`, ''and'' `example` `tagged:"(macro or plugin) example"` ==== /tags handler ==== Going to /tags under your project will show a list of all tags in the wiki. /tags/?q= will show all the objects matching ''''. e.g. [http://trac-hacks.org/tags/?q=plugin]. This accepts all the parameters that the !ListTagged macro does. e.g. [http://trac-hacks.org/tags?q=plugin%20or%20macro]. ==== `tag:` or `tagged:` ==== Both forms are identical and link to the tag search results for the query. Example:: * `tagged:todo` or `tagged:"plugin macro"`. ==== !ListTagged macro ==== This will display a list of resources whose tags match ``. * Version 0.6 -> `[[ListTagged([realm: ])]]` * Version 0.7dev -> `[[ListTagged([realm: ][,format=...][,cols=...])]]` ||'''Argument''' || '''Version''' || '''Description & Details''' || '''Default''' || || `realm:` || 0.6 ||''Optional.'' Restrict tags search to a specific `` where `` is `wiki` or `ticket` (accepts only one realm). ||`realm:ticket` || || `` || 0.6 ||Displays a list of resources whose tags match ``|| `None` || || `format` || 0.7dev ||''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.7dev ||''Rendering Option.'' A pipe (`|`) separated list of columns to show when used `format=table` option. Available options are:[[BR]] * `realm` - identifies to which realm the resource is (wiki or ticket);[[BR]] * `id` - shows the name of the wiki page (if resource is a wiki) or ticket number (if resource is a ticket); [[BR]] * `description` - first title (if resource is a wiki) or ticket summary (if resource is a ticket);[[BR]] * `tags` - all applied tags for such resource || `cols=id|description|tags` || Examples:: * Intersection of `macro` and `plugin` tags: `[[ListTagged(macro plugin)]]` * All resources tagged `macro` but not `plugin`: `[[ListTagged(macro -plugin)]]` * Tickets tagged with `macro`: `[[ListTagged(realm:ticket macro)]]` * Pages tagged with `macro`: `[[ListTagged(realm:wiki macro)]]` ==== !TagCloud macro ==== `[[TagCloud(-Dummy)]]` Display a cloud of all tags, assuming you do not use the '''Dummy''' tag. == Install == Generic installation guidelines are troubleshooting can be found at TracPlugins. Steps to install and configure this plugin are: 1. '''Install''' * Dependencies: 1. None: * Plugin: 1. Manually: 1. Download tags: [download:tagsplugin/tags/0.6 tags-0.6.zip] or grab [/svn/tagsplugin/tags/0.6 the source] from SVN. 2. [trac:wiki:TracPlugins Build and install an egg] from this source. 1. with easy_install: {{{ #!sh $ sudo easy_install https://trac-hacks.org/svn/tagsplugin/tags/0.6 }}} 1. '''Configure''' * '''Note''':: older !TagsPlugin configuration '''must be removed'''. In particular `trac.wiki.web_ui.wikimodule = disabled` and `default_handler = TagsWikiModule`. * Tags 0.6 has vastly simplified the configuration to the point where there are only two options, both of which are under the `[tags]` section: 1. `ignore_closed_tickets = ` * Whether to gather tags from closed tickets. 1. `ticket_fields = [, ...]` * Ticket fields from which to gather tags. Defaults to `keywords`. Custom fields are currently not supported. * For Tags 0.7dev, after install see the TracIni page for the available configuration options. * Example: {{{ [tags] ignore_closed_tickets = true ticket_fields = component, keywords, milestone }}} 1. '''Enable''' * Update your TracIni file (`..../trac.ini`) with: {{{ [components] tractags.* = enabled }}} 1. '''Run''' on your Trac environment {{{ #!sh $ trac-admin upgrade }}} 1. '''Restart''' web server: {{{ #!sh $ sudo /etc/init.d/apache2 restart }}} 1. '''Grant''' `TAGS_VIEW` and `TAGS_MODIFY` permissions to your users according to the policies that you'd like to implement. 1. '''Test''' At this stage the plugin should be working 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 === The development version of this plugin is prepared for localization. But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 1. look, if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tractags Transifex] or 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork 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 [TracPluginTranslation Trac plugin l10n project] via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: Top translations: Trac_Plugin-L10N ยป [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tractags/ tractags][[BR]] [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=http://www.transifex.net/projects/p/Trac_Plugin-L10N)]] Kindly provided by [[Image(http://sw.transifex.net/2/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]] 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 }}} Complaints about missing `locale` directory are often a side-effect of failure to compile any message catalog for inclusion into Python egg, hence the whole path is missing. Due to a know Trac issue Babel has to be installed prior to Trac, to get it all working as expected.[[BR]] Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. == Bugs & Feature Requests == Check the [query:?status=new&status=assigned&status=reopened&group=&component=TagsPlugin&order=priority existing bugs and feature requests]. If you have additional issues, create a [/newticket?component=TagsPlugin&owner=hasienda new ticket]. == Source & Download == You can check out !TagsPlugin from [http://trac-hacks.org/svn/tagsplugin here] using Subversion, or [source:tagsplugin browse the source] with Trac. You can also download the zipped source from [download:tagsplugin here]. === Most Recent Changes === [[ChangeLog(/tagsplugin, 2)]] == Author/Contributors == '''Author:''' athomas [[BR]] '''Maintainer:''' hasienda [[BR]] '''Contributors:''' hasienda