This library provides support for macros to easily add 'filtered' parameters for values like labels, pages, sorting and other common parameters.

Details

Maven 2

Dependency XML

Repository XML

Instructions

There are two main branches in this plugin: parameters and criteria.

Parameters

This branch provides helper classes for parsing and handling commonly used, but often more complex macro parameter values. This can range from a date or number format string, to sorting to a specific page or attachment, to parameters which filter based on label, space or user. It also makes in simple to allow synonyms for the same plugin (eg. 'user' or 'users')

Usage

Parameter objects are used in conjunction with the [Confluence Support Library], specifically the MacroInfo object. This object is provided for you automatically if your macro extends the ConfluenceMacro class, but you can create your own instance by providing the parameters, body and RenderContext for your macro manually. Once you have your MacroInfo instance, typical usage might be something like this:

public class MyMacro extends ConfluenceMacro {
    // Set up a parameter called 'page'
    private ContentParameter pageParam = new ContentParameter( "page" );

    public String execute( MacroInfo info ) throws MacroException {
        try {
            ContentEntityObject content = pageParam.findContent( info );
            if ( content == null )
                throw new MacroException( "Unable to find the specified page." );
            if ( content instanceof Page ) {
                // Do stuff with the Page
            } else {
                throw new MacroException( "The value provided is not a page. Please try again." );
            }
        } catch ( ParameterException e ) {
            throw new MacroException( e );
        }
    }

    // Other implementation methods go here...
}

You would then use your macro something like this:

{my-macro:page=My Page Name}

Criteria

The criteria branch provides a structure for combining chains of individual criterion, and is a bit lower-level than the parameters branch. A criterion might be a specific date, a text value, a page in Confluence or a user.

At its core, a Criterion object has a single method, matches( Object ), which simply takes an object an returns true if the object matches the requirements of the criterion implementation. For example, the BooleanCriteria simply checks if the object passed in is a Boolean, and if so, does it match the required value. Eg:

Page myPage = ???; // Get a page from somewhere...
BooleanCriterion criterion = new BooleanCriterion( true ); // The provided value must be 'true' to match successfully.
if ( criterion.matches( Boolean.valueOf( myPage.isHomePage() ) )
    // Do something...

In this example, it would obviously be simpler to just call the 'myPage.isHomePage()' method directly. Where this comes in useful when you are combining more than one criterion together to match on the same object.

Multiple Criteria

Criterion can be combined together into a single Criteria instance. Criteria itself is a sub-interface of Criterion with an additional 'addCriterion' method, but there are several concrete implementations. The most commonly used is GroupCriteria. This class lets you specify if it's an 'OR' or an 'AND' group in the constructor. Alternately, you can use the OrCriteria or AndCriteria directly.

For example, lets say you want to filter a list of Confluence content to contain only items which match all the following criteria:

• Is either a page or a news item.
• Has the 'foo' label, but not the 'bar' label.
• Is in either the 'X' space or the 'Y' space.
• Has not been deleted

Using criteria, you could do something like this:

List original = // list of content from somewhere.
List filtered = new java.util.ArrayList();

// Create the criteria
Criteria criteria = new AndCriteria();

// Content Type = Page or News
Criteria contentType = new OrCriteria();
contentType.addCriteria( new ContentTypeCriterion( "page" );
contentType.addCriteria( new ContentTypeCriterion( "news" );
criteria.addCriterion( contentType );

// Label = 'foo', but not 'bar'
criteria.addCriterion( new LabelCriterion( "foo" ) );
criteria.addCriterion( new NotCriterion( new LabelCriterion( "bar" ) );

// Space = X OR Y
Criteria spaceCriteria = new OrCriteria();
spaceCriteria.addCriterion( new SpaceKeyCriterion( "X" ) );
spaceCriteria.addCriterion( new SpaceKeyCriterion( "Y") );

criteria.addCriterion( spaceCriteria );
criteria.addCriterion( new DeletedContentCriterion( false ) );

// Now, filter the list.
Iterator i = original.iterator();
while ( i.hasNext() ) {
  Object o = i.next();
  if ( criteria.matches( o ) )
    filtered.add( o );
}
return filtered;

What makes this most useful is that Criteria are stateless, so you can create them once and reuse them across multiple filter jobs, so long as the basic criteria doesn't change. And if you want to add an extra criteria without modifying the original, just put the old and new criteria into a new AndCriteria.

The other place this is useful is when you combine it with parameters to allow the creation of complex filters from macro parameters.

Criteria Parameters

A subset of the provided parameter classes work in combination with the criteria branch to allow more complex filtering of object (thus, the name of this library). All CriterionParameter implementations will create a Criteria based on macro parameter values provided by users. These can then be easily combined with a CriterionParameterGroup and, in some cases, applied to a standard Confluence ListQuery to speed up searches even further.

The other feature common to CriterionParameter}}s is that they accept a list of values which may be prefixed with {{'+' (required) or '-' (excluded) to indicate if the item should appear. For example, "param=one, two" would be "allow 'one' or 'two'", while "param=+one, -two" would be "require 'one', and exclude 'two'". The library provides parameters for filtering Confluence content based on space, page hierarchy, label, or type, as well as filtering users by name, group or space permissions.

Below is an example macro which will output its body if the creator of the page matches the user-specified criteria:

public class CreatorFilterMacro extends ConfluenceMacro {
    private UserAccessor userAcessor;
    private CriteriaParameterGroup filters;

    public CreatorFilterMacro() {
        filters = new CriterionParameterGroup();

        filters.addParameter( new GroupMemberParameter() ); // Defaults to 'group' and 'groups'.
        filters.addParameter( new UserNameParameter() ); // Defaults to 'user' and 'users'.
    }

    public String execute( MacroInfo info ) throws MacroException {
        User creator = userAccessor.getUser( info.getContent().getCreator() );
        try {
            Criteria criteria = filters.createCriteria( critera, info.getMacroParams().getBoolean( "matchAll", true ) );
            if ( criteria.matches( creator )
                return info.getBody();
            else
                return "";
        } catch ( ParameterException e ) {
            throw new MacroException( e );
        }
    }
}

This could then be used something like this:

{creator-filter:user=j.bloggs}Only displayed if the creator was [~j.bloggs]{creator-filter}
{creator-filter:group=confluence-administrators}Only displayed if the creator was a member of 'confluence-administrators'{creator-filter}
{creator-filter:group=user=j.bloggs|+confluence-administrators, -special-users|matchAll=false}
Displayed if the creator was either [~j.bloggs] _OR_ was in the 'confluence-administrators' group but _NOT_ in the 'special-users' group
{creator-filter}