tapestry-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > Component Report
Date Thu, 24 Feb 2011 08:48:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2036/9/12/_/styles/combined.css?spaceKey=TAPESTRY&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Component+Report">Component
Report</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~drobiazko">Igor
Drobiazko</a>
    </h4>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >    &lt;configuration&gt;
<br>        &lt;rootPackage&gt;org.example.myapp&lt;/rootPackage&gt;
<br></td></tr>
            <tr><td class="diff-unchanged" >    &lt;/configuration&gt;
<br></td></tr>
            <tr><td class="diff-unchanged" >&lt;/plugin&gt;{code} <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >Be sure the update the <span
class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">_</span>&lt;version&gt;<span
class="diff-added-chars"style="background-color: #dfd;">_</span></span> element
with the current version of the Maven plugin, and update the <span class="diff-changed-words"><span
class="diff-added-chars"style="background-color: #dfd;">_</span>&lt;rootPackage&gt;<span
class="diff-added-chars"style="background-color: #dfd;">_</span></span> element
with the value for your application (this will match the value you configure inside your [web.xml|Configuration]).
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{since:since=5.3}
<br> <br>In version 5.3 the configuration of the Maven plugin changed in a backward
incompatible way. The configuration expects the _&lt;rootPackages&gt;_ element, which
may have several _&lt;rootPackage&gt;_ elements. You should change the plugin configuration
as shown below or you can still use the 5.2.4 version of the plugin without to change anything.
<br> <br>{code:xml} <br>&lt;plugin&gt; <br>    &lt;groupId&gt;org.apache.tapestry&lt;/groupId&gt;
<br>    &lt;artifactId&gt;tapestry-component-report&lt;/artifactId&gt;
<br>    &lt;version&gt;5.3.x&lt;/version&gt; <br>    &lt;configuration&gt;
<br>        &lt;rootPackages&gt; <br>           &lt;rootPackage&gt;org.example.myapp&lt;/rootPackage&gt;
<br>           &lt;rootPackage&gt;com.acme.lib&lt;/rootPackage&gt; <br>
       &lt;/rootPackages&gt; <br>    &lt;/configuration&gt; <br>&lt;/plugin&gt;{code}
<br> <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h2. Limitations <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>The <b>Component Report</b> module lets you generate comprehensive
documentation for all the components in your module (either a component library or a Tapestry
application).</p>

<p>For each component, the inheritance, description and complete set of parameters (including
inherited parameters) are displayed.</p>

<p>The documentation is generated from a mix of JavaDoc and annotations on the classes
themselves, and from external documentation you may provide.</p>

<h2><a name="ComponentReport-ExternalDocumentation"></a>External Documentation</h2>

<p>The external documentation is optional, and takes the form of a file, stored in the
same package as the component class, with the extension ".xdoc".</p>

<p>External documentation is in the <a href="http://maven.apache.org/doxia/references/xdoc-format.html"
class="external-link" rel="nofollow">Maven XDoc Format</a>, which can be thought
of as a somewhat rigid, stripped down version of XHTML.</p>

<p>The component report will extract the content of the &lt;body&gt; element
and add it to the documentation it automatically generates. It will also copy any images (the
<tt>src</tt> attribute of any &lt;img&gt; element) to the corresponding
output folder.</p>

<p>The documentation is generated into a directory structure that mimics the package
structure; thus a link to component documentation for components in the same package is just
a link to another file (with a .html extension) in the same folder.</p>

<p>Example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;document&gt;</span>
    <span class="code-tag">&lt;body&gt;</span>
        <span class="code-tag">&lt;section name=<span class="code-quote">"Related
Components"</span>&gt;</span>
            <span class="code-tag">&lt;ul&gt;</span>
                <span class="code-tag">&lt;li&gt;</span><span class="code-tag">&lt;a
href=<span class="code-quote">"Foo.html"</span>&gt;</span>Foo<span
class="code-tag">&lt;/a&gt;</span><span class="code-tag">&lt;/ul&gt;</span>
                <span class="code-tag">&lt;li&gt;</span><span class="code-tag">&lt;a
href=<span class="code-quote">"Bar.html"</span>&gt;</span>Bar<span
class="code-tag">&lt;/a&gt;</span><span class="code-tag">&lt;/ul&gt;</span>
            <span class="code-tag">&lt;/ul&gt;</span>
         <span class="code-tag">&lt;/section&gt;</span>
         <span class="code-tag">&lt;section name=<span class="code-quote">"Examples"</span>&gt;</span>
            <span class="code-tag">&lt;p&gt;</span>The Baz component can
be used to generate a gloop style of interface:<span class="code-tag">&lt;/p&gt;</span>
            <span class="code-tag">&lt;p&gt;</span><span class="code-tag">&lt;img
src=<span class="code-quote">"baz_ref.png"</span>/&gt;</span><span
class="code-tag">&lt;/p&gt;</span>
            . . .
</pre>
</div></div>

<p>External documentation files (the .xdoc files and any related image files) can be
either on the Java main path (i.e., src/main/java) or on the resources path (src/main/resources).
At this time, you should place them under src/main/java such that the files are not packaged
in your library JAR or application WAR.</p>

<h2><a name="ComponentReport-GeneratingtheReport"></a>Generating the Report</h2>

<p>Just add the following to the reporting/plugins section of your POM:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.tapestry<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>tapestry-component-report<span
class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>5.0.x<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;configuration&gt;</span>
        <span class="code-tag">&lt;rootPackage&gt;</span>org.example.myapp<span
class="code-tag">&lt;/rootPackage&gt;</span>
    <span class="code-tag">&lt;/configuration&gt;</span>
<span class="code-tag">&lt;/plugin&gt;</span></pre>
</div></div>

<p>Be sure the update the <em>&lt;version&gt;</em> element with
the current version of the Maven plugin, and update the <em>&lt;rootPackage&gt;</em>
element with the value for your application (this will match the value you configure inside
your <a href="/confluence/display/TAPESTRY/Configuration" title="Configuration">web.xml</a>).</p>



<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Added in
5.3</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;"></div>

<p>In version 5.3 the configuration of the Maven plugin changed in a backward incompatible
way. The configuration expects the <em>&lt;rootPackages&gt;</em> element,
which may have several <em>&lt;rootPackage&gt;</em> elements. You should
change the plugin configuration as shown below or you can still use the 5.2.4 version of the
plugin without to change anything.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml"><span class="code-tag">&lt;plugin&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.tapestry<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>tapestry-component-report<span
class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>5.3.x<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;configuration&gt;</span>
        <span class="code-tag">&lt;rootPackages&gt;</span>
           <span class="code-tag">&lt;rootPackage&gt;</span>org.example.myapp<span
class="code-tag">&lt;/rootPackage&gt;</span>
           <span class="code-tag">&lt;rootPackage&gt;</span>com.acme.lib<span
class="code-tag">&lt;/rootPackage&gt;</span>
        <span class="code-tag">&lt;/rootPackages&gt;</span>
    <span class="code-tag">&lt;/configuration&gt;</span>
<span class="code-tag">&lt;/plugin&gt;</span></pre>
</div></div>


<h2><a name="ComponentReport-Limitations"></a>Limitations</h2>

<p>There is no ability to generate parameters for base classes from another library;
the tools assume that the components are entirely self-contained within the current model.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Component+Report">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=23338469&revisedVersion=4&originalVersion=3">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message