You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2014/01/18 19:21:06 UTC
svn commit: r894647 [3/9] - in /websites/production/tapestry/content: ./
cache/
Modified: websites/production/tapestry/content/component-libraries.html
==============================================================================
--- websites/production/tapestry/content/component-libraries.html (original)
+++ websites/production/tapestry/content/component-libraries.html Sat Jan 18 18:21:05 2014
@@ -29,6 +29,7 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -77,22 +78,8 @@ table.ScrollbarTable td.ScrollbarParent
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}
-/*]]>*/</style><div class="Scrollbar"><table class="ScrollbarTable"><tr><td colspan="1" rowspan="1" class="ScrollbarPrevIcon"><a shape="rect" href="supporting-informal-parameters.html"><img align="middle" border="0" src="https://cwiki.apache.org/confluence/images/icons/back_16.gif" width="16" height="16"></a></td><td colspan="1" rowspan="1" class="ScrollbarPrevName" width="33%"><a shape="rect" href="supporting-informal-parameters.html">Supporting Informal Parameters</a> </td><td colspan="1" rowspan="1" class="ScrollbarParent" width="33%"><sup><a shape="rect" href="cookbook.html"><img align="middle" border="0" src="https://cwiki.apache.org/confluence/images/icons/up_16.gif" width="8" height="8"></a></sup><a shape="rect" href="cookbook.html">Cookbook</a></td><td colspan="1" rowspan="1" class="ScrollbarNextName" width="33%"> <a shape="rect" href="switching-cases.html">Switching Cases</a></td><td colspan="1" rowspan="1" class="ScrollbarNextIcon"><a shape="rect" href="switching
-cases.html"><img align="middle" border="0" src="https://cwiki.apache.org/confluence/images/icons/forwd_16.gif" width="16" height="16"></a></td></tr></table></div>
-<p></p>
-
-<h1 id="ComponentLibraries-CreatingComponentLibraries">Creating Component Libraries</h1>
-
-<p>Nearly every Tapestry application includes a least a couple of custom components, specific to the application. What's exciting about Tapestry is how easy it is to package components for reuse across many applications ... and the fact that applications using a component library need no special configuration.</p>
-
-<p>A Tapestry component library consists of components (and optionally mixins, pages and component base classes). In addition, a component library will have a module that can define new services (needed by the components) or configure other services present in Tapestry. Finally, components can be packaged with <em>assets</em>: resources such as images, stylesheets and JavaScript libraries that need to be provided to the client web browser.</p>
-
-<p>We're going to create a somewhat insipid component that displays a large happy face icon.</p>
-
-<p>Tapestry doesn't mandate that you use any build system, but we'll assume for the moment that you are using Maven 2. In that case, you'll have a pom.xml file something like the following:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<project>
+/*]]>*/</style><div class="Scrollbar"><table class="ScrollbarTable"><tr><td colspan="1" rowspan="1" class="ScrollbarPrevIcon"><a shape="rect" href="supporting-informal-parameters.html"><img align="middle" border="0" src="https://cwiki.apache.org/confluence/images/icons/back_16.gif" width="16" height="16"></a></td><td colspan="1" rowspan="1" class="ScrollbarPrevName" width="33%"><a shape="rect" href="supporting-informal-parameters.html">Supporting Informal Parameters</a> </td><td colspan="1" rowspan="1" class="ScrollbarParent" width="33%"><sup><a shape="rect" href="cookbook.html"><img align="middle" border="0" src="https://cwiki.apache.org/confluence/images/icons/up_16.gif" width="8" height="8"></a></sup><a shape="rect" href="cookbook.html">Cookbook</a></td><td colspan="1" rowspan="1" class="ScrollbarNextName" width="33%"> <a shape="rect" href="switching-cases.html">Switching Cases</a></td><td colspan="1" rowspan="1" class="ScrollbarNextIcon"><a shape="rect" href="switching
-cases.html"><img align="middle" border="0" src="https://cwiki.apache.org/confluence/images/icons/forwd_16.gif" width="16" height="16"></a></td></tr></table></div><h1 id="ComponentLibraries-CreatingComponentLibraries">Creating Component Libraries</h1><p>Nearly every Tapestry application includes a least a couple of custom components, specific to the application. What's exciting about Tapestry is how easy it is to package components for reuse across many applications ... and the fact that applications using a component library need no special configuration.</p><p>A Tapestry component library consists of components (and optionally mixins, pages and component base classes). In addition, a component library will have a module that can define new services (needed by the components) or configure other services present in Tapestry. Finally, components can be packaged with <em>assets</em>: resources such as images, stylesheets and JavaScript libraries that need to be provided to the client
web browser.</p><p>We're going to create a somewhat insipid component that displays a large happy face icon.</p><p>Tapestry doesn't mandate that you use any build system, but we'll assume for the moment that you are using Maven 2. In that case, you'll have a pom.xml file something like the following:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<project>
<modelVersion>4.0.0</modelVersion>
<groupId>org.example</groupId>
<artifactId>happylib</artifactId>
@@ -160,25 +147,8 @@ table.ScrollbarTable td.ScrollbarNextIco
</properties>
</project>
]]></script>
-</div></div>
-
-<p>You will need to modify the Tapestry release version number ("5.2.0" in the listing above) to reflect the current version of Tapestry when you create your component library.</p>
-
-<p>We'll go into more detail about the relevant portions of this POM in the later sections.</p>
-
-<h2 id="ComponentLibraries-Step1:Chooseabasepackagename">Step 1: Choose a base package name</h2>
-
-<p>Just as with Tapestry applications, Tapestry component libraries should have a <em>unique</em> base package name. In this example, we'll use <code>org.examples.happylib</code>.</p>
-
-<p>As with an application, we'll follow the conventions: we'll place the module for this library inside the services package, and place pages and components under their respective packages.</p>
-
-<h2 id="ComponentLibraries-Step2:Createyourpagesand/orcomponents">Step 2: Create your pages and/or components</h2>
-
-<p>Our component is very simple:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>HappyIcon.java</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-package org.example.happylib.components;
+</div></div><p>You will need to modify the Tapestry release version number ("5.2.0" in the listing above) to reflect the current version of Tapestry when you create your component library.</p><p>We'll go into more detail about the relevant portions of this POM in the later sections.</p><h2 id="ComponentLibraries-Step1:Chooseabasepackagename">Step 1: Choose a base package name</h2><p>Just as with Tapestry applications, Tapestry component libraries should have a <em>unique</em> base package name. In this example, we'll use <code>org.examples.happylib</code>.</p><p>As with an application, we'll follow the conventions: we'll place the module for this library inside the services package, and place pages and components under their respective packages.</p><h2 id="ComponentLibraries-Step2:Createyourpagesand/orcomponents">Step 2: Create your pages and/or components</h2><p>Our component is very simple:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeade
r pdl" style="border-bottom-width: 1px;"><b>HappyIcon.java</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[package org.example.happylib.components;
import org.apache.tapestry5.Asset;
import org.apache.tapestry5.MarkupWriter;
@@ -200,32 +170,8 @@ public class HappyIcon
}
}
]]></script>
-</div></div>
-
-<p>HappyIcon appears inside the components sub-package. The happyIcon field is injected with the the Asset for the file <code>happy.jpg</code>. The path specified with the @Path annotation is relative to the <code>HappyIcon.class</code> file; it should be stored in the project under <code>src/main/resources/org/example/happylib/components</code>.</p>
-
-<p>Tapestry ensures that the <code>happy.jpg</code> asset can be accessed from the client web browser; the src attribute of the <img> tag will be a URL that directly accesses the image file ... there's no need to unpackage the <code>happy.jpg</code> file. This works for any asset file stored under the library's root package.</p>
-
-<p>This component renders out an <code><img></code> tag for the icon.</p>
-
-<p>Often, a component library will have many different components, or even pages.</p>
-
-<h2 id="ComponentLibraries-Step3:Chooseavirtualfoldername">Step 3: Choose a virtual folder name</h2>
-
-<p>In Tapestry, components that have been packaged in a library are referenced using a virtual folder name. It's effectively as if the application had a new root-level folder containing the components.</p>
-
-<p>In our example, we'll use "happy" as the folder name. That means the application can include the HappyIcon component in the template using any of the following, which are all equivalent:</p>
-
-<ul><li><t:happy.happyicon/></li><li><t:happy.icon/></li><li><img t:type="happy.happyicon"/></li><li><img t:type="happy/icon"/></li></ul>
-
-
-<p>Why "icon" vs. "happyicon"? Tapestry notices that the folder name, "happy" is a prefix or suffix of the class name ("HappyIcon") and creates an alias that strips off the prefix (or suffix). To Tapestry, they are completely identical: two different aliases for the same component class name.</p>
-
-<p>The above naming is somewhat clumsy, and can be improved by introducing an additional namespace into the template:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
+</div></div><p>HappyIcon appears inside the components sub-package. The happyIcon field is injected with the the Asset for the file <code>happy.jpg</code>. The path specified with the @Path annotation is relative to the <code>HappyIcon.class</code> file; it should be stored in the project under <code>src/main/resources/org/example/happylib/components</code>.</p><p>Tapestry ensures that the <code>happy.jpg</code> asset can be accessed from the client web browser; the src attribute of the <img> tag will be a URL that directly accesses the image file ... there's no need to unpackage the <code>happy.jpg</code> file. This works for any asset file stored under the library's root package.</p><p>This component renders out an <code><img></code> tag for the icon.</p><p>Often, a component library will have many different components, or even pages.</p><h2 id="ComponentLibraries-Step3:Chooseavirtualfoldername">Step 3: Choose a virtual folder name</h2><p>In Tapestry, components that h
ave been packaged in a library are referenced using a virtual folder name. It's effectively as if the application had a new root-level folder containing the components.</p><p>In our example, we'll use "happy" as the folder name. That means the application can include the HappyIcon component in the template using any of the following, which are all equivalent:</p><ul><li><t:happy.happyicon/></li><li><t:happy.icon/></li><li><img t:type="happy.happyicon"/></li><li><img t:type="happy/icon"/></li></ul><p>Why "icon" vs. "happyicon"? Tapestry notices that the folder name, "happy" is a prefix or suffix of the class name ("HappyIcon") and creates an alias that strips off the prefix (or suffix). To Tapestry, they are completely identical: two different aliases for the same component class name.</p><p>The above naming is somewhat clumsy, and can be improved by introducing an additional namespace into the template:</p><div class="code panel pdl" style="border-width: 1px;
"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
xmlns:h="tapestry-library:happy">
...
@@ -235,19 +181,8 @@ public class HappyIcon
...
</html>
]]></script>
-</div></div>
-
-<p>The special namespace mapping for sets up namespace prefix "h:" to mean the same as "happy/". It then becomes possible to reference components within the happy virtual folder directly.</p>
-
-<h2 id="ComponentLibraries-Step4:Configurethevirtualfolder">Step 4: Configure the virtual folder</h2>
-
-<p>Tapestry needs to know where to search for your component class. This is accomplished in your library's IoC module class, by making a <em>contribution</em> to the ComponentClassResolver service configuration.</p>
-
-<p>At application startup, Tapestry will read the library module along with all other modules and configure the ComponentClassResolver service using information in the module:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>HappyModule.java</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-package org.example.happylib.services;
+</div></div><p>The special namespace mapping for sets up namespace prefix "h:" to mean the same as "happy/". It then becomes possible to reference components within the happy virtual folder directly.</p><h2 id="ComponentLibraries-Step4:Configurethevirtualfolder">Step 4: Configure the virtual folder</h2><p>Tapestry needs to know where to search for your component class. This is accomplished in your library's IoC module class, by making a <em>contribution</em> to the ComponentClassResolver service configuration.</p><p>At application startup, Tapestry will read the library module along with all other modules and configure the ComponentClassResolver service using information in the module:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>HappyModule.java</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[package org.example.happylib.services;
import org.apache.tapestry5.ioc.Configuration;
import org.apache.tapestry5.services.LibraryMapping;
@@ -260,27 +195,14 @@ public class HappyModule
}
}
]]></script>
-</div></div>
-
-<p>The ComponentClassResolver service is responsible for mapping libraries to packages; it takes as a contribution a collection of these LibraryMapping objects. Every module may make its own contribution to the ComponentClassResolver service, mapping its own package ("org.example.happylib") to its own folder ("happy").</p>
-
-<p>This module class is also where you would define new services that can be accessed by your components (or other parts of the application).</p>
-
- <div class="aui-message warning shadowed information-macro">
+</div></div><p>The ComponentClassResolver service is responsible for mapping libraries to packages; it takes as a contribution a collection of these LibraryMapping objects. Every module may make its own contribution to the ComponentClassResolver service, mapping its own package ("org.example.happylib") to its own folder ("happy").</p><p>This module class is also where you would define new services that can be accessed by your components (or other parts of the application).</p> <div class="aui-message warning shadowed information-macro">
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
<p>It is possible to add a mapping for "core", the core library for Tapestry components; all the built-in Tapestry components (TextField, BeanEditForm, Grid, etc.) are actually in the core library. When Tapestry doesn't find a component in your application, it next searches inside the "core" library. Contributing an additional package as "core" simply extends the number of packages searched for core components (it doesn't replace Tapestry's default package, org.apache.tapestry5.corelib). Adding to "core" is sometimes reasonable, if you ensure that there is virtually no chance of a naming conflict (via different modules contributing packages to core with conflicting class names).</p>
</div>
</div>
-
-
-<h2 id="ComponentLibraries-Step5:Configurethemoduletoautoload">Step 5: Configure the module to autoload</h2>
-
-<p>For Tapestry to load your module at application startup, it is necessary to put an entry in the JAR manifest. This is taken care of in the pom.xml above:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml (partial)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
- <plugin>
+<h2 id="ComponentLibraries-Step5:Configurethemoduletoautoload">Step 5: Configure the module to autoload</h2><p>For Tapestry to load your module at application startup, it is necessary to put an entry in the JAR manifest. This is taken care of in the pom.xml above:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml (partial)</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<configuration>
@@ -292,45 +214,19 @@ public class HappyModule
</configuration>
</plugin>
]]></script>
-</div></div>
-
-<h2 id="ComponentLibraries-Step6:ExtendingClientAccess">Step 6: Extending Client Access</h2>
-
-<p>As of Tapestry 5.2, a new step is needed: extending access for the assets. This is accomplished in your library's module class, HappyModule:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public static void contributeRegexAuthorizer(Configuration<String> configuration)
+</div></div><h2 id="ComponentLibraries-Step6:ExtendingClientAccess">Step 6: Extending Client Access</h2><p>As of Tapestry 5.2, a new step is needed: extending access for the assets. This is accomplished in your library's module class, HappyModule:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public static void contributeRegexAuthorizer(Configuration<String> configuration)
{
configuration.add("^org/example/happylib/.*\\.jpg$");
}
]]></script>
-</div></div>
-
-<p>This contribution uses a regular expression to identify that any resource on the classpath under the org/example/happylib folder with a jpg extension is allowed. If you had a mix of different image types, you could replace jpg with (jpg|gif|png).</p>
-
-<h2 id="ComponentLibraries-Step7:VersioningAssets">Step 7: Versioning Assets</h2>
-
-<p>Classpath assets, those packaged in JAR files (such as the happy.jpg asset) are retrieved by the client web browser using a URL that reflects the package name. Tapestry users a special virtual folder, /assets, under the context folder for this purpose.</p>
-
-<p>The image file here is exposed to the web browser via the URL /happyapp/assets/org/example/happylib/components/happy.jpg (this assumes that the application was deployed as happyapp.war).</p>
-
-<p>Tapestry uses a far-future expiration date for classpath assets; this allows browsers to aggressively cache the file, but in Tapestry 5.1 and earlier this causes a problem when a later version of the library changes the file. This is discussed in detail in <a shape="rect" class="external-link" href="http://developer.yahoo.com/performance/rules.html#expires" >Yahoo's Performance Best Practices</a>.</p>
-
-<p>To handle this problem in Tapestry 5.1 and earlier, you should map your library assets to a versioned folder. This can be accomplished using another contribution from the HappyModule, this time to the ClasspathAssetAliasManager service whose configuration maps a virtual folder underneath /assets to a package:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public static void contributeClasspathAssetAliasManager(MappedConfiguration<String, String> configuration)
+</div></div><p>This contribution uses a regular expression to identify that any resource on the classpath under the org/example/happylib folder with a jpg extension is allowed. If you had a mix of different image types, you could replace jpg with (jpg|gif|png).</p><h2 id="ComponentLibraries-Step7:VersioningAssets">Step 7: Versioning Assets</h2><p>Classpath assets, those packaged in JAR files (such as the happy.jpg asset) are retrieved by the client web browser using a URL that reflects the package name. Tapestry users a special virtual folder, /assets, under the context folder for this purpose.</p><p>The image file here is exposed to the web browser via the URL /happyapp/assets/org/example/happylib/components/happy.jpg (this assumes that the application was deployed as happyapp.war).</p><p>Tapestry uses a far-future expiration date for classpath assets; this allows browsers to aggressively cache the file, but in Tapestry 5.1 and earlier this causes a problem when a later version of
the library changes the file. This is discussed in detail in <a shape="rect" class="external-link" href="http://developer.yahoo.com/performance/rules.html#expires" >Yahoo's Performance Best Practices</a>.</p><p>To handle this problem in Tapestry 5.1 and earlier, you should map your library assets to a versioned folder. This can be accomplished using another contribution from the HappyModule, this time to the ClasspathAssetAliasManager service whose configuration maps a virtual folder underneath /assets to a package:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public static void contributeClasspathAssetAliasManager(MappedConfiguration<String, String> configuration)
{
configuration.add("happylib/1.0", "org/example/happylib");
}
]]></script>
-</div></div>
-
-<p>With this in place, and the library and applications rebuilt and redeployed, the URL for happy.jpg becomes /happyapp/assets/happylib/1.0/components/happy.jpg. This is shorter, but also incorporates a version number ("1.0") that can be changed in a later release.</p>
-
-
+</div></div><p>With this in place, and the library and applications rebuilt and redeployed, the URL for happy.jpg becomes /happyapp/assets/happylib/1.0/components/happy.jpg. This is shorter, but also incorporates a version number ("1.0") that can be changed in a later release.</p>
<div class="aui-message hint shadowed information-macro">
<p class="title">Added in 5.2</p>
@@ -342,13 +238,8 @@ public static void contributeClasspathAs
</div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;">
-
<p>In version 5.2 and later, Tapestry automatically creates a mapping for assets inside your JAR. In the above example, the icon image will be exposed as <code>/assets/</code><em>application version</em><code>/happy/components/happy.jpg</code> (the application version number is incorporated into the URL). The "happy" portion is a virtual folder that maps to the library's root package (as folder <code>org/example/happylib</code> on the Java classpath). The application version is a configurable value.</p>
-</div>
-
-<h2 id="ComponentLibraries-Conclusion">Conclusion</h2>
-
-<p>That's it! Autoloading plus the virtual folders for components and for assets takes care of all the issues related to components. Just build your JARs, setup the JAR Manifest, and drop them into your applications.</p></div>
+</div><h2 id="ComponentLibraries-Conclusion">Conclusion</h2><p>That's it! Autoloading plus the virtual folders for components and for assets takes care of all the issues related to components. Just build your JARs, setup the JAR Manifest, and drop them into your applications.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/component-mixins.html
==============================================================================
--- websites/production/tapestry/content/component-mixins.html (original)
+++ websites/production/tapestry/content/component-mixins.html Sat Jan 18 18:21:05 2014
@@ -29,6 +29,7 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -69,9 +70,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><p>A <strong>Component Mixin</strong> is a way to supplement an existing Tapestry component with additional behavior. </p>
-
-<div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
+<div id="ConfluenceContent"><p>A <strong>Component Mixin</strong> is a way to supplement an existing Tapestry component with additional behavior.</p><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -96,7 +95,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="javascript.html">JavaScript</a>
+ <a shape="rect" href="component-templates.html">Component Templates</a>
</div>
@@ -114,92 +113,29 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-templates.html">Component Templates</a>
+ <a shape="rect" href="javascript.html">JavaScript</a>
</div>
</li></ul>
-</div>
-
-<p>You can think of a mixin as a kind of mashup for a component; it combines the behavior of the mixin with the behavior of the component, and bundles it all in one place. Mixins may be used to add validation to user input fields, or to add Ajax effects and behaviors to all sorts of components.</p>
-
-<p>Tapestry comes with several mixins, such as the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html">Autocomplete mixin</a> which adds autocomplete behavior to an ordinary TextField Component. In addition, you can easily create your own.</p>
-
-<h2 id="ComponentMixins-MixinClasses">Mixin Classes</h2>
-
-<p>Mixin classes are stored in the <code>mixins</code> sub-package of your application, below the application (or library) root package. This parallels where your component and page classes are stored.</p>
-
-<p>Other than that, mixin classes are the same as any other component class.</p>
-
-<h2 id="ComponentMixins-MixinLimitations">Mixin Limitations</h2>
-
-<p>Currently, mixins are allowed to do anything a component can do, including having parameters and render phase methods.</p>
-
-<p>Mixins may not have a template. They integrate with the component strictly in terms of invoking render phase methods.</p>
-
-<p>Mixins may have persistent fields, but currently, this is not implemented perfectly (there is a potential for a name clash between a mixin and the component or another mixin). Use persistent fields with mixins with care ... or better yet, delegate persistence to the container using parameters.</p>
-
-<p>Mixins may not, themselves, have mixins.</p>
-
-<h2 id="ComponentMixins-UsingMixins">Using Mixins</h2>
-
-<p>Mixins are used in two different scenarios: <em>Instance mixins</em> and <em>Implementation mixins</em>.</p>
-
-<h3 id="ComponentMixins-InstanceMixins">Instance Mixins</h3>
-
-<p>An instance mixin is a mixin applied to a specific <em>instance</em> of a component. This can be done in the <a shape="rect" href="component-templates.html">component template</a> with the <code>mixins</code> attribute of the component tag. This is a comma-separated list of mixin names.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<t:textfield t:id="accountName" t:mixins="Autocomplete,DefaultFromCookie" />
+</div><p>You can think of a mixin as a kind of mashup for a component; it combines the behavior of the mixin with the behavior of the component, and bundles it all in one place. Mixins may be used to add validation to user input fields, or to add Ajax effects and behaviors to all sorts of components.</p><p>Tapestry comes with several mixins, such as the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html">Autocomplete mixin</a> which adds autocomplete behavior to an ordinary TextField Component. In addition, you can easily create your own.</p><h2 id="ComponentMixins-MixinClasses">Mixin Classes</h2><p>Mixin classes are stored in the <code>mixins</code> sub-package of your application, below the application (or library) root package. This parallels where your component and page classes are stored.</p><p>Other than that, mixin classes are the same as any other component class.</p><h2 id="ComponentM
ixins-MixinLimitations">Mixin Limitations</h2><p>Currently, mixins are allowed to do anything a component can do, including having parameters and render phase methods.</p><p>Mixins may not have a template. They integrate with the component strictly in terms of invoking render phase methods.</p><p>Mixins may have persistent fields, but currently, this is not implemented perfectly (there is a potential for a name clash between a mixin and the component or another mixin). Use persistent fields with mixins with care ... or better yet, delegate persistence to the container using parameters.</p><p>Mixins may not, themselves, have mixins.</p><h2 id="ComponentMixins-UsingMixins">Using Mixins</h2><p>Mixins are used in two different scenarios: <em>Instance mixins</em> and <em>Implementation mixins</em>.</p><h3 id="ComponentMixins-InstanceMixins">Instance Mixins</h3><p>An instance mixin is a mixin applied to a specific <em>instance</em> of a component. This can be done in the <a shape="rect" h
ref="component-templates.html">component template</a> with the <code>mixins</code> attribute of the component tag. This is a comma-separated list of mixin names.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<t:textfield t:id="accountName" t:mixins="Autocomplete,DefaultFromCookie" />
]]></script>
-</div></div>
-
-<p>Alternately, when the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation is used to define the component type, you may specify the mixins in two ways:</p>
-
-<ul><li>The @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Mixins.html">Mixins</a> annotation allows a list of mixin names to be specified.</li><li>The @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinClasses.html">MixinClasses</a> annotation allows a set of mixin classes to be specified directly.</li></ul>
-
-
-<p>The former is often less verbose, and allows core mixins to be overridden with application-specific mixins. The later format is more specific and more refactor-safe (renaming a mixin class will rename the entry in the MixinClasses annotation as well).</p>
-
-<p>Example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-
- @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie"})
+</div></div><p>Alternately, when the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation is used to define the component type, you may specify the mixins in two ways:</p><ul><li>The @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Mixins.html">Mixins</a> annotation allows a list of mixin names to be specified.</li><li>The @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinClasses.html">MixinClasses</a> annotation allows a set of mixin classes to be specified directly.</li></ul><p>The former is often less verbose, and allows core mixins to be overridden with application-specific mixins. The later format is more specific and more refactor-safe (renaming a mixin class will rename the entry in the MixinClasses annotation as well).</p>
<p>Example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie"})
private TextField userId;
]]></script>
-</div></div>
-
-<p>This example defines a component of type TextField and mixes in the <em>hypothetical</em> Autocomplete and DefaultFromCookie mixins.</p>
-
-<h3 id="ComponentMixins-OrderingtheMixins">Ordering the Mixins</h3>
-<p>With @Mixins and @MixinClasses annotations, we can order the list of mixins, by adding a constraint.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie::before:Autocomplete"})
+</div></div><p>This example defines a component of type TextField and mixes in the <em>hypothetical</em> Autocomplete and DefaultFromCookie mixins.</p><h3 id="ComponentMixins-OrderingtheMixins">Ordering the Mixins</h3><p>With @Mixins and @MixinClasses annotations, we can order the list of mixins, by adding a constraint.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie::before:Autocomplete"})
private TextField userId;
]]></script>
-</div></div>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Component(parameters=. . .)
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Component(parameters=. . .)
@MixinClasses(value={Autocomplete.class, DefaultFromCookie.class}, order={"","before:AutoComplete"})
private TextField userId;
]]></script>
-</div></div>
-
-<p>You can specify many contraints for a mixin. You just need to separate them with a ";".</p>
-
-<h3 id="ComponentMixins-ImplementationMixins">Implementation Mixins</h3>
-
-<p>Implementation mixins, mixins which apply to all instances of a component, are added using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Mixin.html">Mixin</a> annotation. This annotation defines a field that will contain the mixin instance.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class AutocompleteField extends TextField
+</div></div><p>You can specify many contraints for a mixin. You just need to separate them with a ";".</p><h3 id="ComponentMixins-ImplementationMixins">Implementation Mixins</h3><p>Implementation mixins, mixins which apply to all instances of a component, are added using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Mixin.html">Mixin</a> annotation. This annotation defines a field that will contain the mixin instance.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class AutocompleteField extends TextField
{
@Mixin
private Autocomplete autocompleteMixin;
@@ -207,15 +143,8 @@ public class AutocompleteField extends T
. . .
}
]]></script>
-</div></div>
-
-<p>Often, the type of the field is the exact mixin class to be instantiated.</p>
-
-<p>In other cases, such as when the field's type is an interface or a base class, the value attribute of the annotation will be used to determine the mixin class name:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class AutocompleteField extends TextField
+</div></div><p>Often, the type of the field is the exact mixin class to be instantiated.</p><p>In other cases, such as when the field's type is an interface or a base class, the value attribute of the annotation will be used to determine the mixin class name:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class AutocompleteField extends TextField
{
@Mixin("Autocomplete")
private Object autocompleteMixin;
@@ -223,36 +152,12 @@ public class AutocompleteField extends T
. . .
}
]]></script>
-</div></div>
-
-<h2 id="ComponentMixins-MixinParameters">Mixin Parameters</h2>
-
-<p>Mixins are allowed to have parameters, just like components.</p>
-
-<p>When binding parameters (either in the template, or using the parameters attribute of the Component annotation), Tapestry will match each parameter name against the parameters defined by each class (which is to say, the component and each mixin).</p>
-
-<p>If the component and a mixin both define a parameter with the same name, then the component wins: the component's parameter will be bound, and the mixin's parameter will be unbound.</p>
-
-<p>Alternately, you may prefix the name of the parameter with the <em>unqualified</em> name of the Mixin class; this eliminates the ambiguity. Example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Component(parameters={"Autocomplete.id=auto", . . . }) @Mixins("Autocomplete", "DefaultFromCookie"})
+</div></div><h2 id="ComponentMixins-MixinParameters">Mixin Parameters</h2><p>Mixins are allowed to have parameters, just like components.</p><p>When binding parameters (either in the template, or using the parameters attribute of the Component annotation), Tapestry will match each parameter name against the parameters defined by each class (which is to say, the component and each mixin).</p><p>If the component and a mixin both define a parameter with the same name, then the component wins: the component's parameter will be bound, and the mixin's parameter will be unbound.</p><p>Alternately, you may prefix the name of the parameter with the <em>unqualified</em> name of the Mixin class; this eliminates the ambiguity. Example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Component(parameters={"Autocomplete.id=auto", . . . }) @Mixins("Autocomplete", "DefaultFromCookie"})
private TextField userId;
]]></script>
-</div></div>
-
-<p>If the component and a mixin both supports informal parameters, the mixin will receive the all the unqualified informal parameters. If more than one Mixin supports informal parameters the results are undefined. </p>
-
-<p>Note that when you define an implementation mixin, and the mixin has parameters, there's no way to bind those parameters as part of the <em>implementation</em>. They simply become available when the composite component (including the mixin) is introduced into a page.</p>
-
-<h2 id="ComponentMixins-Bindingtheparameterofthecorecomponent">Binding the parameter of the core component</h2>
-
-<p>It is sometimes desirable to access the current value of a parameter defined in the component associated with the mixin. For example: normally, when the textfield component is marked disabled, it renders a text field with a disabled attribute, but you want it to output the (plaintext) value when disabled. A mixin for this purpose would need access to at least the disabled, and value parameters, and possibly the translate parameter (for a client-side representation). You can access the disabled parameter via @InjectContainer and checking isDisabled on the field, but textfield currently provides no access to value or translate. In this case, you can bind the core-component parameter using the @BindParameter annotation:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- public class MyMixin
+</div></div><p>If the component and a mixin both supports informal parameters, the mixin will receive the all the unqualified informal parameters. If more than one Mixin supports informal parameters the results are undefined.</p><p>Note that when you define an implementation mixin, and the mixin has parameters, there's no way to bind those parameters as part of the <em>implementation</em>. They simply become available when the composite component (including the mixin) is introduced into a page.</p><h2 id="ComponentMixins-Bindingtheparameterofthecorecomponent">Binding the parameter of the core component</h2><p>It is sometimes desirable to access the current value of a parameter defined in the component associated with the mixin. For example: normally, when the textfield component is marked disabled, it renders a text field with a disabled attribute, but you want it to output the (plaintext) value when disabled. A mixin for this purpose would need access to at least the disabled, and
value parameters, and possibly the translate parameter (for a client-side representation). You can access the disabled parameter via @InjectContainer and checking isDisabled on the field, but textfield currently provides no access to value or translate. In this case, you can bind the core-component parameter using the @BindParameter annotation:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ public class MyMixin
{
@BindParameter
private boolean disabled;
@@ -276,24 +181,12 @@ public class AutocompleteField extends T
}
....
]]></script>
-</div></div>
-
-<p>Tapestry will "link" the disabled, translate, and value fields above to parameters of the same name on the associated component. The fields are not parameters to the mixin, but local copies of the component parameter. They are cached only if the associated component parameter is cached. They are read-write, and Tapestry handles synchronizing the value between mixins and the associated component such that even with a cached parameter, components and mixins will share the same value for a given parameter/bound-parameter during render. Only declared parameters of the associated components may be bound.</p>
-
-<p>By default, Tapestry will bind the parameter with the same name as the field. You can explicitly declare the parameter to bind via the value attribute:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @BindParameter("translate")
+</div></div><p>Tapestry will "link" the disabled, translate, and value fields above to parameters of the same name on the associated component. The fields are not parameters to the mixin, but local copies of the component parameter. They are cached only if the associated component parameter is cached. They are read-write, and Tapestry handles synchronizing the value between mixins and the associated component such that even with a cached parameter, components and mixins will share the same value for a given parameter/bound-parameter during render. Only declared parameters of the associated components may be bound.</p><p>By default, Tapestry will bind the parameter with the same name as the field. You can explicitly declare the parameter to bind via the value attribute:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @BindParameter("translate")
private FieldTranslator translator;
]]></script>
-</div></div>
-
-<p>In same cases, a mixin will be used on different components using different names for a similar parameter type. For instance, BeanEditor has an "object" parameter; most form fields have a "value" parameter, and Grid has a "source" parameter. These parameters have different names but share the feature of being the "principle" parameter on which the components are acting. A mixin useable by all three components can specify multiple potential parameter values to bind. The first value that matches a declared parameter of the associated component will be used:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class MyMixin
+</div></div><p>In same cases, a mixin will be used on different components using different names for a similar parameter type. For instance, BeanEditor has an "object" parameter; most form fields have a "value" parameter, and Grid has a "source" parameter. These parameters have different names but share the feature of being the "principle" parameter on which the components are acting. A mixin useable by all three components can specify multiple potential parameter values to bind. The first value that matches a declared parameter of the associated component will be used:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class MyMixin
{
...
@BindParameter({"value","object","source"})
@@ -301,65 +194,27 @@ public class MyMixin
...
}
]]></script>
-</div></div>
-
-<p>"MyMixin" can be used on a textfield (principalObject is bound to "value"), on BeanEditor or BeanDisplay (principalObject is bound to "object"), or on Grid or Loop (principalObject is bound to "source").</p>
-
-<h2 id="ComponentMixins-RenderPhaseOrdering">Render Phase Ordering</h2>
-
-<p>All mixins for a component execute their render phase methods <em>before</em> the component's render phase methods for most phases. However, in the later phases (AfterRender, CleanupRender) the order of executing is reversed.</p>
-
-<p>Exception: A mixins whose class is annotated with @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html">MixinAfter</a> is ordered <em>after</em> the component, not before.</p>
-
-<p>Withing a given phase and class (@MixinAfter vs. mixin before), mixin ordering is determined by the ordering constraints specified in the mixin definitions. The constraint definitions follow the same conventions as <a shape="rect" href="ordering-by-constraints.html">ordered service configurations</a>. How you specify the constraints depends on how the mixin is specified.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As an Implementation Mixin</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Mixin("Autocomplete",order={"before:DiscardBody","after:RenderDisabled"}
+</div></div><p>"MyMixin" can be used on a textfield (principalObject is bound to "value"), on BeanEditor or BeanDisplay (principalObject is bound to "object"), or on Grid or Loop (principalObject is bound to "source").</p><h2 id="ComponentMixins-RenderPhaseOrdering">Render Phase Ordering</h2><p>All mixins for a component execute their render phase methods <em>before</em> the component's render phase methods for most phases. However, in the later phases (AfterRender, CleanupRender) the order of executing is reversed.</p><p>Exception: A mixins whose class is annotated with @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html">MixinAfter</a> is ordered <em>after</em> the component, not before.</p><p>Withing a given phase and class (@MixinAfter vs. mixin before), mixin ordering is determined by the ordering constraints specified in the mixin definitions. The constraint definitions follow the same convent
ions as <a shape="rect" href="ordering-by-constraints.html">ordered service configurations</a>. How you specify the constraints depends on how the mixin is specified.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As an Implementation Mixin</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Mixin("Autocomplete",order={"before:DiscardBody","after:RenderDisabled"}
private TextField userId;
]]></script>
-</div></div>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As a Template-specifed Instance Mixin</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
- <input t:id="myfield" t:mixins="autocomplete::before:discardbody;after:renderdisabled,
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As a Template-specifed Instance Mixin</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[ <input t:id="myfield" t:mixins="autocomplete::before:discardbody;after:renderdisabled,
defaultfromcookie::before:autocomplete"/>
]]></script>
-</div></div>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As a @Mixins-specified Instance Mixin</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Component(...)
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As a @Mixins-specified Instance Mixin</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Component(...)
@Mixins("Autocomplete::before:discardbody;after:renderdisabled","DefaultFromCookie::before:autocomplete"))
private TextField userId;
]]></script>
-</div></div>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As a @MixinClasses-specified Instance Mixins</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
- @Component(...)
+</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>As a @MixinClasses-specified Instance Mixins</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Component(...)
@MixinClasses(value={Autocomplete.class,DefaultFromCookie.class},
order={"before:discardbody;after:renderdisabled","before:autocomplete")
]]></script>
-</div></div>
-
-<p>The ordering is always specified in terms of the order of the "forward" rendering process (setupRender, beginRender, etc.). When the "reverse" rendering phases (afterRender, etc.) occur, the mixin order is exactly reversed. Mixins which have no associated ordering constraints will be ordered in a manner which is consistent with the specified constraints for all other mixins, but is otherwise unspecified.</p>
-
-
-<h2 id="ComponentMixins-AvailableMixins">Available Mixins</h2>
-
-Tapestry includes the following mixins out-of-the-box.
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html">Autocomplete</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> modifies a text field to provide for auto-completion of text using values retrieved from the server as the user types. <a shape="rect" href="ajax-and-zones.html#AjaxandZones-autocomplete">See instructions</a>. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/DiscardBody.html">DiscardBody</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> discards a component's body. Returns false from the BeforeRenderBody phase, which prevents the rendering of the body. </p></td></tr><tr><td colspan="1" rowsp
an="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/FormFieldFocus.html">FormFieldFocus</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> instruments the outer Form on which component the focus should be activated. Replaced by OverrideFieldFocus starting in Tapestry 5.4. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/NotEmpty.html">NotEmpty</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> attaches to any component that renders an element. At the end of the render, if the element is empty, then a non-breaking space (&nbsp;) is injected into the element. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/a
pidocs/org/apache/tapestry5/corelib/mixins/OverrideFieldFocus.html">OverrideFieldFocus</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> when attached to a form field, causes that field to gain focus. Starting in Tapestry 5.4, this supersedes FormFieldFocus. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderClientId.html">RenderClientId</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> forces a client element to render its client id by ensuring that "getClientId" is called. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderDisabled.html">RenderDisabled</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> renders an "disabled" attribute if the c
ontaining component is disabled </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderInformals.html">RenderInformals</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> renders out all informal parameters, at the end of the BeginRender phase. This mixin can be used with components that render a single tag inside the BeginRender phase. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderNotification.html">RenderNotification</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> triggers event notifications to identify when it enters the BeginRender and AfterRender render phases </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class=
"external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/TriggerFragment.html">TriggerFragment</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> when applied to a Checkbox or Radio component, links the input field and a FormFragment, making the field control the client-side visibility of the FormFragment </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/ZoneRefresh.html">ZoneRefresh</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> periodically refreshes a Zone by triggering an event on the server using ajax requests. </p></td></tr></tbody></table></div>
-
-<p>In addition, the following mixins are available from other sources:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/creatingmixins1" >ClickOnce</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> From JumpStart, a mixin to apply to a submit button, ensuring it can't be double-clicked </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://wiki.apache.org/tapestry/Tapestry5AndJavaScriptExplained">Confirm</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> Adds a JavaScript <em>confirm</em> prompt to any link </p></td></tr></tbody></table></div>
-
-
-<h2 id="ComponentMixins-AdditionalTools">Additional Tools</h2>
+</div></div><p>The ordering is always specified in terms of the order of the "forward" rendering process (setupRender, beginRender, etc.). When the "reverse" rendering phases (afterRender, etc.) occur, the mixin order is exactly reversed. Mixins which have no associated ordering constraints will be ordered in a manner which is consistent with the specified constraints for all other mixins, but is otherwise unspecified.</p><h2 id="ComponentMixins-AvailableMixins">Available Mixins</h2><p>Tapestry includes the following mixins out-of-the-box.
-<p><a shape="rect" class="external-link" href="http://tapestryxpath.sourceforge.net/" >Tapestry-Xpath</a> is a third-part Tapestry module that allows XPath traversal of the Tapestry (server-side) DOM, which can be extremely useful in certain mixins.</p></div>
+</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html">Autocomplete</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> modifies a text field to provide for auto-completion of text using values retrieved from the server as the user types. <a shape="rect" href="ajax-and-zones.html#AjaxandZones-autocomplete">See instructions</a>. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/DiscardBody.html">DiscardBody</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> discards a component's body. Returns false from the BeforeRenderBody phase, which prevents the rendering of the body. </p></td></tr><tr><td colspan="1" r
owspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/FormFieldFocus.html">FormFieldFocus</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> instruments the outer Form on which component the focus should be activated. Replaced by OverrideFieldFocus starting in Tapestry 5.4. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/NotEmpty.html">NotEmpty</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> attaches to any component that renders an element. At the end of the render, if the element is empty, then a non-breaking space (&nbsp;) is injected into the element. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/curre
nt/apidocs/org/apache/tapestry5/corelib/mixins/OverrideFieldFocus.html">OverrideFieldFocus</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> when attached to a form field, causes that field to gain focus. Starting in Tapestry 5.4, this supersedes FormFieldFocus. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderClientId.html">RenderClientId</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> forces a client element to render its client id by ensuring that "getClientId" is called. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderDisabled.html">RenderDisabled</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> renders an "disabled" attribute if t
he containing component is disabled </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderInformals.html">RenderInformals</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> renders out all informal parameters, at the end of the BeginRender phase. This mixin can be used with components that render a single tag inside the BeginRender phase. </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/RenderNotification.html">RenderNotification</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> triggers event notifications to identify when it enters the BeginRender and AfterRender render phases </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" cl
ass="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/TriggerFragment.html">TriggerFragment</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> when applied to a Checkbox or Radio component, links the input field and a FormFragment, making the field control the client-side visibility of the FormFragment </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/ZoneRefresh.html">ZoneRefresh</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> periodically refreshes a Zone by triggering an event on the server using ajax requests. </p></td></tr></tbody></table></div><p>In addition, the following mixins are available from other sources:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class
="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/javascript/creatingmixins1" >ClickOnce</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>From JumpStart, a mixin to apply to a submit button, ensuring it can't be double-clicked</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://wiki.apache.org/tapestry/Tapestry5AndJavaScriptExplained">Confirm</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Adds a JavaScript <em>confirm</em> prompt to any link</p></td></tr></tbody></table></div><h2 id="ComponentMixins-AdditionalTools">Additional Tools</h2><p><a shape="rect" class="external-link" href="http://tapestryxpath.sourceforge.net/" >Tapestry-Xpath</a> is a third-part Tapestry module that allows XPath traversal of the Tapestry (server-side) DOM, which can be extremely useful in certain mixins.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/component-report.html
==============================================================================
--- websites/production/tapestry/content/component-report.html (original)
+++ websites/production/tapestry/content/component-report.html Sat Jan 18 18:21:05 2014
@@ -29,6 +29,7 @@
<link href='http://cxf.apache.org/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
<script src='http://cxf.apache.org/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='http://cxf.apache.org/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -69,27 +70,8 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><p>The <strong>Component Report</strong> 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 id="ComponentReport-ExternalDocumentation">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 shape="rect" class="external-link" href="http://maven.apache.org/doxia/references/xdoc-format.html">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 <body> element and add it to the documentation it automatically generates. It will also copy any images (the <code>src</code> attribute of any <img> 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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<document>
+<div id="ConfluenceContent"><p>The <strong>Component Report</strong> 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 id="ComponentReport-ExternalDocumentation">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 shape="rect" class="external-link" href="http://maven.apache.org/doxia/references/xdoc-format.html">Maven XDoc Format</a>, which can be thought of as a somewhat rigid, stripped down version of XHTML.</p><p>The component repor
t will extract the content of the <body> element and add it to the documentation it automatically generates. It will also copy any images (the <code>src</code> attribute of any <img> 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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<document>
<body>
<section name="Related Components">
<ul>
@@ -102,17 +84,8 @@
<p><img src="baz_ref.png"/></p>
. . .
]]></script>
-</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 id="ComponentReport-GeneratingtheReport">Generating the Report</h2>
-
-<p>Just add the following to the reporting/plugins section of your POM:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<plugin>
+</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 id="ComponentReport-GeneratingtheReport">Generating the Report</h2><p>Just add the following to the reporting/plugins section of your POM:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<plugin>
<groupId>org.apache.tapestry</groupId>
<artifactId>tapestry-component-report</artifactId>
<version>5.0.x</version>
@@ -120,11 +93,7 @@
<rootPackage>org.example.myapp</rootPackage>
</configuration>
</plugin>]]></script>
-</div></div>
-
-<p>Be sure the update the <em><version></em> element with the current version of the Maven plugin, and update the <em><rootPackage></em> element with the value for your application (this will match the value you configure inside your <a shape="rect" href="configuration.html">web.xml</a>).</p>
-
-
+</div></div><p>Be sure the update the <em><version></em> element with the current version of the Maven plugin, and update the <em><rootPackage></em> element with the value for your application (this will match the value you configure inside your <a shape="rect" href="configuration.html">web.xml</a>).</p>
<div class="aui-message hint shadowed information-macro">
<p class="title">Added in 5.3</p>
@@ -136,13 +105,8 @@
</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><rootPackages></em> element, which may have several <em><rootPackage></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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[
-<plugin>
+<p> </p></div><p>In version 5.3 the configuration of the Maven plugin changed in a backward incompatible way. The configuration expects the <em><rootPackages></em> element, which may have several <em><rootPackage></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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<plugin>
<groupId>org.apache.tapestry</groupId>
<artifactId>tapestry-component-report</artifactId>
<version>5.3.x</version>
@@ -153,12 +117,7 @@
</rootPackages>
</configuration>
</plugin>]]></script>
-</div></div>
-
-
-<h2 id="ComponentReport-Limitations">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></div><h2 id="ComponentReport-Limitations">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>
<div class="clearer"></div>