Real World Usage: The Usage & Reference Page

Below is the actual source of the page "Usage & Reference".
Using the Include Macro combined with the helper class JavaSourceLoader allows to get most of the page content directly from the sources.

usageAndReference.apt.vm:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
    ------
    Usage & Reference
    ------
    Juergen Kellerer
    ------
    2010-09-05
    ------
  
General Usage:
  
    This project builds an <<extension to {{{http://maven.apache.org/doxia/}Doxia}}>>.
    Doxia is used by <<maven-site-plugin>> to build project sites within a <Maven project>.
    The Macro defined by this extension can be used as soon as it was registered within your
    own project's <<pom.xml>> (Maven 2 - {{{http://maven.apache.org/pom.html}Project Object Model}}).
  
* Prerequisites
  
    * <<Maven>> Version >= <<2.2>>
  
    * <<JDK>> Version >= <<5>>
  
    * "<<maven-site-plugin>>" Version >= <<2.1>> (Doxia >= 1.1 is required)
  
* 1. Define the dependencies inside the "pom.xml":
  
%{include|source=pom-usage-sample.xml.vm|moduleVersion=${project.version}|highlight-lines=xp://artifactId\|//groupId\|//version}
  
    The include macro's artifact has to be added as a dependency to the site plugin's dependency list, in order
    to let <Maven Doxia> recognize it when generating a project site.\
    Any additionally required 3rd party dependencies have to be added <<here>> when using the "<<<source-class>>>" parameter
    with an implementation that depends on a certain library that is not in the default site building classpath (or project
    classpath when the goal <<<initialize>>> was called before calling the macro).
  
    <<Available Versions>>: An overview on public available versions of "${project.artifactId}" can be obtained from here:\
    {{http://mvnrepository.com/artifact/org.tinyjee.dim/doxia-include-macro}}
  
** Macro Configuration & Multi-Module Projects:
  
    With non standard path configuration or multi-module projects, the macro requires the following addition in the
    <<base POM>> to resolve the project paths correctly.
    Even though optional, it is in general advisable to include this build plugin as it improves site building stability and
    provides access to the configured POM dependencies and the resulting classpath.
  
%{include|source=pom-fix-basedir.xml.vm|moduleVersion=${project.version}}
  
    Besides configuring the macro, the build plugin sets a system property that is currently picked up by Doxia to
    set the base path for macros.\
    That works not only for this but also for all other macros that attempt to resolve resources relative to the
    given base directory.
    As a consequence of setting a system property, <parallel> site building is <unsupported>.
  
* 2. Use in XDoc or APT documents
  
** Usage within APT
  
------------------------------
%{include|source=org.tinyjee.maven.dim.IncludeMacro}
%{include|source=org/tinyjee/maven/dim/IncludeMacro.java}
%{include|source=template.html|verbatim=false}
------------------------------
  
** Usage within XDoc
  
------------------------------
<macro name="include">
  <param name="source" value="org/tinyjee/maven/dim/IncludeMacro.java"/>
  ...
</macro>
------------------------------
  
Parameter Reference:
  
    The following list shows all parameters that can be used with the Macro:    
  
%{include|source=interface-table.xdoc.vm|source-java=org.tinyjee.maven.dim.IncludeMacroSignature|since=1.0.7|version=1.0|apidocs-java=http://download.oracle.com/javase/6/docs/api/}
  
Snippet Selectors:
  
%{include|source=derived-implementations-table.xdoc.vm|source-java=org.tinyjee.maven.dim.spi.SnippetSelector|apidocs-java=http://download.oracle.com/javase/6/docs/api/}
  
Debugging / Logging:
  
    Whether debug logging is enabled when using the commandline option "<<<-X>>>" depends on the site plugin and Doxia version that
    is used (by experience, in most cases it is not).\
    Adding the commandline option "<<<-Ddim.verbose=true>>>" <<does always enable>> debug logging inside the include macro and
    allows to trace issues that may prevent content from being rendered correctly.
  
Velocity Template Processing Reference:
  
* Template Processing:
  
    Any included content is processed by the <Apache Velocity> template engine, as soon as the file name of the source
    ends with <<.vm>> or <<<source-is-template>>> is set to true. A reference on how to work with templates can be obtained from here:
    {{http://velocity.apache.org/engine/releases/velocity-1.5/user-guide.html}}
  
    In most cases the velocity engine version will be <<1.5>> and it is not affected by adding the include macro to the site
    plugin's dependencies. Instead the exact version of the engine depends on what was set inside the site plugin's dependency graph.
  
    Any parameters that were given with the macro call and any parameters that were added by RequestParameterTransformer's or source
    classes automatically turn into variables within velocity templates.
  
    <<Default Engine Configuration:>>
  
%{include|snippet=aj:..configureEngine(..)|source=org.tinyjee.maven.dim.sources.DefaultVelocityConfigurator}
  
    <<Default Context Configuration:>>
  
%{include|snippet=aj:..configureContext(..)|source=org.tinyjee.maven.dim.sources.DefaultVelocityConfigurator}
  
    The default context is configured with an instance of {{{./apidocs/org/tinyjee/maven/dim/spi/Globals.html}<$globals>}} that offers
    access to logging, base path and the ability to attach content (css, scripts and arbitrary text-based) to a page.
  
* Enabled Velocity Tools (Version 2.0):
  
    The include macro uses the following code snippet to include several additional tools that help building content with velocity:
  
%{include|snippet=aj:..configureTools(..)|source=org.tinyjee.maven.dim.sources.DefaultVelocityConfigurator}
  
    A complete reference on how to work with velocity tools can be obtained from here:
    {{http://velocity.apache.org/tools/releases/2.0/summary.html}}
  
** Macro Related Tools
  
    Besides the standard Apache tools, 'doxia-include-macro' bundles a couple of custom tools to reuse the macro features
    inside a velocity template.
  
%{include|source=derived-implementations-table.xdoc.vm|source-java=org.tinyjee.maven.dim.sources.AbstractParametricVelocityTool}
  
** Custom Tools
  
    Source classes (used via <<<source-class>>>) are free to set variables with custom implementation inside the template context
    (= request parameter map) which may be accessed and used from a velocity template in exactly the same way as tools are accessed. E.g.
    if a source class implements the code snippet "<<<put("myCallable", new Callable() \{ ... \});>>>" the template can use
    "<<<$myCallable.call()>>>" to invoke the "<<<call()>>>" method in this example and retrieve the result.
  
    In case of there's a need to adjust the tool configuration itself, look after {{{./extensionsReference.html}Extension Reference}}
    and create a macro extension that performs this task.

Used Resources:

Classes:

interface-table.xdoc.vm:

1
2
#set($nameKey = "value")
#parse("classpath:/templates/dim/constants-table.xdoc.vm")

classpath:/templates/dim/constants-table.xdoc.vm:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
<?xml version="1.0"?>
## set 'since=base-version' to enable the since column
    #if(!$nameKey) #set($nameKey="name") #end
    #if(!$labelSince) #set($labelSince = "Since") #end
    #if(!$labelParameter) #set($labelParameter="Parameter Name") #end
    #if(!$labelDescription) #set($labelDescription = "Description") #end
<document>
    <body>
        <table>
            <tr>
                <th>$labelParameter</th>
                #if($since)
                    <th>$labelSince</th>
                #end
                <th>$labelDescription</th>
            </tr>
  
            #foreach($javaElement in $constants)
                <tr>
                    <td style="white-space: nowrap; #dim_printIfDeprecated($javaElement, "text-decoration:line-through;")">
                        <code>$javaElement.get($nameKey)</code>
                    </td>
                    #if($since)
                        <td>#dim_printSince($javaElement, $since)</td>
                    #end
                    <td>
                        #dim_printIfDeprecated($javaElement, "<b><i>Deprecated:</i></b><p/>")
                        $javaElement.comment
                    </td>
                </tr>
            #end
        </table>
    </body>
</document>

derived-implementations-table.xdoc.vm:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<?xml version="1.0"?>
<document>
    <body>
        <table border="1">
            <tr>
                <th>Implementation</th>
                <th>Description</th>
            </tr>
#foreach($class in $select.derivedClasses.selectNonMatching("abstract ..*"))
    #set($deprecated = $class.get("annotations").containsKey("@Deprecated"))
            <tr>
                <td style="white-space: nowrap;#if($deprecated) text-decoration:line-through;#end">
                    #if($deprecated) <b><i>Deprecated:</i></b><p/> #end
                    <code><a href="./apidocs/${class.get("javaClass").fullyQualifiedName.replace('.', '/')}.html">
                        $class.get("javaClass").name</a></code></td>
                <td>$class.get("comment")</td>
            </tr>
#end
        </table>
    </body>
</document>