Label Management Plugin

Name	Label Manager Plugin
Vendor	James House (Website)
Authors	James House
Homepage	http://confluence.atlassian.com/display/CONFEXT/Label+Management+Plugin
Issue Management	http://developer.atlassian.com/jira/browse/LBLMAN
Continuous Integration	n/a
Categories	Content Macros
Most Recent Version	1.1
Availability	Confluence v2.2-rc1 to v2.10
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Free
Release Docs	http://confluence.atlassian.com/display/CONFEXT/Label+Management+Plugin
Java API Docs	n/a
Download Source	http://svn.atlassian.com/svn/public/contrib/confluence/label-management-plugin/tags/1.1/
Download JAR	plugin-labelmanagement-1.1.jar

Description/Features

Helps users take better advantage of the powerful page labels feature by letting them manage page hierarchies of labelings. This makes Confluence's "Search" and "RSS Feed Builder" features far more useful.

The Problem

Labels are a powerful feature of Confluence, but there is no existing way to add/remove them from a page without directly visiting that page. This can get extremely tedious when you wish to add a given label to a page as well as all of its children, particularly when the page is the head of a large hierarchy of pages.

Even worse, once you have labeled all of the pages in a hierarchy, another user may add a new page, and not add the label, creating inconsistencies over time.

The Solution

The "Label Manager" plugin allows to to add a label to a page and all of it's children with one simple click!

The "Label Manager" also has a powerful feature called "Sticky Labels": if you use the manager to mark a label as "sticky", then all child pages of that page will always have the label. In other words, the child pages cannot have that label removed from them, and any new child pages added to the hierarchy automaticaly get the label!

Once you have your pages well labeled, searching and RSS feeds are far more powerful!

Usage

If you install the suggested links (below in the "Install" section) you can get to the Label Manager two ways:

From the main controls:

From the page labeling controls:

Once you are on the Label Management screen, you can use the Select Space control to choose which space you are manging labels in.

The left panel will display the hierarchy of pages in the selected space. Next to each page is a listing of the page's labels, color coded per the label type (label types are discussed below).

Click on a page name to manage its labels. The right panel will display the details of the page's labels, and offer conrols to manage them (if you have permissions to edit the page). Clicking on the icon next to a page title will take you to that page - away from the Label Manager.

You can hover your mouse pointer over the control action links to get more information about what the action will do.

Summary of controls:

sticky will make the label 'sticky' (see label types below)
un-sticky will make the label 'normal'
remove will remove the label from the page
remove from tree will remove the label from the page and all child pages that have it as well
add will add the label to the page (a label must already exist in the space to be added)
add to tree will add the label to the page and all child pages as well
add sticky will add the label to the page as a 'sticky' label

Label Types

Normal Labels (highlighed yellow) are just that - labels attached to the page, with no special properties.
Sticky Labels (highlighted pink) are labels that have been marked "sticky" using the Labeling Manager conrols for the page. Sticky labels cause all child-pages to "inherit" the label. The label cannot be removed from child pages. Any new page added as a child in the page hierarchy will have the label automatically added.

Inherited (Sticky) Labels (highlighed green) are labels on a page that are there due to one of its parent pages having a sticky label. Inherited sticky labels cannot be removed from a page until the label is made un-sticky on the parent page that has declared it sticky.

The Label Manager only lets you work with (such as add to a page) labels that already exist in the Space. If you need a new label, temporarily visit the page on which it belongs, and use the normal "EDIT" labels feature. You may then return to the Label Manager and add it to all child or make it "sticky".

Here is a complete view of the Label Manager (click to view):

Examples

To help you better understand how the Label Manager, and more particularly "sticky labels" work, the following example is given:

Here is a view of the Label Manager's left panel, which shows the space's page hierarchy. Next to each page is shown the page's labels, color coded with type.

In order to aid searching and creating selective RSS feeds (using Confluence's Feed Builder), the pages in this space have been labeled with metadata.

In our example, we desired that all pages under the "Documentation" page heirarchy be labeled as "documentation". This was easily accomplished with the Label Manager, simply by making the "documentation" label sticky on the "Documentation" page. You can see in the screen shot that all child pages have inherited the label. What's more, because the label is sticky if anyone adds a page to hierarchy, they need not remember to label it as "documentation", as it will automatically happen! Further, no one can mistakenly remove that label from any of the pages - as it will be automatically replaced.

Examine the screen shot and take note of all sticky labels (in pink) and the inheritance (in green) they cause down the tree of the page hierarchy. Note that all pages that had to do with release version 1.0 of the Zippy Product have been painlessly labeled with "zippy_r1_0". Also note the "use_case" labeling.

Note how easy it will now be to search for all pages that are a use case document for release 1.0!

Installation

Installing the Plugin

Place the "plugin-labelmanagement.jar" in your Confluence install's "plugins" directory, restart Confluence, or more simply visit Confluence's Administration -> Plugins page, and select "rescan" to load the new plugin.

Exposing the Plugin on the UI

Once the plugin is in place, you also need to add links/controls to your pages for getting to the Labeling Manger UI.

Although you are free to place links to the Label Management Action anywhere on the Confluence UI that you wish, it is suggested that you do the following:

Add Link To Page Label Information Line

Open the file confluence/labels/labels-include.vm

Locate the div block that looks like this (note the "editLabelsLink" id of the span):

<span id="editLabelsLink" class="inline-control-link" style="display: none;">
    #if( $permissionCheckDispatcher.isPermittedForAjax("addLabelToEntity",[$entity]) )
      <a href="" onclick="onAddLabel(); showLabelsInput(); return false;">EDIT</a>
    #end
 </span>

Just after the closing span tag (</span>) add the following:

&nbsp;<span class="inline-control-link">
<a href="$req.contextPath/plugins/stickylabel/addstickylabel.action
?spaceKey=$spaceKey&pageId=$entity.id" mce_href="$req.contextPath/plugins/stickylabel/addstickylabel.action
?spaceKey=$spaceKey&pageId=$entity.id">MANAGE</a>
</span>

(be careful to make sure the complete link is on one line)

You may also want to add a label editing tip after the existing one:

Locate this block:

<div class="smalltext">
  <em>Tip:</em> Looking for a label? Just start typing.
</div>

Add this one after it:

<div class="smalltext">
  <em>Tip:</em> Labels come back after you remove them?  'Manage' sticky labels.
</div>

Add Link To Top-Level Controls Site-Wide:

Go the the "Administration" area of Confluence, and select "Layouts" under the
"Look and Feel" section.

Edit a custom version of the "Main Layout". Search for the line that reads:

#usernavbar()

On a new line immediately after this, add:

#if ($sitemeshPage.getProperty("page.spacekey"))
<span class="smalltext">| <a href="$req.contextPath/plugins/stickylabel/addstickylabel.action?spaceKey=$sitemeshPage.getProperty("page.spacekey")">Manage Labels</a>&nbsp;</span>
  #end

(be careful to make sure the complete link is on one line)

ENJOY!

Version History

1.0 - Initial release
1.0.1 - Fixed small bug related to space-select option when confluence is not deployed on root context of app server
1.1 - Fixes to allow use with Confluence 2.2.x

(contributions welcome!)

Screenshots

Screenshots

Link for Managing the Labels of a Page	Snip of View of the Page Hierarchy, showing labels	View of the Page Hierarchy, showing labels

Link for getting to the Label Manager	Controls for Managing the Labels of a Page	Complete View of the Label Manager

Selecting a Space in the Label Manger


Full Size

Label Management Plugin

Description/Features

The Problem

The Solution

Usage

Label Types

Examples

Installation

Installing the Plugin

Exposing the Plugin on the UI

Add Link To Page Label Information Line

Add Link To Top-Level Controls Site-Wide:

Version History

Screenshots

Screenshots

Labels

Comments (33)

James House says:

Mircea Botez says:

James House says:

James House says:

Kevin James says:

Dan Hardiker says:

James House says:

James House says:

Kevin James says:

Michael Kasten says:

Kalyan D says:

Simon Lieschke says:

Guy Fraser says:

Simon Lieschke says:

patrice saint-louis says:

Jonathan Nolen says:

Joaquin Obieta says:

Vanessa Vandervalk says:

Tony Cheah Tong Nyee says:

Kirk Mook says:

Kirk Mook says:

Martin Breest says:

David Page says:

Matt Bovett says:

Joseph Sagir says:

jd lima says:

semir h says:

Jeff Guthrie says:

Lukas Pischala says: