wiki:TagsPlugin

Version 22 (modified by athomas, 7 years ago) (diff)

--

Note: Version 0.6 is a complete rewrite. This page documents that version. Refer to this page for documentation on older versions of the plugin.

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.

Bugs/Feature Requests

Existing bugs and feature requests for TagsPlugin are here.

If you have any issues, create a new ticket.

Obtaining and Installing

Follow the installation instructions?.

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. 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 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 will link to a Wiki page. If that doesn't exist, it will instead link to a listing of all the objects tagged <tag>.

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

Change Log

[14159] by hasienda on 2014-09-07 19:35:11
TagsPlugin: Finally fix TagSystem.describe_tagged_resource, refs #2749.

While correcting [14156] the original implementation from [3880] is now fully
reworked into a reliable resource description getter method, obsoleting other
fallbacks.

[14158] by hasienda on 2014-09-06 16:49:20
TagsPlugin: Test generator for emptyness instead of totally consuming it, refs #3624 and #11950.

Made it just as light as needed for something like a formatter method.

[14157] by hasienda on 2014-09-06 10:40:15
TagsPlugin: Add a versatile Trac request mockup, refs #11945.

This is partially a rework of [14146] using partial built-in for better
maintainability.

Thanks to Ryan J Ollos for designing and proposing the new utility class.

[14156] by hasienda on 2014-09-05 23:30:40
TagSystem: Fallback to Trac resource manager method rather than just logging.

Note that the method was already imported but unused before.
For those who care, try..catch is even the recommended, more efficient and
'pythonic' way to go.

[14155] by hasienda on 2014-09-05 23:20:25
TagsPlugin: Add more permission checks after further review, refs #11968.

Looking at the optional permission-based filtering for taggable realms made me
watch out for places where we might have been too permissive until now.

Attachments (1)

Download all attachments as: .zip