Tag-me Plugin

Plugin to tag wiki content collectively in order to find content by tags and to get a meaningful page ranking.

Introduction

The larger a wiki gets, the harder it is to find content. This wiki tagging plugin attempts to solve the issue based on these assumptions:

• Assertion 1: Intranet search does not work well due to inadequate ranking of search engines on intranets. This is because there are typically not many cross-links between pages.
• Assertion 2: Let the individuals build their own taxonomy to find content quickly
• Assertion 3: Let the users do the ranking to get an "human intelligence" ranking of important content

There are clear benefits in tagging content in a large TWiki (10K or more topics):

• Find relevant content in a large system quickly,
  • by quickly accessing related topics via the tags on a topic
  • by quickly accessing related topics via related tags listed in a specific tag view
  • by quickly identifying important tags in the tag cloud
• Access my favorite topics quickly (assuming I tag topics of interest)
• Solve the search ranking issue of wiki content indexed by a search engine
• Help solve stale content issue (old topics do not get tagged)

The design goals of the TagMePlugin were as follows:

• Any topic can be tagged by individuals -> create taxonomy for individuals
• Show tag statistics of all users on each topic -> show popularity
• Encourage users to reuse the same tag on a topic -> get a "collective ranking", or "vote for a tag", or "tag count"
• Make it as easy as possible to increase the tag count
• Make it as easy as possible to add a new tag to a topic
• Encourage users to create new tags, but try to avoid use of similar tags for the same subject
• Search for topic by tag, sorted by tag popularity

User Interface

Tag List on Topic

Every topic has a list showing all tags associated with the topic. Additional tags can be added to the topic, and new tags can be created.

Screenshot of tags shown on a topic:

You see:

• a list of tags with vote count and add/remove vote buttons,
• an add tag selector
• a link to create a new tag
• a link to the all tags view

Create, Rename, Delete tags

Create New Tags

For developers:
Use the url parameter createtag=my+tag+name to pass a new tag name to the form.

Add Tag to Topic

Rename Tags

For developers:
Use the url parameters renametagfrom=my+old+tag+name and renametagto=my+new+tag+name to pass the old and new tag names to the form.

Delete Tags

For developers:
Use the url parameter deletetag=my+tag+name to pass the to-be-deleted tag name to the form.

List All Tags

TagMeViewAllTags shows all tags used in the system. The font size indicates the overall tag count of a tag.

Screenshot of tag cloud in the list all tags view:

Tip: In a WebHome of a web you can show a tag cloud of all tagged topics in that web with this variable:

<div class="tagmeTagCloud" style="line-height:2em;">
%TAGME{ tpaction="showalltags" format="<a href=\"%SCRIPTURL{view}%/%WEB%/TagMeSearch?tag=$tag\" style=\"font-size:$size%\">$tag</a>" separator="&nbsp; " minsize="94" maxsize="220"}%
</div>

List My Tags

TagMeViewMyTags shows all tags used by logged-in user. The font size indicates the overall tag count of a tag.

Tag Search

TagMeSearch shows a list of topics that are tagged with all of the selected tags, sorted by relevance. Topics with a high tag count are shown first.

Plugin Variable

The Plugin handles a %TAGME{}% variable that performs different actions. The tpaction="" is a required parameter.

• %TAGME{ tpaction="show" }% - shows the tag list on topic

• %TAGME{ tpaction="showalltags" ... }% - view all tags or my tags as a tag cloud

  Parameter	Comment	Default
  by="me"	My own tags only; can also be a USERNAME	all tags
  web="%WEB%"	Limit query to a web	current web
  topic="*Plugin"	Limit query to a topic, or a comma-space delimited list of topics with optional asterisk wildcards	all topics
  exclude="fixme"	Exclude tags; specify a tag, or a comma-space delimited list of tags with optional asterisk wildcards	all tags
  mincount="2"	Exclude tags below the threshold of mincount votes	all tags
  minsize="90"	Minimum size of tag $size (typically percent font size)	"90"
  maxsize="180"	Maximum size of tag $size	"180"
  format="..."	Format of a tag, tokens $tag, $size, $marker (adds selected="selected" for use in html options), $count, $order	"$tag"
  separator=", "	Separator between tags	", ", unless format has been specified

• %TAGME{ tpaction="query" ... }% - tag search

  Parameter	Comment	Default
  by="me"	My tagged topics only; can also be a USERNAME	all tagged topics
  web="%WEB%"	Limit query to a web	current web
  topic="*Plugin"	Limit query to a topic, or a comma-space delimited list of topics with optional asterisk wildcards	all topics
  tag="..."	Name of tag	(required)
  sort="web"	Sorting of tagged topics: "tagcount" by tag count (relevance), "web" by web then topic name, "topic" by topic name	"tagcount"
  norelated="on"	Do not show the list of "related tags"	(show related tags)
  nototal="on"	Do not show total number of topics found	(show total)
  minsize="90"	Minimum size of topic $size (typically percent font size)	"90"
  maxsize="180"	Maximum size of topic $size	"180"
  format="..."	Format of a topic, any token of FormattedSearch can be used, such as $web, $topic, $summary, $rev, $n. In addition, $votecount expands to the number of tag votes, $size to the suggested font size, and $taglist to the tag list of the topic.	(nice formatting)
  separator=", "	Separator between tags, $n or $n() can be used for newlines	"$n"
  limit=""	limit number of results if sort="web"
  header=""	if sort="web", add this header once per web with results (only $web is interpreted)	---+++ $web
  footer=""	if sort="web", add this footer once per web with results (only $web and $count and $showmore are interpreted)	showing $limit out of $count results $showmore
  refine	Normally related tags are shown that when clicked on will search for the related tag. If refine is set to 1, then the link instead will add the clicked tag to the set of tags being searched for, allowing you to incrementally refine search results. If not set the value of ALWAYS_REFINE is used.

• %TAGME{ tpaction="newtag" ... }% - create new tag

  Parameter	Comment	Default
  tag="..."	Name of tag. Accepts alphanumeric and underscore characters only (unless NORMALIZE_TAG_INPUT is set to 0 to allow any user input)	(required)

• %TAGME{ tpaction="add" ... }% - add tag to topic, or add vote to existing tag

  Parameter	Comment	Default
  tag="..."	Name of tag	(required)
  nostatus="on"	Turn off status text shown when a tag is added or voted on	(show status text)

• %TAGME{ tpaction="newtagandadd" ... }% - create new tag and add tag to topic

  Parameter	Comment	Default
  tag="..."	Name of tag. Accepts alphanumeric and underscore characters only (unless NORMALIZE_TAG_INPUT is set to 0 to allow any user input)	(required)

• %TAGME{ tpaction="remove" ... }% - remove my tag vote on existing tag

  Parameter	Comment	Default
  tag="..."	Name of tag	(required)
  nostatus="on"	Turn off status text shown when a tag is removed or voted on	(show status text)

How to put tags on every page

To show the tag interface at the top of the page directly below the breadcrumb (like on twiki.org), use the default template view.tagme.tmpl in the templates directory.

This template is in fact a 'skin' template. To enable it, write in Main.TWikiPreferences:

   * Set SKIN = tagme,pattern

   * Set SKIN = tagme04x01,pattern

Customizing the appearance

• Create an empty CSS file, for instance sitestyle.css
• Copy the CSS styles for tagmetags (see below at Example styles used on twiki.org) into the file
• Attach the file to Main.TWikiPreferences
• In Main.TWikiPreferences, write:

     * Set USERSTYLEURL = %PUBURL%/%MAINWEB%/TWikiPreferences/sitestyle.css
     

Other places for the tag interface

<div class="tagmetags">
Tags: %TAGME{ tpaction="%URLPARAM{tpaction}%" web="%WEB%" tag="%URLPARAM{tag}%" }%, [[TWiki.TagMeViewAllTags][view all tags]]
</div>

To show the tags at the bottom of every page, write in Main.TWikiPreferences:

 * Set WEBCOPYRIGHT = Tags: %TAGME{ tpaction="%URLPARAM{tpaction}%" web="%WEB%" tag="%URLPARAM{tag}%" }%, [[TWiki.TagMeViewAllTags][view all tags]] %BR% Copyright © 1999-%GMTIME{"$year"}% by... etc

How to show the tags without vote buttons

Tags: %TAGME{ tpaction="showalltags" web="%WEB%" topic="%TOPIC%" format="<a href=\"%SCRIPTURL{view}%/%TWIKIWEB%/TagMeSearch?tag=$tag\">$tag</a> " }%

Tag styles

CSS Styles

Search results CSS Styles

Preventing link wrap

<div class="tagmeTagCloud">
%TAGME{ ... }%
</div>

This CSS style is included in tagme.css:

.tagmeTagCloud a {
   white-space:nowrap;
}

Example styles used on twiki.org

<div class="tagmetags">
Tags: %TAGME{ tpaction="%URLPARAM{tpaction}%" web="%WEB%" tag="%URLPARAM{tag}%" }%, [[TWiki.TagMeViewAllTags][view all tags]]
</div>

CSS styles:

.tagmetags select {
   font-size:.8em;
   margin:0 .25em;
}
.tagmetags a {
   text-decoration:none;
   white-space:nowrap;
}
.tagmetags a:link,
.tagmetags a:visited {
   color:#8E9195; /* all links are gray; for blue links use: #06c */
   text-decoration:none;
}
.tagmetags a:hover {
   color:#FBF7E8; 
}
.tagMeControl {
   color:#8E9195; /* gray for non-links */
}

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, e.g., %TAGMEPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Tag wiki content collectively to find content by keywords

• Log add/create actions:
  • Set LOGACTION = 1

• Optionally normalize tag names. Set to 1 to translate international characters to their latin match (ü to ue, å to aa, etcetera), and to convert spaces to underscores.
  Set to 0 to allow any user input, except for the reserved characters ,#'"|*.
  Setting to 0 also sorts tags case insensitive: 'U' comes after 't'.
  • Set NORMALIZE_TAG_INPUT = 0

• If 1, then the refine parameter is always added to TAGME queries.
  • Set ALWAYS_REFINE = 1

• List of users and groups that are allowed to change (rename and delete) tags (names separated by commas).
  Users that are not allowed to change post their change requests to TagMeChangeRequests.
  If not set anyone can change tags.
  • Set ALLOW_TAG_CHANGE = TWikiAdminGroup

• Debug plugin: (See output in data/debug.txt)
  • Set DEBUG = 0

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the Plugin on the TWiki server.

• Download the ZIP file from the Plugin web (see below)
• Unzip TagMePlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/TagMePlugin.txt	Plugin topic
  data/TWiki/TagMeViewAllTags.txt	Supporting topic to view all tags
  data/TWiki/TagMeViewMyTags.txt	Supporting topic to view my tags
  data/TWiki/TagMeSearch.txt	Supporting topic to search for tagged topics
  data/TWiki/TagMeManage.txt	Supporting topic to create new tags
  data/TWiki/TagMeDebug*.txt	Supporting topics for debug
  lib/TWiki/Plugins/TagMePlugin.pm	Plugin Perl module
  pub/TWiki/TagMePlugin/*.gif	Icon files
  templates/view.tagme.tmpl	Template containing GUI components

• Configure and enable the Plugin:
  • TWiki 4.0 and up: Run the configure script to enable the Plugin
  • Change the Plugin settings as needed:
    • Determine who will be allowed to rename and delete tags.
    • For international character support: set NORMALIZE_TAG_INPUT to 0.
    • To allow any user input as tag name also set NORMALIZE_TAG_INPUT to 0.
  • To put the tags interface on every page, see the instructions above at How to put tags on every page
• Test if the installation was successful:
  • Go to TagMeCreateNewTag and add a tag

Limitations

• TWiki 04-Sep-2005 and older: Tags are lost if a topic is renamed or moved.

Plugin Info

Related Topics: TagMeViewAllTags, TagMeViewMyTags, TagMeSearch, TagMeDebugViewTags, TagMeDebugSearch, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

-- TWiki:Main.PeterThoeny - 16 Oct 2007