<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 -->

<document>

  <properties>
    <title>Maven Dashboard aggregator creation guide</title>
    <author email="vmassol@apache.org">Vincent Massol</author>
  </properties>

  <body>
    <section name="How to create a custom aggregator">
      <p>
        The dashboard plugin supports custom aggregators. This page is a 
        tutorial explaining how to create a custom aggregator.
      </p>
      <p>
        An aggregator is a Jelly script that you plug in the dashboard plugin.
        This Jelly script is called on each Maven subproject to extract a 
        single piece of data (ex: number of checkstyle errors, Clover test 
        coverage percentage, etc).
      </p>
      <subsection name="Step 1: Creating a Jelly script">
       <p>
         The Jelly script must output the aggregator data for a project. 
         For example:
       </p>
<source><![CDATA[
<?xml version="1.0"?>
<j:jelly xmlns:j="jelly:core" xmlns:x="jelly:xml" xmlns:u="jelly:util">
  <u:file var="artifactAsFile" 
      name="${maven.dashboard.aggregator.cserrors.artifact}"/>
  <j:choose>
    <j:when test="${artifactAsFile.exists()}">
      <x:parse var="doc" xml="${artifactAsFile}"/>
      <x:expr select="count($doc//error[@severity = 'error'])"/>
    </j:when>
    <j:otherwise>
      <j:expr value="-"/>
    </j:otherwise>
  </j:choose>
</j:jelly>]]></source>
        <p>
          Note that the Jelly script has access to all of the Dashboard plugin
          properties.
        </p>
      </subsection>
      <subsection name="Step 2: Configuring the dashboard">
        <p>
          Add the following properties to your master project's 
          <code>project.properties</code>:
        </p>
<source><![CDATA[
# Properties for my custom aggregator
maven.dashboard.aggregator.[aggregator name].script = [location of my custom jelly script]
maven.dashboard.aggregator.[aggregator name].artifact = [Location of artifacts from which to extract data]
maven.dashboard.aggregator.[aggregator name].label = [Label to display in report]
maven.dashboard.aggregator.[aggregator name].goal = [Goal to call that generates the artifact above]
maven.dashboard.aggregator.[aggregator name].description = [Aggregator description legend]
]]></source>
        <p>
          In order to use your aggregator in the dashboard report, you need to 
          add it to the list of aggregators by adding the following property in
          your <code>project.properties</code>:
        </p>
<source><![CDATA[
maven.dashboard.aggregators = [aggregator name],[other aggregators to use]
]]></source>        
      </subsection>
      <subsection name="Step 3: Tips">
        <p>
          If there is no existing goal that generates the data you need, create
          a custom goal in your top level <code>maven.xml</code>. Make sure your
          subprojects inherit from this top level project (so that 
          <code>maven.xml</code> is inherited).
        </p>
        <p>
          If you think your aggregator could be useful to others, feel free to
          donate it to the Maven project.
        </p>
      </subsection>
    </section>
 </body>
</document>
