Tag-me Plugin

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

On this page:

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:

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

The design goals of the TagMePlugin were as follows:

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.

Default style

Screenshot of tags shown on a topic:
Screenshot of tags on a topic

You see:

"blog" style

But the same control can have a different look and feel if we specify style="blog". In view mode it has a terse apperance:

Screenshot of tags on a topic, style=blog

But, if you click on Tags, and that you have an account and can edit tags, you will see:

Screenshot of tags on a topic, style=blog

"jqui"

An experimental interactive user interface is also provided, implemented using the latest version of JQueryPlugin in TagMeAjaxHelper.

All features work without having to re-load the topic:

Include it into your WebTopBar? (See WebTopBarExample) or any part of your skin that has horizontal space to spare, as follows: 

%INCLUDE{"%SYSTEMWEB%.TagMeAjaxHelper" section="jqui"}%

Screenshot of experimental jQuery UI

Dependencies:

Create, Rename, Delete tags

Create New Tags

Go to TagMeCreateNewTag to create new tags.
Anyone is allowed to 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

Once a new tag is created, it can be added in the tag list of the topic.

Rename Tags

Go to TagMeRenameTag to rename existing tags.
Rename permissions are controlled with ALLOW_TAG_CHANGE (see Plugin Settings below).

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

Go to TagMeDeleteTag to delete existing tags.
Delete permissions are controlled with ALLOW_TAG_CHANGE (see Plugin Settings below).

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:

Screenshot of view all tags tag cloud

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

How to put tags on every page

To show the tag interface at the top of the page directly below the breadcrumb (like on foswiki.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.SitePreferences: 

   * Set SKIN = tagme,pattern
The list of skins can be appended, for instance: tagme,corporate,pattern.

For the "blog" style, use for a simple "Tags: list-of-tags (edit)" at the top of the page: 

   * Set SKIN = tagme_styleblog,pattern
And for an alternate style, with no tags line shown if no tags exists, and the button to open the tag edit frame placed at the right of the Edit and Attach ones, in the same style, on the upper right: 
   * Set SKIN = tagme_styleblogbutton,pattern

Customizing the appearance

If you customize your site you probably want to change overall appearance. You can find instructions how to do that - at least for default pattern skin - in System.PatternSkinCssCookbook.
The short summary is:

Other places for the tag interface

To show the tags in the top bar, edit System.WebTopBar? and copy: 
<div class="tagmetags">
Tags: %TAGME{ tpaction="%URLPARAM{tpaction}%" web="%WEB%" tag="%URLPARAM{tag}%" }%, [[%SYSTEMWEB%.TagMeViewAllTags][view all tags]]
</div>

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

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

How to show the tags without vote buttons

To just show the tags for a topic, without buttons or "Create new tag" link, use a showalltags search: 
Tags: %TAGME{ tpaction="showalltags" web="%WEB%" topic="%TOPIC%" format="<a href=\"%SCRIPTURL{view}%/%SYSTEMWEB%/TagMeSearch?tag=$tag\">$tag</a> " }%

Tag styles

CSS Styles

TagMePlugin writes the following CSS styles:

Class Used where
tagMeControl Around 'tags shown on a topic': tag link plus vote counter plus add/vote button
tagMeVoteCount Around vote count number
tagMeNotification span: One-line notification feedback after adding or removal of a tag and on in this process
tagMeNotification div: Block of notification feedback after creation of a tag and on errors in this process
tagmeAction Link style for buttons add and remove tag vote
tagmeNavigation Table style for tabbed admin pages

Search results CSS Styles

Class Used where
tagmeRelated Text style of the line "Related tags (Click to refine the search)"
tagmeResultsTable Table style for search results
tagmeResultsTableHeader Table header with link to topic, last modified date and author. These have the additional classes td.tagmeTopicTd, td.tagmeDateTd, td.tagmeAuthorTd, tagmeTopicTdWeb
tagmeResultsDetails Wrapper around tagmeResultsSummary and tagmeResultsDetails
tagmeResultsSummary The topic summary
tagmeResultsTags List of tags for the topic

Preventing link wrap

If users are allowed to use spaces in their tag names (when NORMALIZE_TAG_INPUT is set to 0), tag links may break halfway to the next line. To prevent wrapping, add a wrapper div around the tags: 

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

This CSS style is included in tagme.css: 

.tagmeTagCloud a {
   white-space:nowrap;
}

Example styles

To show the 'tags shown on a topic': 

<div class="tagmetags">
Tags: %TAGME{ tpaction="%URLPARAM{tpaction}%" web="%WEB%" tag="%URLPARAM{tag}%" }%, [[%SYSTEMWEB%.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. To reference a plugin setting write %<plugin>_<setting>%, e.g., %TAGMEPLUGIN_SHORTDESCRIPTION%

NOTE: In a change from previous releases, preferences cannot be set in this topic. Use the standard preference setting topics, such as SitePreferences, instead.

Preference name Meaning Default
TAGMEPLUGIN_LOGACTION Log add/create actions 1
TAGMEPLUGIN_NORMALIZE_TAG_INPUT 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'. 		0
TAGMEPLUGIN_ALWAYS_REFINE If 1, then the refine parameter is always added to TAGME queries. 1
TAGMEPLUGIN_ALLOW_TAG_CHANGE 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. 		AdminGroup
Set TAGMEPLUGIN_BUNDLES Bundles are groups of tags that are presented as menus for convenience. It is a list of space-separated (or comma-separated if your tags may contain spaces) prefixed by bundle labels terminated by colon (":"). e.g:
  1. * Set TAGMEPLUGIN_BUNDLES = Rating: * * * Todo: to_blog to_read
  2. * Set BUNDLES = Rating:, , *, **, Todo:, to_blog, to_read
  
TAGMEPLUGIN_DEBUG Generate debug trace in foswiki debug log

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Plugin Author: Peter Thoeny, Arthur Clemens
Copyright: © 2006-2007, Peter Thoeny
License: GPL (GNU General Public License)
Version: 6613 (2010-03-02)
Release: 02 Mar 2010
Change History:  
02 Mar 2010: Foswiki:Main.PaulHarvey: Fix IE compatibility, link tag items to TagMeSearch topic with web parameter
01 Mar 2010: Foswiki:Main.PaulHarvey: Added an interactive user interface implemented with JQuery; ship missing blog style tmpl files; fix docs/implementation of newtagsandadd
11 Jun 2009: Foswiki port, and moved settings out of this topic
30 Aug 2008: Foswiki:Main.ColasNahaboo: enhancements to the "blog" style: Bundles, count of known tags, option to delete tags
28 Aug 2008: Foswiki:Main.ColasNahaboo: prefix & suffix options renamed as header & footer. New parameter style to TAGME to be able to define different UI style for the default "show" action of TAGME. Implemented a first one, "blog" for the simpler case of authors managing the same tags
26 Aug 2008: Foswiki:Main.ColasNahaboo: prefix & suffix options to TAGME
16 Oct 2007: Foswiki:Main.ArthurClemens: added backward compatible example template.
26 Sep 2007: Foswiki:Main.CrawfordCurrie Item4728 fixed incorrect cloud font sizes to reflect relative importance of tags actually being displayed
11 Sep 2007: Foswiki:Main.ArthurClemens: updated example template to TWiki template convention.
11 Jun 2007: Foswiki:Main.ArthurClemens: fixed sizing of tags with the same tag count; fixed CSS class for select box; updated documentation with "How to put tags on every page".
07 Jun 2007: Foswiki:Main.ArthurClemens: removed dependency on (unreleased) TWiki 4.2.
21 May 2007: Foswiki:Main.WillNorris: added view.tagme.tmpl and updated installation instructions.
30 Apr 2007: Foswiki:Main.ArthurClemens: fixed calculation of sizes in tag cloud; if mincount is passed only the shown tags are calculated.
18 Apr 2007: Foswiki:Main.ArthurClemens: added permissions for rename and delete; added TagMeChangeRequests.
17 Apr 2007: Foswiki:Main.CrawfordCurrie for Escape Studios: contributed support for incremental refinement of tag searches.
12 Apr 2007: Foswiki:Main.CrawfordCurrie contributed ability to search for multiple tags. TWiki:Main.SvenDowideit for Escape Studios: added parameters needed for custom search result display.
05 Apr 2007: Foswiki:Main.ArthurClemens: The "topic tags" select box is now created with Javascript to prevent the tag options getting indexed by search engines. The former select box is used for noscript fallback.
02 Apr 2007: Foswiki:Main.ArthurClemens: Added "Delete Tag" interface. Added tabbed interface for Create, Rename, Delete tags.
30 Mar 2007: Foswiki:Main.ArthurClemens: Added "Rename Tag" interface.
22 Mar 2007: Foswiki:Main.ArthurClemens: Added option NORMALIZE_TAG_INPUT (to be set to 0) to allow any word as tag name (including upper case, punctuation characters and spaces). Moved "Create New Tag" to dedicated page. Created CSS styles in tagme.css. Added mincount parameter to TAGME{tpaction="showalltags"}.
14 Nov 2006: Fix IE browser crash issue on print (forms can't be named "tags"; debug by TWiki:Main.KevinKalmbach)
14 Oct 2006: Fix show default problem introduced by version 07 Oct 2006 (contributed by TWiki:Main.ChristianSuenkel)
07 Oct 2006: nostatus="on" parameter for add/remove tag (contributed by TWiki:Main.FredMorris)
05 Oct 2006: Fix issue of missing topics in tag search if topic name contains plus or minus sign (workaround for TWiki core TWikibug:Item2625 and TWikibug:Item2967)
04 Oct 2006: Fix issue of statistics moving WebHome tags to WebStatistics
02 Oct 2006: Support for topic rename (tags are no longer lost)
14 Sep 2006: MAKETEXT support (TWiki:Main.KoenMartens); fixed nested webs issue; fix in generated XHTML (TWiki:Main.ArthurClemens)
20 May 2006: Support international characters (contributed by TWiki:Main.AntonioTerceiro)
09 May 2006: Support for sub-webs; enclose tag list on topic in span class="tagMePlugin"; tag selector not shown if empty; limit max size of new tags to 30 characters
21 Mar 2006: TagMeSearch with minsize and maxsize parameters; TagMeSearch format with $votecount, $size; fixed JavaScript compatibility issue on TWiki 4.0
11 Mar 2006: TagMeSearch with sort, norelated, nototal, format and separator paramters; linked tags in create new tag section; renamed TagMeViewSpecificTag to a shorter TagMeSearch; workaround for Dakar TWikibug:Item1838 to fix broken links in top bar
06 Mar 2006: Remove my tag vote; added exclude="", minsize="" and maxsize="" parameters; more intuitive icons; in default view, sort tags alphabetically instead of sort by tag vote
03 Mar 2006: Allow underscore in tags (and convert space and dash to underscore); added web="" and topic="" parameters; fixed font size issue in tag cloud with disproportional counts
28 Feb 2006: Use tabs in all/my/specific tags view; show related tags in specific tags view; check if topic exists when adding tags;
26 Feb 2006: Added view all tags / my tags (as tag clouds); view specific tag (sorted by tag count); do not allow guests to create new tags; log add/create tag actions
20 Feb 2006: Initial version
Home: Foswiki:Extensions/TagMePlugin
Support: Foswiki:Support/TagMePlugin

Related Topics: TagMeViewAllTags, TagMeViewMyTags, TagMeSearch, TagMeDebugViewTags, TagMeDebugSearch, TagMeAjaxHelper, Plugins, DeveloperDocumentationCategory, AdminDocumentationCategory, DefaultPreferences, SitePreferences spacer