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 2015/07/19 23:21:30 UTC
svn commit: r958985 [6/29] - in /websites/production/tapestry/content: ./
2009/09/13/ 2009/10/27/ 2009/11/25/ 2010/07/18/ 2010/07/24/ 2010/10/11/
2010/10/31/ 2010/11/18/ 2010/12/16/ 2010/12/17/ 2011/01/18/ 2011/03/23/
2011/03/29/ 2011/03/30/ 2011/03/31...
Modified: websites/production/tapestry/content/component-libraries.html
==============================================================================
--- websites/production/tapestry/content/component-libraries.html (original)
+++ websites/production/tapestry/content/component-libraries.html Sun Jul 19 21:21:27 2015
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css">
+ <link href='/resources/highlighter/styles/shCoreCXF.css' rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js' type='text/javascript'></script>
+ <script type="text/javascript">
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -57,16 +67,8 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><style type="text/css">/*<![CDATA[*/
-table.ScrollbarTable {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color: #f0f0f0}
-table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
-table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
-table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
-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><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>This page has not yet been fully updated for Tapestry 5.4. Things are different and simpler in 5.4 than in previous releases.</p></div></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 opt
ionally 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="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<project>
+<div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>This page has not yet been fully updated for Tapestry 5.4. Things are different and simpler in 5.4 than in previous releases.</p></div></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 (ne
eded 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">
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><project>
<modelVersion>4.0.0</modelVersion>
<groupId>org.example</groupId>
<artifactId>happylib</artifactId>
@@ -133,9 +135,9 @@ table.ScrollbarTable td.ScrollbarNextIco
<tapestry-release-version>5.4-beta-28</tapestry-release-version>
</properties>
</project>
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[package org.example.happylib.components;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.example.happylib.components;
import org.apache.tapestry5.Asset;
import org.apache.tapestry5.MarkupWriter;
@@ -145,21 +147,21 @@ import org.apache.tapestry5.ioc.annotati
public class HappyIcon
{
@Inject
- @Path("happy.jpg")
+ @Path("happy.jpg")
private Asset happyIcon;
boolean beginRender(MarkupWriter writer)
{
- writer.element("img", "src", happyIcon);
+ writer.element("img", "src", happyIcon);
writer.end();
return false;
}
}
-]]></script>
+</pre>
</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="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
- xmlns:h="tapestry-library:happy">
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd"
+ xmlns:h="tapestry-library:happy">
...
@@ -167,9 +169,9 @@ public class HappyIcon
...
</html>
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[package org.example.happylib.services;
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.example.happylib.services;
import org.apache.tapestry5.ioc.Configuration;
import org.apache.tapestry5.services.LibraryMapping;
@@ -178,12 +180,12 @@ public class HappyModule
{
public static void contributeComponentClassResolver(Configuration<LibraryMapping> configuration)
{
- configuration.add(new LibraryMapping("happy", "org.example.happylib"));
+ configuration.add(new LibraryMapping("happy", "org.example.happylib"));
}
}
-]]></script>
+</pre>
</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="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><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="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ <plugin>
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"> <plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<configuration>
@@ -194,19 +196,19 @@ public class HappyModule
</archive>
</configuration>
</plugin>
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[public static void contributeRegexAuthorizer(Configuration<String> configuration)
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public static void contributeRegexAuthorizer(Configuration<String> configuration)
{
- configuration.add("^org/example/happylib/.*\\.jpg$");
+ configuration.add("^org/example/happylib/.*\\.jpg$");
}
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[public static void contributeClasspathAssetAliasManager(MappedConfiguration<String, String> configuration)
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public static void contributeClasspathAssetAliasManager(MappedConfiguration<String, String> configuration)
{
- configuration.add("happylib/1.0", "org/example/happylib");
+ configuration.add("happylib/1.0", "org/example/happylib");
}
-]]></script>
+</pre>
</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="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
Modified: websites/production/tapestry/content/component-mixins.html
==============================================================================
--- websites/production/tapestry/content/component-mixins.html (original)
+++ websites/production/tapestry/content/component-mixins.html Sun Jul 19 21:21:27 2015
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css">
+ <link href='/resources/highlighter/styles/shCoreCXF.css' rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js' type='text/javascript'></script>
+ <script type="text/javascript">
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -59,45 +69,45 @@
<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 class="error"><span class="error">Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null</span> </div></div><p>You can think of a mixin as a kind of mashup for a component; it combines the new behavior of the mixin with the existing behavior of the component, and bundles it all in one place. Mixins may be used to add specialized validation to user input fields, dynamically modify the HTML output of a component, or to add Ajax effects and behaviors of all sorts to 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 <cod
e>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="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[<t:textfield t:id="accountName" t:mixins="Autocomplete,DefaultFromCookie" />
-]]></script>
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><t:textfield t:id="accountName" t:mixins="Autocomplete,DefaultFromCookie" />
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie"})
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie"})
private TextField userId;
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie::before:Autocomplete"})
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Component(parameters=. . .) @Mixins({"Autocomplete", "DefaultFromCookie::before:Autocomplete"})
private TextField userId;
-]]></script>
+</pre>
</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Component(parameters=. . .)
- @MixinClasses(value={Autocomplete.class, DefaultFromCookie.class}, order={"","before:AutoComplete"})
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Component(parameters=. . .)
+ @MixinClasses(value={Autocomplete.class, DefaultFromCookie.class}, order={"","before:AutoComplete"})
private TextField userId;
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[public class AutocompleteField extends TextField
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class AutocompleteField extends TextField
{
@Mixin
private Autocomplete autocompleteMixin;
. . .
}
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[public class AutocompleteField extends TextField
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class AutocompleteField extends TextField
{
- @Mixin("Autocomplete")
+ @Mixin("Autocomplete")
private Object autocompleteMixin;
. . .
}
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Component(parameters={"Autocomplete.id=auto", . . . }) @Mixins("Autocomplete", "DefaultFromCookie"})
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Component(parameters={"Autocomplete.id=auto", . . . }) @Mixins("Autocomplete", "DefaultFromCookie"})
private TextField userId;
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ public class MyMixin
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public class MyMixin
{
@BindParameter
private boolean disabled;
@@ -120,39 +130,39 @@
...
}
....
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @BindParameter("translate")
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @BindParameter("translate")
private FieldTranslator translator;
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[public class MyMixin
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class MyMixin
{
...
- @BindParameter({"value","object","source"})
+ @BindParameter({"value","object","source"})
private Object principalObject;
...
}
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Mixin("Autocomplete",order={"before:DiscardBody","after:RenderDisabled"}
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Mixin("Autocomplete",order={"before:DiscardBody","after:RenderDisabled"}
private TextField userId;
-]]></script>
+</pre>
</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="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ <input t:id="myfield" t:mixins="autocomplete::before:discardbody;after:renderdisabled,
- defaultfromcookie::before:autocomplete"/>
-]]></script>
+<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"> <input t:id="myfield" t:mixins="autocomplete::before:discardbody;after:renderdisabled,
+ defaultfromcookie::before:autocomplete"/>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Component(...)
- @Mixins("Autocomplete::before:discardbody;after:renderdisabled","DefaultFromCookie::before:autocomplete"))
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Component(...)
+ @Mixins("Autocomplete::before:discardbody;after:renderdisabled","DefaultFromCookie::before:autocomplete"))
private TextField userId;
-]]></script>
+</pre>
</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="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[ @Component(...)
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @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><p>Tapestry includes the following mixins out-of-the-box.</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"><a shape="rect" class="external-link" href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/Confirm.html">Confirm</a></td><td colspan="1" rowspan="1" class="confluenceTd">attached to a Form or link component, runs a modal-dialog to force the user to confirm the behavior.</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" rowspan="1" class="confluenceTd"><p><a shape="rect" class="external-link" href="http://tapestry.apac
he.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"><a shape="rect" class="external-link" href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/FormGroup.html">FormGroup</a></td><td colspan="1" rowspan="1" class="confluenceTd">attached to a field to render an enclosing <div> element and label</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 ele
ment 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/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" hr
ef="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 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" clas
s="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 addit
ion, 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>
+ order={"before:discardbody;after:renderdisabled","before:autocomplete")
+</pre>
+</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><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">See instructions</a>.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><a shape="rect" class="external-link" href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/Confirm.html">Confirm</a></td><td colspan="1" rowspan="1" class="confluenceTd">attached to a Form or link component, runs a modal-dialog to force the user to confirm the behavior.</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" rowspan="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"><a shape="rect" class="external-link" href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/FormGroup.html">FormGroup</a></td><td colspan="1" rowspan="1" class="confluenceTd">attached to a field to render an enclosing <div> element and label</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/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 the 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>trigge
rs 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><p><a shape="rect" class="external-link" href="http://tapestryxpath.sourceforge.net/" >Tapestry-Xpath</a> is a third-part Tapestry module that allo
ws 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-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Sun Jul 19 21:21:27 2015
@@ -75,11 +75,11 @@
</div></div><p>A component may have any number of parameters. Each parameter has a specific name, a specific Java type (which may be a primitive value), and may be <em>optional</em> or <em>required</em>.</p><p>Within a component class, parameters are declared by using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html">Parameter</a> annotation on a private field, as we'll see below.</p><p><span class="confluence-anchor-link" id="ComponentParameters-bindingparameters"></span></p><h1 id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In Tapestry, a parameter is not a slot into which data is pushed: it is a <em>connection</em> between a field of the component (marked with the @Parameter annotation) and a property or resource of the component's container. (Components can be nested, so the container can be either the page or another component.)</p><div class="navmenu" style="float:r
ight; background:white; margin:3px; padding:3px">
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Contents</b></div><div class="panelContent">
<style type="text/css">/*<![CDATA[*/
-div.rbtoc1437338466493 {padding: 0px;}
-div.rbtoc1437338466493 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1437338466493 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1437340847807 {padding: 0px;}
+div.rbtoc1437340847807 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1437340847807 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style><div class="toc-macro rbtoc1437338466493">
+/*]]>*/</style><div class="toc-macro rbtoc1437340847807">
<ul class="toc-indentation"><li><a shape="rect" href="#ComponentParameters-ParameterBindings">Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-BindingExpressions">Binding Expressions</a></li><li><a shape="rect" href="#ComponentParameters-@Parameterannotation">@Parameter annotation</a></li><li><a shape="rect" href="#ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...} syntax!</a></li><li><a shape="rect" href="#ComponentParameters-InformalParameters">Informal Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParametersAreBi-Directional">Parameters Are Bi-Directional</a></li><li><a shape="rect" href="#ComponentParameters-InheritedParameterBindings">Inherited Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter Binding Defaults</a></li><li><a shape="rect" href="#ComponentParameters-UnboundParameters">Unbound Parameters</a></li><li><a shape="rect" href="#Compon
entParameters-ParameterTypeCoercion">Parameter Type Coercion</a></li><li><a shape="rect" href="#ComponentParameters-ParameterNames">Parameter Names</a></li><li><a shape="rect" href="#ComponentParameters-DeterminingifBound">Determining if Bound</a></li><li><a shape="rect" href="#ComponentParameters-PublishingParameters">Publishing Parameters</a></li></ul>
</div>
</div></div></div> <p>The connection between a component and a property (or resource) of its container is called a <em>binding</em>. The binding is two-way: the component can read the bound property by reading its parameter field. Likewise, a component that updates its parameter field will update the bound property.</p><p>This is important in a lot of cases; for example a TextField component can read <em>and update</em> the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.</p><p>The component listed below is a looping component; it renders its body a number of times, defined by its <code>start</code> and <code>end</code> parameters (which set the boundaries of the loop). The component can update a <code>result</code> parameter bound to a property of its container; it will automatically count up or down depending on whether <code>start</code> or <code>end</code> is larger.</p><div class="code panel pdl" st
yle="border-width: 1px;"><div class="codeContent panelContent pdl">