| Tag-me Plugin
<--
Contributions to this plugin are appreciated. Please update the plugin page at
http://twiki.org/cgi-bin/view/Plugins/TagMePlugin or provide feedback at
http://twiki.org/cgi-bin/view/Plugins/TagMePluginDev.
If you are a TWiki contributor please update the plugin in the SVN repository.
-->
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.
Default "twiki" style
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
"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:
But, if you click on Tags, and that you have an account and can edit tags, you
will see:
Create, Rename, Delete tags
Create New Tags
Go to TWiki.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 TWiki.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 TWiki.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
TWiki.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}%/%SYSTEMWEB%/TagMeSearch?tag=$tag\" style=\"font-size:$size%\">$tag</a>" separator=" " minsize="94" maxsize="220"}%
</div>
List My Tags
TWiki.TagMeViewMyTags shows all tags used by logged-in user. The font size indicates the overall tag count of a tag.
Tag Search
TWiki.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 Parameter | Comment | Default | style="blog" | will expand into a "tag edit" frame that allows tag management as commonly found in blogs or tag systems like delicious, but only if tpaction is actually present. If tpaction is omitted, but the style is "blog" , will show nothing. Thus a button to make the edit tags frame appear can be put as: <a href="%SCRIPTURL{viewauth}%/%SYSTEMWEB%/%TOPIC%?tpaction=show">Edit tags</a> | "twiki" | label=", " | (for style=blog) link label (text) to open the edit tags form | "" | button=", " | (for style=blog) the complete button, link or html construct that will be shown when not in edit tag mode. Should open the Edit tag form when clicked by redirection to this same topic with a tpaction=show added. Overrides label . | "" | header="..." | (for style=blog) Printed before the edit tags form if it is not empty, $n can be used for newlines. e.g: header="Manage your tags: <i>" | "" | footer="..." | (for style=blog) Printed after the edit tags form if it is not empty, $n can be used for newlines. e.g: footer="</i>" | "" |
-
%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" | header="..." | Printed before the list of tags if it is not empty, $n can be used for newlines. e.g: header="Tags: <i>" | "" | separator=", " | Separator between tags | ", " , unless format has been specified | footer="..." | Printed after the list of tags if it is not empty, $n can be used for newlines. e.g: footer="</i>" | "" |
-
%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 TWiki.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
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
For TWiki 4.1, use:
* Set SKIN = tagme04x01,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 TWiki.PatternSkinCssCookbook.
The short summary is:
Other places for the tag interface
To show the tags in the top bar, edit TWiki.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.TWikiPreferences:
* Set WEBCOPYRIGHT = Tags: %TAGME{ tpaction="%URLPARAM{tpaction}%" web="%WEB%" tag="%URLPARAM{tag}%" }%, [[%SYSTEMWEB%.TagMeViewAllTags][view all tags]] %BR% Copyright © 1999-%GMTIME{"$year"}% by... etc
Show 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 used on twiki.org
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 |