Metadata Plugin 2

Description/Features

Version 2 is a major rewrite of the Metadata Plugin that extends the functionality in a number of directions. The highlights are as follows:

• support for adding metadata and generating reports for spaces
• support for hierarchical spaces through space metadata
• new metadata reports for users, blog posts and attachments
• alternative renderings for each report
• provided access to more internal metadata
• full support for dates
• addressed a number of reported issues

Space metadata

This release adds the same metadata functionality to spaces that the previous version provided for pages. There are a lot of useful reports that you can now generate automatically from your Wiki.

e.g. a report of all the spaces, all the spaces tagged with a specific label

The main improvement over the built-in Confluence support for showing spaces is that these reports can include columns with different metadata from the space. Some examples include the space's status, its owner, its purpose etc.

Hierarchical spaces

Version 2 of the plugin also provides the ability to define space hierarchies by utilizing space metadata. By default, Confluence provides a flat list of spaces, but as your wiki grows this becomes harder and harder to manage. For example, note that the Atlassian wiki has a large number of spaces, many of which could be grouped together. There are eight general Atlassian spaces, two for Bamboo, six for Confluence etc.

This plugin allows you to create new parent spaces (say one called "Confluence") and to parent other spaces into it. You simply attach a single piece of space metadata to the home page of the space indicating the key of its parent space. Note that this metadata is used to visually group spaces, but does not affect the existing Confluence permissioning scheme.

For example, to specify that the current space is a child of the dev space, you would add this to the home page:

{parent-space}dev{parent-space}

This hierarchy metadata is now available to all the other metadata macros. For example, a new space-breadcrumb macro is provided to render a new hierarchical breadcrumb for your pages from this information. In the following screenshot, you are looking at a page in the Development space, which is under the "New Product" space, which itself is under the "Root Space".

The new breadcrumb can optionally drop the 'Dashboard' link so that the home page is itself a space. This can allow Confluence to lose its administrative feel, and hence be used as a website for people who don't need to know that they are accessing a wiki.

See "Setting up hierarchical spaces" for details.

Metadata reports for users, blog posts and attachments

In addition to all the new functionality around spaces, version 2 also provides useful functionality for generating reports for users, blog posts and attachments.

For users, Metadata can either be posted to a user's profile or to their personal space, and then reports generated. For example, every user in a company could be requested to attach personal metadata such as work phone, cell phone, location etc. A company directory can then be generated that includes all of this information.

See the users-report macro for details.

Similarly, there are two new reports available for blog posts and attachments. See the blog-posts-report and attachments-report macros.

Alternative report styles

The Metadata Plugin has been generalized to allow alternate report styles to be provided. As with other Confluence macros, the style parameter is used to control the rendering. THe possible values are:

Here's an example of the four different styles when showing a blog posts report:

Support for dates

In order to fully benefit from all of the new metadata, the plugin has been extended to add full support for dates. Internally metadata used to be stored as strings, but the code base has been generalized to allow for arbitrary data types. This means that metadata collections can be sorted by date, and that date fields can use a custom renderer so that the user's date and time format preferences are obeyed.

Currently dates can only come from internal metadata such as a blog's post date, the last modified date of a page etc. The plan is to add support for user-supplied date metadata shortly.

Additional internal metadata

The following internal metadata can now be accessed from reports:

Issues addressed

This release addresses a few of the issues reported against version 1:

In addition, the following general Confluence issues are addressed (some only partially):

Usage

Metadata macros

The plugin provides the following new macros:

space-metadata macro

This lets you attach a single piece of metadata to a space (see the original metadata macro for the equivalent functionality for pages).

For example:

{space-metadata:location}Bedford, MA{space-metadata}

would render simply as:

Bedford, MA

but would also attach "location" as a piece of metadata to the page. Note that as with the other metadata macros, the metadata is stored as unrendered Wiki markup. The reporting macros then render the markup into the page they are used on. This usually works very well because links, emoticons etc can be used.

If you don't want the metadata to show on the page you can use the "hidden" parameter.

{space-metadata:location|hidden=true}Bedford, MA{space-metadata}

space-metadata-list macro

This macro allows the user to attach multiple pieces of metadata to a space with one macro. The main purpose of this is to make it allow a user to add metadata more concisely and to make the Wiki markup easier to read.

The following usage:

{space-metadata-list}
|| Location | Bedford, MA |
|| Extension | x1234 |
|| Cell Phone | 617 123-4567 |
{space-metadata-list}

adds three pieces of metadata to the space, as well as rendering the following output:

An optional orientation=horizontal parameter changes the rendering to be horizontal. It will then render as follows:

space-metadata-from macro

This is a simple macro that can pull one piece of metadata from a space.

This space's owner is {space-metadata-from:Owner}

will just display as:

This space's owner is Andy Armstrong.

spaces-report macro

As with the standard metadata-report, this macro allows you to generate a report detailing the metadata attached to the matching spaces. There are a large number of internal metadata types that can be used, plus custom metadata can be attached using the space-metadata and space-metadata-list macros.

Here's a sample

{spaces-report:Space,Owner,Purpose,Last Changed By,Last Time Changed|sort=Last Time Changed desc}

which produces this result:

space-hierarchy macro

This is a very simple macro that shows the hierarchy beneath the current space.

For example:

h2. Spaces
{space-hierarchy}

shows this:

In addition, you can show the hierarchy beneath a different space using the space argument:

{space-hierarchy:space=dev}

space-breadcrumbs macro

This is a very simple macro that will add breadcrumbs to a page. In particular, it analyzes the space hierarchy information so that it includes all of the parent spaces up to the root space.

You can control the display of the breadcrumb using an optional second parameter. It can take any of the following three values:

By default, neither the 'Dashboard' link nor the 'Home' link are shown. Note that you should be careful before removing the 'Dashboard' link to make sure that all of the required functionality is available elsewhere in your site. I would suggest including the 'Dashboard' link initially until you are ready to give it up. Probably the best place to put it is in your root space, either on the home page or on an "Administration" subpage.

_Note: I plan to provide an example page that replicates all of the dashboard functionality.

users-report macro

As with the other report macros, you can generate a report of all the users, showing any metadata attached to the user. For users with personal spaces, the metadata is fetched from the space, while for regular users the metadata is fetched from their profile.

Here's a sample

{users-report:User,Location,Email,Extension,Cell Phone}

which produces this result:

blog-posts-report macro

As with the other report macros, you can generate a report of all the blog posts in a particular space. Here's some sample usages, which illustrate some of the different report styles.

h4. Table
{blog-posts-report:Title,Date,Time,Author,Comments,Time Created|sort=Time Created desc|maxResults=5}

h4. Plain list
{blog-posts-report:Title|sort=Time Created desc|maxResults=5|style=list}

h4. Unordered list
{blog-posts-report:Title|sort=Time Created desc|maxResults=5|style=ul}

h4. Ordered list
{blog-posts-report:Title|sort=Time Created desc|maxResults=5|style=ol}

and here is the resulting page:

attachments-report macro

As with the other report macros, you can generate a report of all the attachments on a single page. Here's an example usage:

{attachments-report:Attachment,Title,File Type,Size,Version,Download,Creator,Date,Time|sort=Time desc}

and here's how it looks on my home page:

Setting up hierarchical spaces

There are four steps to setting up Confluence for hierarchical spaces:

1. Create a root space
2. Create a 'Users' space
3. Add parent metadata to every other space
4. Update the breadcrumb

Create a root space

The first thing to do is to decide upon a root space. Most non-hierarchical Wiki installations would not currently have a root space, so in that case you should create one. It should probably have the same name as the Wiki itself, because it will be shown as the root of the breadcrumb. e.g. Progress Software's wiki now has a space called "Progress Wiki". Remember the space key designated for this space as that will be needed in subsequent steps.

I also recommend setting the root space to be the site home page for your site. You can set this in the Administration page, under Configuration/General Configuration.

Create a 'Users' space

In addition to having a root space, it seems to be useful to also have a users space. This is conceptually the parent space of every personal space, and helps to provide another level of structure. Note that this step is optional.

If you want a user space, you should put the following metadata into the home page (note that 'root' should be replaced with your root space's key):

{parent-space}root{parent-space}
{users-space}

You might also want to put a user report directly onto this page, assuming that you don't have many users. Something like this:

{users-report:User,Location,Email,Extension,Cell Phone}

Eventually this will provide a pageable report of all the users, but currently it shows every single user, so be careful!

Add parent metadata to every other space

Now you should go through all of your existing spaces and attach the parent space information to every page. For each space, find the space key of the parent, and then change the home page of the space to include:

{parent-space}PARENT_SPACE_KEY{parent-space}

Updating the breadcrumb

Unfortunately the plugin cannot directly change the site breadcrumb. Instead a new macro called space-breadcrumbs has been provided, and it has to be manually installed into your main site velocity template. Edit the Main Layout (found in the Administration page, under Look and Feel/Layouts) and replace the reference to:

<span class="topBarDiv"> #breadcrumbs() </span>

with:

#if ($spaceKey != '')
  $helper.renderConfluenceMacro("{space-breadcrumbs:$spaceKey:$title|dashboard}")
#else
  <span class="topBarDiv"> #breadcrumbs() </span>
#end

Some older version of Confluence call the variable $spacekey instead of $spaceKey, so the two references in the code above should be updated.

You can configure the display of the breadcrumb by specifying parameters to the space-breadcrumbs macro.

Version History

• 2.0.0 - Initial release
• 2.0.1 - Adds support for dates, blog posts and attachments and new renderers
• 2.1.0 - Compatibility with Confluence 2.7. Note I have not back-tested this for compatibility, so it probably works a long way earlier than the indicated version.

Future Improvements

I hope to have the following functionality added in time for my Confluence entry:

• Provide support for paging through large result sets
• Ability to change the titles of columns (META-39)
• Ability to use boolean logic when matching spaces, users and blog posts in reports

Slightly longer term I'm thinking about:

• Allow the space hierarchy metadata to be edited as properties, rather than entered into Wiki pages

Screenshots

Screenshots (view as slideshow)
	Users space illustrating a user-report macro		Simple page showing a hierarchy of spaces as a tree		Page showing hierarchical spaces in the breadcrumb
	A blog report showing in a number of styles		A sample attachments report		A sample spaces report