From c045e1a78a1743d12420f177ce7fe217086aafc6 Mon Sep 17 00:00:00 2001
From: vmassol <vmassol@13f79535-47bb-0310-9956-ffa450edef68>
Date: Wed, 26 Nov 2003 15:00:10 +0000
Subject: [PATCH] Start of an Aggregator authoring guide

git-svn-id: https://svn.apache.org/repos/asf/maven/maven-1/plugins/trunk@114407 13f79535-47bb-0310-9956-ffa450edef68
---
 dashboard/xdocs/authoring.xml  | 73 ++++++++++++++++++++++++++++++++++
 dashboard/xdocs/changes.xml    |  3 ++
 dashboard/xdocs/navigation.xml |  1 +
 3 files changed, 77 insertions(+)
 create mode 100644 dashboard/xdocs/authoring.xml

diff --git a/dashboard/xdocs/authoring.xml b/dashboard/xdocs/authoring.xml
new file mode 100644
index 00000000..a2fdec36
--- /dev/null
+++ b/dashboard/xdocs/authoring.xml
@@ -0,0 +1,73 @@
+<?xml version="1.0"?>
+<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]
+]]></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>
diff --git a/dashboard/xdocs/changes.xml b/dashboard/xdocs/changes.xml
index afbce242..adcae631 100644
--- a/dashboard/xdocs/changes.xml
+++ b/dashboard/xdocs/changes.xml
@@ -8,6 +8,9 @@
   <body>
 
     <release version="1.2" date="in CVS">
+      <action dev="vmassol" type="add">
+        Added tutorial on how to create custom aggregators.
+      </action>
       <action dev="vmassol" type="add">
         Added new <code>maven.dashboard.report.showempty</code> property. If
         set to false, the HTML report table will not contain entries for 
diff --git a/dashboard/xdocs/navigation.xml b/dashboard/xdocs/navigation.xml
index 42378cdb..22f99cb8 100644
--- a/dashboard/xdocs/navigation.xml
+++ b/dashboard/xdocs/navigation.xml
@@ -11,6 +11,7 @@
       <item name="Goals" href="/goals.html"/>
       <item name="Properties" href="/properties.html"/>
       <item name="Aggregators" href="/aggregators.html"/>
+      <item name="Authoring" href="/authoring.html"/>
     </menu>
     <menu name="Downloads">
       <item name="Dashboard plugin 1.0" href="http://www.ibiblio.org/maven/maven/plugins/maven-dashboard-plugin-1.0.jar"/>