wiki:TagsPlugin

Version 48 (modified by anonymous, 3 years ago) (diff)

--

Note: Version 0.6 is a complete rewrite for Trac 0.11. This page documents that version. Refer to this page for information on older versions of the plugin. Also works on Trac 0.12.

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 Muness Alrubaie but has since been completely rewritten by Alec Thomas.

See also: KeywordSuggestPlugin

Bugs/Feature Requests

Check the existing bugs and feature requests. If you have additional issues, create a new ticket.

Download

Download the zipped source from here.

Source

You can check out TagsPlugin from here using Subversion, or browse the source with Trac.

Installing

  1. install
  2. Configure appropriately for your version of Trac. Update your trac.ini with this:
    [components]
    tractags.* = enabled
    
    Be sure to remove any previous TagsPlugin configuration changes. In particular trac.wiki.web_ui.wikimodule = disabled and default_handler = TagsWikiModule must be removed.
  3. Run trac-admin <env> upgrade on your Trac environment.
  4. Restart your web server.
  5. Grant TAGS_VIEW and TAGS_MODIFY permissions to your users according to the policies that you'd like to implement.

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.

Configuring TagsPlugin

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:

ignore_closed_tickets = <bool>

Whether to gather tags from closed tickets.

ticket_fields = <field>[, <field> ...]

eg. ticket_fields = component, keywords.

Ticket fields from which to gather tags. Defaults to keywords. Custom fields are currently not supported.

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 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 Trac names wiki entries, tags are case sensitive. Trac Hacks itself makes extensive use of tagging and is a good example of their use.

How do I 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.

How do I remove a tag from a wiki entry?

To remove a tag from a wiki entry

  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.

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/?q=<expression> will show all the objects matching <expression>. 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:<tag> or tagged:<expr> Usage

Both forms are identical and link to the tag search results for the expression.

e.g. tagged:todo or tagged:"plugin macro".

Tag expressions

Both the ListTagged macro and the /tags handler use a basic expression language for filtering tagged objects.

Space-separating terms logically ANDs them together.

Operators supported by the language are:

OperatorFunction
orLogical or
notLogical not
realm:<realm>Restrict to tags in <realm> where realm is wiki, ticket, etc.

Sub-expressions can be grouped inside parentheses (, ).

Expressions and individual tags can be quoted with single ' or double " quotes.

Examples

Intersection of macro and plugin tags:

tagged:"macro plugin"

Union of macro and plugin tags:

tagged:"macro or plugin"

Objects tagged macro or plugin, and example

tagged:"(macro or plugin) example"

Macro Usage

ListTagged

[[ListTagged(<expr>)]]

This will display a list of resources whose tags match <expr>.

Examples

Intersection of macro and plugin tags:

[[ListTagged(macro plugin)]]

Pages tagged macro but not plugin:

[[ListTagged(macro -plugin)]]

TagCloud

[[TagCloud(-Dummy)]]

Display a cloud of all tags, assuming you do not use the Dummy tag.

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 Trac plugin l10n project at Transifex or
  2. 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

http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/tractags/chart/image_png

Kindly provided by http://sw.transifex.net/2/static/charts/images/tx-logo-micro.png

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.
Again, for more details see the l10n cookbook page for Trac plugins.

Change Log

[13874] by hasienda on 2014-04-26 19:38:04
TagsPlugin: Adapt unit tests to [13867], refs #1344.
[13873] by hasienda on 2014-04-26 02:14:49
TagsPlugin: Create filter component to show events only for resources matching tag query, refs #3660.

The input field added to timeline preferences box accepts full TagQuery
syntax, even filtering events by taggable realm without specifying a tag.

[13867] by hasienda on 2014-04-24 16:11:36
TagsPlugin: Refit of configuration options inherited from KeywordSuggestPlugin, refs #1344, #3816, #4201 and #11690.

Included are minor changes for component doc-strings as follow-up to [13865].

Author/Contributors

Author: athomas
Maintainer: otaku42
Contributors: hasienda

Attachments (1)

Download all attachments as: .zip