Modified: websites/production/tapestry/content/autoloading-modules.html
==============================================================================
--- websites/production/tapestry/content/autoloading-modules.html (original)
+++ websites/production/tapestry/content/autoloading-modules.html Wed Sep 20
12:29:16 2017
@@ -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>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -36,26 +46,13 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
-
-</div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
-<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form>
-
-</div>
-
-
-<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
-
-
-<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Autoloading Modules</h1></div>
-
-</div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Autoloading Modules</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,8 +64,11 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Autoloading of
modules</strong> allows new features to be added to an application just by
"dropping in" a JAR that contains a module: the services in the module are
automatically integrated into the overall service registry, along with any
configuration or other supporting code and resources.</p><p>An example of this
is the <a href="uploading-files.html">tapestry-upload</a> library, which
introduces an Upload component, along with supporting services related to
handling file upload requests.</p><p>The core Tapestry IoC module is
automatically included. When using the Tapestry web framework, the core
Tapestry module is also included, as is an optional per-application module,
plus any autoloaded modules.</p><p>Module autoloading isn't 100% free ... you
must tell Tapestry IoC where the modules to load are located, which can be done
via a Manifest file entry, or via an annotation.</p><h1
id="AutoloadingModules-JARManifestEntries">J
AR Manifest Entries</h1><p>When setting up the registry, Tapestry can
automatically locate modules packaged into JARs. It does this by searching for
a particular global manifest entry.</p><p>The manifest entry name is
"Tapestry-Module-Classes". The value is a comma-separated list of fully
qualified class names of module classes (this allows a single JAR to contain
multiple, related modules). Whitespace is ignored.</p><p>Example:</p><parameter
ac:name="language">text</parameter><plain-text-body>Manifest-Version: 1.0
-Tapestry-Module-Classes: org.example.mylib.LibModule,
org.example.mylib.internal.InternalModule</plain-text-body><p>If you are using
Maven 2, then getting these entries into your JAR's manifest is as simple as
some configuration in your pom.xml:</p><parameter
ac:name="language">xml</parameter><plain-text-body><project>
+ <div id="ConfluenceContent"><p><strong>Autoloading of
modules</strong> allows new features to be added to an application just by
"dropping in" a JAR that contains a module: the services in the module are
automatically integrated into the overall service registry, along with any
configuration or other supporting code and resources.</p><p>An example of this
is the <a href="uploading-files.html">tapestry-upload</a> library, which
introduces an Upload component, along with supporting services related to
handling file upload requests.</p><p>The core Tapestry IoC module is
automatically included. When using the Tapestry web framework, the core
Tapestry module is also included, as is an optional per-application module,
plus any autoloaded modules.</p><p>Module autoloading isn't 100% free ... you
must tell Tapestry IoC where the modules to load are located, which can be done
via a Manifest file entry, or via an annotation.</p><h1
id="AutoloadingModules-JARManifestEntries">J
AR Manifest Entries</h1><p>When setting up the registry, Tapestry can
automatically locate modules packaged into JARs. It does this by searching for
a particular global manifest entry.</p><p>The manifest entry name is
"Tapestry-Module-Classes". The value is a comma-separated list of fully
qualified class names of module classes (this allows a single JAR to contain
multiple, related modules). Whitespace is ignored.</p><p>Example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: text; gutter: false; theme: Default"
style="font-size:12px;">Manifest-Version: 1.0
+Tapestry-Module-Classes: org.example.mylib.LibModule,
org.example.mylib.internal.InternalModule</pre>
+</div></div><p>If you are using Maven 2, then getting these entries into your
JAR's manifest is as simple as some configuration in your pom.xml:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><project>
. . .
<build>
<plugins>
@@ -87,11 +87,14 @@ Tapestry-Module-Classes: org.example.myl
</plugins>
</build>
. . .
-</project></plain-text-body><p>More details are provided in the <a
class="external-link"
href="http://maven.apache.org/guides/mini/guide-manifest.html";>Maven Manifest
Guide</a>.</p><h1 id="AutoloadingModules-SubModuleAnnotation">SubModule
Annotation</h1><p>Often, you will have several different modules working
together that should all be loaded as a unit.</p><p>One approach is to update
the module ids into the manifest, as shown in the previous
extension.</p><p>This can become tedious, and somewhat brittle in the face of
refactorings (such as renaming of classes or packages).</p><p>A better
alternative is the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/SubModule.html";>SubModule
annotation</a> annotation.</p><p>The value for this annotation is a list of
<em>additional</em> classes to be treated as module classes, exactly as if they
were identified in the manifest. Despite the name, there is no hierarchy of mo
dules in Tapestry IoC.</p><p>Example:</p><parameter
ac:name="language">java</parameter><plain-text-body>@SubModule(
+</project></pre>
+</div></div><p>More details are provided in the <a class="external-link"
href="http://maven.apache.org/guides/mini/guide-manifest.html";>Maven Manifest
Guide</a>.</p><h1 id="AutoloadingModules-SubModuleAnnotation">SubModule
Annotation</h1><p>Often, you will have several different modules working
together that should all be loaded as a unit.</p><p>One approach is to update
the module ids into the manifest, as shown in the previous
extension.</p><p>This can become tedious, and somewhat brittle in the face of
refactorings (such as renaming of classes or packages).</p><p>A better
alternative is the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/SubModule.html";>SubModule
annotation</a> annotation.</p><p>The value for this annotation is a list of
<em>additional</em> classes to be treated as module classes, exactly as if they
were identified in the manifest. Despite the name, there is no hierarchy of
modules in Tapestry IoC.
</p><p>Example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@SubModule(
{ InternalTransformModule.class })
public final class InternalModule
{
- . . .</plain-text-body><p>In general, your should only need to identify a
single module in the JAR manifest, and make use of @SubModule to pull in any
additional module classes.</p><p> </p><p></p></div>
+ . . .</pre>
+</div></div><p>In general, your should only need to identify a single module
in the JAR manifest, and make use of @SubModule to pull in any additional
module classes.</p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/bean-validation.html
==============================================================================
--- websites/production/tapestry/content/bean-validation.html (original)
+++ websites/production/tapestry/content/bean-validation.html Wed Sep 20
12:29:16 2017
@@ -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/shBrushJScript.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -72,7 +82,41 @@
<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">
</div></div>
<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div><p><strong>Bean validation</strong> involves validating
user input using Tapestry's built-in support for the <a class="external-link"
href="http://jcp.org/en/jsr/detail?id=303"; rel="nofollow">JSR 303 Bean
Validation API</a>.</p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "validation" and space =
currentSpace()</parameter></rich-text-body><p>Tapestry has always provided a
powerful non-JSR 303 validation mechanism (see <a
href="forms-and-validation.html">Forms and Validation</a>). Among other things
this mechanism allows you to annotate your domain model classes with the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tape
stry5/beaneditor/Validate.html">@Validate</a> annotation. However, this
annotation is problematic if your domain model is used in non-Tapestry
applications as well as in Tapestry applications. Your non-Tapestry application
becomes dependent on <em>tapestry5-annotations</em> module. To make your domain
model independent from Tapestry you can use the <a class="external-link"
href="http://jcp.org/en/jsr/detail?id=303"; rel="nofollow">JSR 303: Bean
Validation</a> instead. This library provides integration between Tapestry and
JSR-303.</p><h2 id="BeanValidation-Configuration">Configuration</h2><p>The
Tapestry's JSR 303 - Bean Validation Library is responsible for configuring and
bootstrapping the <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a> for you. In order to use this library you have to
choose an implementation of the JSR-303 specification like <a
class="external-link" href="https://www.hibernate
.org/412.html" rel="nofollow">Hibernate Validator 4.x</a>. This library is not
specific to any implementation of JSR-303 and will work with any implementation
of your choice.</p><h3
id="BeanValidation-BootstrapingtheBeanValidator">Bootstraping the Bean
Validator</h3><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html";>BeanValidatorSource</a>
service is responsible for bootstrapping the <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a>. You can contribute a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorConfigurer.html";>BeanValidatorConfigurer</a>
to the configuration of this service in order to participate on the
configuration of <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel=
"nofollow">Validator</a>.</p><parameter
ac:name="language">java</parameter><plain-text-body>@Contribute(BeanValidatorSource.class)
+<p> </p></div><p><strong>Bean validation</strong> involves validating
user input using Tapestry's built-in support for the <a class="external-link"
href="http://jcp.org/en/jsr/detail?id=303"; rel="nofollow">JSR 303 Bean
Validation API</a>.</p><div class="aui-label" style="float:right"
title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="bean-validation.html">Bean Validation</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="forms-and-validation.html">Forms and
Validation</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>Tapestry has always provided a powerful non-JSR 303 validation mechanism
(see <a href="forms-and-validation.html">Forms and Validation</a>). Among
other things this mechanism allows you to annotate your domain model classes
with the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>@Validate</a>
annotation. However, this annotation is problematic if your domain model is
used in non-Tapestry applications as well as in Tapestry applications. Your
non-Tapestry application becomes dependent on <em>tapestry5-annotations</em>
module. To make your domain model independent from Tapestry you can use the <a
class="external-link" href="http://jcp.org/en/jsr/detail?id=303";
rel="nofollow">JSR 303: Bean Validation</a> instead. This library provides
integration between Tapestry and JSR-303.</p><h2
id="BeanValidation-Configuration">Configuration</h2><p>The Tapestry's JSR 303 -
Bean Validation Library is responsible for con
figuring and bootstrapping the <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a> for you. In order to use this library you have to
choose an implementation of the JSR-303 specification like <a
class="external-link" href="https://www.hibernate.org/412.html";
rel="nofollow">Hibernate Validator 4.x</a>. This library is not specific to any
implementation of JSR-303 and will work with any implementation of your
choice.</p><h3 id="BeanValidation-BootstrapingtheBeanValidator">Bootstraping
the Bean Validator</h3><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html";>BeanValidatorSource</a>
service is responsible for bootstrapping the <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a>. You can contribute a <a class="external-link"
href="htt
p://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorConfigurer.html">BeanValidatorConfigurer</a>
to the configuration of this service in order to participate on the
configuration of <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a>.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Contribute(BeanValidatorSource.class)
public static void
provideBeanValidatorConfigurer(OrderedConfiguration<BeanValidatorConfigurer>
configuration)
{
configuration.add("MyConfigurer", new BeanValidatorConfigurer()
@@ -82,7 +126,9 @@ public static void provideBeanValidatorC
configuration.ignoreXmlConfiguration();
}
});
-}</plain-text-body><h3 id="BeanValidation-Validationgroups">Validation
groups</h3><p>In JSR-303 validation groups are used to define a subset of the
constraints validated at a given time. If no validation group is specified the
<a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/groups/Default.html";
rel="nofollow">Default</a> group is taken. By default, Tapestry passes only
this group to <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a>. You can tell Tapestry to pass more groups by
contributing group classes into the configuration of the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html";>BeanValidatorSource</a>
service.</p><h2 id="BeanValidation-Usage">Usage</h2><h3
id="BeanValidation-ValidatingInputFields">Validating Input Fields</h3><p>Once
you included this library and its depe
ndencies into your web app, you may use the JSR-303 annotations to validate
the user's input.</p><parameter
ac:name="language">java</parameter><plain-text-body>public class Login
+}</pre>
+</div></div><h3 id="BeanValidation-Validationgroups">Validation
groups</h3><p>In JSR-303 validation groups are used to define a subset of the
constraints validated at a given time. If no validation group is specified the
<a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/groups/Default.html";
rel="nofollow">Default</a> group is taken. By default, Tapestry passes only
this group to <a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/Validator.html";
rel="nofollow">Validator</a>. You can tell Tapestry to pass more groups by
contributing group classes into the configuration of the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/BeanValidatorSource.html";>BeanValidatorSource</a>
service.</p><h2 id="BeanValidation-Usage">Usage</h2><h3
id="BeanValidation-ValidatingInputFields">Validating Input Fields</h3><p>Once
you included this library and its dependencie
s into your web app, you may use the JSR-303 annotations to validate the
user's input.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class Login
{
@NotNull
@Size(max=10)
@@ -99,7 +145,9 @@ public static void provideBeanValidatorC
{
// Login the user here
}
-}</plain-text-body><p>You can even mix JSR-303 annotations and Tapestry's @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation.</p><parameter
ac:name="language">java</parameter><plain-text-body>public class Login
+}</pre>
+</div></div><p>You can even mix JSR-303 annotations and Tapestry's @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class Login
{
@NotNull
@Validate("maxlength=10")
@@ -116,7 +164,9 @@ public static void provideBeanValidatorC
{
// Login the user here
}
-}</plain-text-body><p>Next you have to pass the object to validate into the
Form's <em>validate</em> parameter. In the following example the Form's fields
are bound to the properties of the <em>Login</em> page. That's why we pass
<em>this</em>, thus the page instance, to the  <em>validate</em>
parameter.</p><parameter
ac:name="language">xml</parameter><plain-text-body><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
+}</pre>
+</div></div><p>Next you have to pass the object to validate into the Form's
<em>validate</em> parameter. In the following example the Form's fields are
bound to the properties of the <em>Login</em> page. That's why we pass
<em>this</em>, thus the page instance, to the  <em>validate</em>
parameter.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<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">
<body>
<t:form validate="this">
@@ -135,7 +185,9 @@ public static void provideBeanValidatorC
</p>
<t:form>
</body>
-</html></plain-text-body><p>Since the <em>validate</em> parameter
defaults to the container of the Form component, we could also remove
<em>validate="this"</em> in the example above.</p><h3
id="BeanValidation-ValidatingBeanswithBeanEditForm">Validating Beans with
BeanEditForm</h3><p>If you use the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/BeanEditForm.html";>BeanEditForm</a>
component it's even easier to validate your beans. The only thing you have to
do is to annotate your beans with JSR-303 annotations. If you are migrating
from Tapestry's built-in validation mechanism to JSR-303 Bean Validation, you
don't have to change your template at all.</p><parameter
ac:name="language">java</parameter><plain-text-body>public class User
+</html></pre>
+</div></div><p>Since the <em>validate</em> parameter defaults to the container
of the Form component, we could also remove <em>validate="this"</em> in the
example above.</p><h3
id="BeanValidation-ValidatingBeanswithBeanEditForm">Validating Beans with
BeanEditForm</h3><p>If you use the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/BeanEditForm.html";>BeanEditForm</a>
component it's even easier to validate your beans. The only thing you have to
do is to annotate your beans with JSR-303 annotations. If you are migrating
from Tapestry's built-in validation mechanism to JSR-303 Bean Validation, you
don't have to change your template at all.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class User
{
@NotNull
private String userName;
@@ -145,7 +197,9 @@ public static void provideBeanValidatorC
private String password;
...
-}</plain-text-body><h3 id="BeanValidation-Client-sideValidation">Client-side
Validation</h3><p>Unfortunately JSR-303 doesn’t cover client-side
validation, so web frameworks supporting this JSR need to come up with
proprietary client-side solutions. Tapestry provides client-side validation for
the following JSR-303 constraints:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>JSR-303 constraint</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry' JavaScript function</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Max.html";
rel="nofollow">@Max</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.maxnumber</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/ap
i/javax/validation/constraints/Min.html" rel="nofollow">@Min</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.minnumber</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/NotNull.html";
rel="nofollow">@NotNull</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.notnull</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Null.html";
rel="nofollow">@Null</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.isnull</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Pattern.html";
rel="nofollow">@Pattern</a></p></td><td colspan="1" rowspan="1" clas
s="confluenceTd"><p>Tapestry.Validator.pattern</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Size.html";
rel="nofollow">@Size</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.size</p></td></tr></tbody></table></div><h3
id="BeanValidation-Providingownclient-sidevalidators">Providing own
client-side validators</h3><p>Now let's see how to provide own client-side
validation for JSR-303 constraints. Imagine you created the following
constraint definition. The server-side implementation of the constraint is
implemented by RangeValidator. I suppose you are familiar with JSR-303, so I
don’t explain how to implement RangeValidator.</p><parameter
ac:name="language">java</parameter><plain-text-body>@Documented
+}</pre>
+</div></div><h3 id="BeanValidation-Client-sideValidation">Client-side
Validation</h3><p>Unfortunately JSR-303 doesn’t cover client-side
validation, so web frameworks supporting this JSR need to come up with
proprietary client-side solutions. Tapestry provides client-side validation for
the following JSR-303 constraints:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>JSR-303 constraint</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry' JavaScript function</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Max.html";
rel="nofollow">@Max</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.maxnumber</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax
/validation/constraints/Min.html" rel="nofollow">@Min</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.minnumber</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/NotNull.html";
rel="nofollow">@NotNull</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.notnull</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Null.html";
rel="nofollow">@Null</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.isnull</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Pattern.html";
rel="nofollow">@Pattern</a></p></td><td colspan="1" rowspan="1" class="conf
luenceTd"><p>Tapestry.Validator.pattern</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://download.oracle.com/javaee/6/api/javax/validation/constraints/Size.html";
rel="nofollow">@Size</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Tapestry.Validator.size</p></td></tr></tbody></table></div><h3
id="BeanValidation-Providingownclient-sidevalidators">Providing own
client-side validators</h3><p>Now let's see how to provide own client-side
validation for JSR-303 constraints. Imagine you created the following
constraint definition. The server-side implementation of the constraint is
implemented by RangeValidator. I suppose you are familiar with JSR-303, so I
don’t explain how to implement RangeValidator.</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Documented
@Constraint(validatedBy = RangeValidator.class)
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@@ -159,18 +213,23 @@ public @interface Range {
Class[] groups() default {};
Class[] payload() default {};
-}</plain-text-body><p>To provide client-side validation of a constraint you
have to add a JavaScript function to the built-in <em>Tapestry.Validator</em>
JavaScript-object. The function should contain exactly three
parameters:</p><ol><li>Field being validated</li><li>Validation
message</li><li>JSON object with values from the constraint
annotation</li></ol><p>Here is an example:</p><parameter
ac:name="language">js</parameter><plain-text-body>Tapestry.Validator.range =
function(field, message, spec) {
+}</pre>
+</div></div><p>To provide client-side validation of a constraint you have to
add a JavaScript function to the built-in <em>Tapestry.Validator</em>
JavaScript-object. The function should contain exactly three
parameters:</p><ol><li>Field being validated</li><li>Validation
message</li><li>JSON object with values from the constraint
annotation</li></ol><p>Here is an example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: js; gutter: false; theme: Default"
style="font-size:12px;">Tapestry.Validator.range = function(field, message,
spec) {
field.addValidator(function(value) {
if (value < spec.min || value > spec.max) {
throw message;
}
});
-};</plain-text-body><p>Now you have to tell Tapestry to call the function
<em>Tapestry.Validator.range</em> when client-side validation of
<em>@Range</em> should be executed. This is accomplished by a contribution to
the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptorSource.html";>ClientConstraintDescriptorSource</a>
service. The configuration of this service is a collection of <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptor.html";>ClientConstraintDescriptor</a>.
Each <em>ClientConstraintDescriptor</em> represents a client-side validation
constraint. The constructor of <em>ClientConstraintDescriptor</em> has three
parameters:</p><ol><li>Class of the constraint annotation.</li><li>Name of the
JavaScript function.</li><li>The last parameter is a varargs. It is used to
pass the attribute names of the constraint a
nnotation to be passed (along with their values) to the JavaScript function as
an JSON object.</li></ol><p>The last step is to make the contribution, which
links the <em>@Range</em> annotation with the JavaScript function
<em>range</em>. The attributes <em>max</em> and <em>min</em> and their values
are passed to the function.</p><parameter
ac:name="language">java</parameter><plain-text-body>@Contribute(ClientConstraintDescriptorSource.class)
+};</pre>
+</div></div><p>Now you have to tell Tapestry to call the function
<em>Tapestry.Validator.range</em> when client-side validation of
<em>@Range</em> should be executed. This is accomplished by a contribution to
the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptorSource.html";>ClientConstraintDescriptorSource</a>
service. The configuration of this service is a collection of <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beanvalidator/ClientConstraintDescriptor.html";>ClientConstraintDescriptor</a>.
Each <em>ClientConstraintDescriptor</em> represents a client-side validation
constraint. The constructor of <em>ClientConstraintDescriptor</em> has three
parameters:</p><ol><li>Class of the constraint annotation.</li><li>Name of the
JavaScript function.</li><li>The last parameter is a varargs. It is used to
pass the attribute names of the constraint annotatio
n to be passed (along with their values) to the JavaScript function as an JSON
object.</li></ol><p>The last step is to make the contribution, which links the
<em>@Range</em> annotation with the JavaScript function <em>range</em>. The
attributes <em>max</em> and <em>min</em> and their values are passed to the
function.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Contribute(ClientConstraintDescriptorSource.class)
public static void
provideClientConstraintDescriptors(Configuration<ClientConstraintDescriptor>
config) {
config.add(new ClientConstraintDescriptor(Range.class, "range", "min",
"max"));
}
-</plain-text-body></div>
+</pre>
+</div></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/beaneditform-faq.html
==============================================================================
--- websites/production/tapestry/content/beaneditform-faq.html (original)
+++ websites/production/tapestry/content/beaneditform-faq.html Wed Sep 20
12:29:16 2017
@@ -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>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,7 +77,7 @@
</div>
<div id="content">
- <div
id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body>
+ <div id="ConfluenceContent">
<h2 id="BeanEditFormFAQ-BeanEditForm">BeanEditForm </h2>
@@ -83,7 +93,8 @@
-<plain-text-body>
+<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
public class MyBean {
@Inject
public MyBean() { ... }
@@ -94,12 +105,14 @@ public class MyBean {
...
}
-</plain-text-body>
+</pre>
+</div></div>
<ul><li>Provide an event handler method for the "prepare" event, and put an
instantiated instance into the property.</li></ul>
-<plain-text-body>
+<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">
public class MyPage {
@Property
public MyBean myBean;
@@ -110,7 +123,8 @@ public class MyPage {
myBean = new MyBean();
}
}
-</plain-text-body>
+</pre>
+</div></div>
<h3
id="BeanEditFormFAQ-What'sthedifferencebetweenBeanEditorandBeanEditForm?">What's
the difference between BeanEditor and BeanEditForm?</h3>
@@ -119,8 +133,7 @@ public class MyPage {
<h3 id="BeanEditFormFAQ-HowdoIcustomizethelayoutoftheBeanEditForm?">How do I
customize the layout of the BeanEditForm?</h3>
<p>The BeanEditForm is a <em>scaffolding</em> component; it exists to get
things up and running quickly. It can be customized visually using CSS, and can
be configured and extended in a number of ways ... but ultimately, if you want
fine control, you should use the underlying Form, TextField and other
components directly.</p>
-
-<plain-text-body>{scrollbar}</plain-text-body></div>
+</div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/beaneditform-guide.html
==============================================================================
--- websites/production/tapestry/content/beaneditform-guide.html (original)
+++ websites/production/tapestry/content/beaneditform-guide.html Wed Sep 20
12:29:16 2017
@@ -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>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,18 +77,20 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>BeanEditForm</strong>
is a powerful Tapestry component capable of generating a complete create/edit
user interface for a typical
JavaBean.</p><plain-text-body>{float:right|background=#eee|padding=0 1em}
- *JumpStart Demos:*
- [Edit (Using
BeanEditForm)|http://jumpstart.doublenegative.com.au/jumpstart/examples/input/edit1/1]
- [Create (Using
BeanEditForm)|http://jumpstart.doublenegative.com.au/jumpstart/examples/input/create1]
- [More Control Edit (Using
BeanEditor)|http://jumpstart.doublenegative.com.au/jumpstart/examples/input/morecontroledit1/1]
-{float}</plain-text-body><p>BeanEditForm analyzes the the properties of the
bean, locating just those properties that are readable and writeable. It
filters down to properties whose type is mapped to a known editor (this is
described in more detail below).</p><p>The default ordering for properties is
in the order in which the <em>getter methods</em> for the properties are
defined. When a super-class defines editable properties, those are ordered
before sub-class properties.</p><h2
id="BeanEditFormGuide-SupportedTypes">Supported Types</h2><p>The default set of
property types supported by BeanEditForm:</p><ul><li>String: as a text
field</li><li>Number: as a text field</li><li>Enum: as a drop-down
list</li><li>Boolean: as a checkbox</li><li>Date: as a JavaScript
calendar</li><li>Calendar: as a JavaScript calendar</li></ul><p>Resolving a
property type to an editor type involves a search up the inheritance hierarchy:
thus the super-type of Integer, Long, BigDecimal, etc. is Number, which
uses a text field for data entry.</p><p>The list of supported property types
is extensible (this is documented below).</p><h2
id="BeanEditFormGuide-AutomaticObjectCreation">Automatic Object
Creation</h2><p>When a page is rendered, the BeanEditForm component will read
its object parameter as the JavaBean to edit (with the current properties of
the JavaBean becoming the defaults for the various fields). Likewise, when the
form is submitted by the user, the object parameter is read and its properties
populated from the request.</p><p>If the object does not exist, it will be
created as needed. The type is determined from the property type, which should
be a specific type in order for automatic creation to operate
properly.</p><p>The BeanEditForm component will attempt to instantiate a value
for the property as necessary, when the form is submitted. This can be a
problem when the property type is an interface, rather than an instantiable
class.</p><p>One option is to provide an event ha
ndler for the "prepare" or "prepareForSubmit" events to instantiate an
instance to receive the submitted information.</p><p>For a class, Tapestry will
select the public constructor with the <em>most</em> parameters. If this is not
desirable (for example, if you get an exception), then place the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation on the constructor Tapestry should use.</p><h2
id="BeanEditFormGuide-ImplicitObjectBinding">Implicit Object Binding</h2><p>If
the object parameter is not bound, then an implicit binding to a property of
the containing component is made. The bound property will be the BeanEditForm
component's id, if such a property exists. Thus you may typically give the
BeanEditForm component an id (that matches a property) and not have to bind the
object parameter.</p><h2 id="BeanEditFormGuide-Non-VisualProperties">Non-Visual
Properties</h2><p>In some cases, a pr
operty may be updatable and of a supported type for editing, but should not be
presented to the user for editing: for example, a property that holds the
primary key of a database entity. In such a case, the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/NonVisual.html";>NonVisual</a>
annotation may be applied to the property (either the getter or the setter
method).</p><h2 id="BeanEditFormGuide-DefaultValidation">Default
Validation</h2><p>Default validation for fields is primary determined by
property type.</p><p>If desired, additional validation may be specified using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation. See <a href="forms-and-validation.html">Forms and
Validation</a>.</p><p>As of Tapestry 5.2, validation may also be specified via
the containing component's property file, using a key in the form of <code>prop
ertyId-validate</code> (eg: myfield-validate=required).</p><h2
id="BeanEditFormGuide-Propertyordering">Property ordering</h2><p>By default,
the order in which properties are presented is as defined above (order of the
getter method). This can be overridden using the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/ReorderProperties.html";>ReorderProperties</a>
class annotation.</p><h2 id="BeanEditFormGuide-DefaultLabel">Default
Label</h2><p>Tapestry will attempt to provide a reasonable default label for
each field, based on the property name being emitted. The property name is
capitalized, and spaces are added before case changes, thus property "name"
becomes label "Name" and property "streetAddress" becomes label "Street
Address".</p><p>BeanEditForm also searches for a label for the field in the
containing component's message catalog. The message key is the property name
suffixed with "-label". If such a label is found, it ta
kes precedence.</p><h1 id="BeanEditFormGuide-PropertyEditorOverrides">Property
Editor Overrides</h1><p>You may override the editor for any particular
property, using the a block parameter to the BeanEditForm component.</p><p>An
editor normally consists of a Label component and some form of field component
(such as TextField or TextArea).</p><p>For example, you may want to selectively
use a PasswordField component:</p><parameter
ac:name="">java</parameter><plain-text-body> <t:beaneditform
object="loginCredentials">
+ <div id="ConfluenceContent"><p><strong>BeanEditForm</strong>
is a powerful Tapestry component capable of generating a complete create/edit
user interface for a typical JavaBean.</p><div class="navmenu"
style="float:right; background:#eee; margin:3px; padding:0 1em">
+<p> <strong>JumpStart Demos:</strong><br clear="none">
+ <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/edit1/1";
rel="nofollow">Edit (Using BeanEditForm)</a><br clear="none">
+ <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/create1";
rel="nofollow">Create (Using BeanEditForm)</a><br clear="none">
+ <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/input/morecontroledit1/1";
rel="nofollow">More Control Edit (Using
BeanEditor)</a></p></div><p>BeanEditForm analyzes the the properties of the
bean, locating just those properties that are readable and writeable. It
filters down to properties whose type is mapped to a known editor (this is
described in more detail below).</p><p>The default ordering for properties is
in the order in which the <em>getter methods</em> for the properties are
defined. When a super-class defines editable properties, those are ordered
before sub-class properties.</p><h2
id="BeanEditFormGuide-SupportedTypes">Supported Types</h2><p>The default set of
property types supported by BeanEditForm:</p><ul><li>String: as a text
field</li><li>Number: as a text field</li><li>Enum: as a drop-down
list</li><li>Boolean: as a checkbox</li><li>Date: as a JavaScript
calendar</li><li>Calendar: as a JavaScript calendar</li></ul><p>Res
olving a property type to an editor type involves a search up the inheritance
hierarchy: thus the super-type of Integer, Long, BigDecimal, etc. is Number,
which uses a text field for data entry.</p><p>The list of supported property
types is extensible (this is documented below).</p><h2
id="BeanEditFormGuide-AutomaticObjectCreation">Automatic Object
Creation</h2><p>When a page is rendered, the BeanEditForm component will read
its object parameter as the JavaBean to edit (with the current properties of
the JavaBean becoming the defaults for the various fields). Likewise, when the
form is submitted by the user, the object parameter is read and its properties
populated from the request.</p><p>If the object does not exist, it will be
created as needed. The type is determined from the property type, which should
be a specific type in order for automatic creation to operate
properly.</p><p>The BeanEditForm component will attempt to instantiate a value
for the property as necessary, when th
e form is submitted. This can be a problem when the property type is an
interface, rather than an instantiable class.</p><p>One option is to provide an
event handler for the "prepare" or "prepareForSubmit" events to instantiate an
instance to receive the submitted information.</p><p>For a class, Tapestry will
select the public constructor with the <em>most</em> parameters. If this is not
desirable (for example, if you get an exception), then place the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation on the constructor Tapestry should use.</p><h2
id="BeanEditFormGuide-ImplicitObjectBinding">Implicit Object Binding</h2><p>If
the object parameter is not bound, then an implicit binding to a property of
the containing component is made. The bound property will be the BeanEditForm
component's id, if such a property exists. Thus you may typically give the
BeanEditForm component an id (that ma
tches a property) and not have to bind the object parameter.</p><h2
id="BeanEditFormGuide-Non-VisualProperties">Non-Visual Properties</h2><p>In
some cases, a property may be updatable and of a supported type for editing,
but should not be presented to the user for editing: for example, a property
that holds the primary key of a database entity. In such a case, the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/NonVisual.html";>NonVisual</a>
annotation may be applied to the property (either the getter or the setter
method).</p><h2 id="BeanEditFormGuide-DefaultValidation">Default
Validation</h2><p>Default validation for fields is primary determined by
property type.</p><p>If desired, additional validation may be specified using
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/Validate.html";>Validate</a>
annotation. See <a href="forms-and-validation.html">Forms an
d Validation</a>.</p><p>As of Tapestry 5.2, validation may also be specified
via the containing component's property file, using a key in the form of
<code>propertyId-validate</code> (eg: myfield-validate=required).</p><h2
id="BeanEditFormGuide-Propertyordering">Property ordering</h2><p>By default,
the order in which properties are presented is as defined above (order of the
getter method). This can be overridden using the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/ReorderProperties.html";>ReorderProperties</a>
class annotation.</p><h2 id="BeanEditFormGuide-DefaultLabel">Default
Label</h2><p>Tapestry will attempt to provide a reasonable default label for
each field, based on the property name being emitted. The property name is
capitalized, and spaces are added before case changes, thus property "name"
becomes label "Name" and property "streetAddress" becomes label "Street
Address".</p><p>BeanEditForm also searches for a
label for the field in the containing component's message catalog. The
message key is the property name suffixed with "-label". If such a label is
found, it takes precedence.</p><h1
id="BeanEditFormGuide-PropertyEditorOverrides">Property Editor
Overrides</h1><p>You may override the editor for any particular property, using
the a block parameter to the BeanEditForm component.</p><p>An editor normally
consists of a Label component and some form of field component (such as
TextField or TextArea).</p><p>For example, you may want to selectively use a
PasswordField component:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <t:beaneditform object="loginCredentials">
<p:password>
<t:label for="password"/>
<t:passwordfield t:id="password"
value="loginCredentials.password"/>
</p:password>
</t:beaneditform>
-</plain-text-body><p>The other fields will render normally (using the built-in
editors).</p><h1 id="BeanEditFormGuide-CustomizingtheBeanModel">Customizing the
BeanModel</h1><p>You may want to customize the BeanModel further, to remove
from the form properties that should not be editable by the user, and to change
the order in which properties are presented within the form.</p><p>The
BeanEditForm component has several parameters for this purpose:</p><ul><li>add:
A comma separated list of property names to add to the model.</li><li>include:
A comma separated list of property names to keep with the model (others are
excluded).</li><li>exclude: A comma separated list of property names to exclude
from the model.</li><li>reorder: A comma separated list of property names
indicating the desired order.<br clear="none"> If a model has more properties
that are listed in the reorder parameter, then the additional properties will
be ordered at the end of the form.</li></ul><p>Note that these par
ameters <em>modify</em> the BeanModel. If you supply your own BeanModel (via
the model parameter) you should not use the add, include, exclude or reorder
parameters.</p><p>Added properties must not conflict with normal properties.
Cells for added properties will render blank unless an override is
provided.</p><h1 id="BeanEditFormGuide-ProvidingtheBeanModel">Providing the
BeanModel</h1><p>The BeanEditForm component operates in terms of a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/BeanModel.html";>BeanModel</a>,
which describes the properties, their presentation order, labels and so
forth.</p><p>Normally, the BeanEditForm automatically creates the BeanModel as
needed, based on the type of object bound to its object
parameter.</p><p>Alternately, the BeanModel can be supplied as the model
parameter. This can be useful in situations where the exclude and reorder
parameters are insufficient. For example, if the the type of the
property being edited is an interface type, it may be useful to provide an
explicit BeanModel around an underlying implementation class.</p><p>The model
can be created when the page is first instantiated:</p><parameter
ac:name="">java</parameter><plain-text-body>public class MyPage
+</pre>
+</div></div><p>The other fields will render normally (using the built-in
editors).</p><h1 id="BeanEditFormGuide-CustomizingtheBeanModel">Customizing the
BeanModel</h1><p>You may want to customize the BeanModel further, to remove
from the form properties that should not be editable by the user, and to change
the order in which properties are presented within the form.</p><p>The
BeanEditForm component has several parameters for this purpose:</p><ul><li>add:
A comma separated list of property names to add to the model.</li><li>include:
A comma separated list of property names to keep with the model (others are
excluded).</li><li>exclude: A comma separated list of property names to exclude
from the model.</li><li>reorder: A comma separated list of property names
indicating the desired order.<br clear="none"> If a model has more properties
that are listed in the reorder parameter, then the additional properties will
be ordered at the end of the form.</li></ul><p>Note that these parameter
s <em>modify</em> the BeanModel. If you supply your own BeanModel (via the
model parameter) you should not use the add, include, exclude or reorder
parameters.</p><p>Added properties must not conflict with normal properties.
Cells for added properties will render blank unless an override is
provided.</p><h1 id="BeanEditFormGuide-ProvidingtheBeanModel">Providing the
BeanModel</h1><p>The BeanEditForm component operates in terms of a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/beaneditor/BeanModel.html";>BeanModel</a>,
which describes the properties, their presentation order, labels and so
forth.</p><p>Normally, the BeanEditForm automatically creates the BeanModel as
needed, based on the type of object bound to its object
parameter.</p><p>Alternately, the BeanModel can be supplied as the model
parameter. This can be useful in situations where the exclude and reorder
parameters are insufficient. For example, if the the type of the prope
rty being edited is an interface type, it may be useful to provide an explicit
BeanModel around an underlying implementation class.</p><p>The model can be
created when the page is first instantiated:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class MyPage
{
@Inject
private BeanModelSource beanModelSource;
@@ -100,12 +112,18 @@
}
}
-</plain-text-body><p>And, in the component template, the built model can be
passed to the BeanEditForm component explicitly:</p><parameter
ac:name="">java</parameter><plain-text-body> <t:beaneditform object="bean"
model="model"/>
-</plain-text-body><h1 id="BeanEditFormGuide-AddingNewPropertyEditors">Adding
New Property Editors</h1><p>Adding a new property editor is a three step
process.</p><p>First, decide on a logical name for the data type. For example,
you may decide that the BigDecimal type will represent currency in your
application, so name the data type "currency".</p><p>Next, you must make
contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocsapidocs/org/apache/tapestry5/services/DataTypeAnalyzer.html";>DataTypeAnalyzer</a>
or <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/DefaultDataTypeAnalyzer.html";>DefaultDataTypeAnalyzer</a>
services to match properties to your new name.</p><p>DataTypeAnalyzer is a
chain of command that can match properties to data types based on property type
or annotations on the property. In general, DefaultDataTypeAnalyzer is used, as
that only needs to consider property
type. DefaultDataTypeAnalyzer matches property types to data types, based on
a search up the inheritance path.</p><parameter
ac:name="">java</parameter><plain-text-body>public static void
contributeDefaultDataTypeAnalyzer(MappedConfiguration<Class, String>
configuration)
+</pre>
+</div></div><p>And, in the component template, the built model can be passed
to the BeanEditForm component explicitly:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <t:beaneditform object="bean" model="model"/>
+</pre>
+</div></div><h1 id="BeanEditFormGuide-AddingNewPropertyEditors">Adding New
Property Editors</h1><p>Adding a new property editor is a three step
process.</p><p>First, decide on a logical name for the data type. For example,
you may decide that the BigDecimal type will represent currency in your
application, so name the data type "currency".</p><p>Next, you must make
contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocsapidocs/org/apache/tapestry5/services/DataTypeAnalyzer.html";>DataTypeAnalyzer</a>
or <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/DefaultDataTypeAnalyzer.html";>DefaultDataTypeAnalyzer</a>
services to match properties to your new name.</p><p>DataTypeAnalyzer is a
chain of command that can match properties to data types based on property type
or annotations on the property. In general, DefaultDataTypeAnalyzer is used, as
that only needs to consider property type.
DefaultDataTypeAnalyzer matches property types to data types, based on a
search up the inheritance path.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public static void
contributeDefaultDataTypeAnalyzer(MappedConfiguration<Class, String>
configuration)
{
configuration.add(BigDecimal.class, "currency");
}
-</plain-text-body><p>You must provide an editor for the "currency" data type.
An editor is a block of a page of the application; this page is not normally
rendered itself, but acts as a container for one or more blocks.</p><parameter
ac:name="">java</parameter><plain-text-body>public class AppPropertyEditBlocks
+</pre>
+</div></div><p>You must provide an editor for the "currency" data type. An
editor is a block of a page of the application; this page is not normally
rendered itself, but acts as a container for one or more blocks.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class AppPropertyEditBlocks
{
@Property
@Environmental
@@ -130,15 +148,20 @@
return context.getTranslator(current);
}
}
-</plain-text-body><p>The hard part is the translator; this is a piece of code
that understands how to format and how to parse a currency value. It must be
wrapped to create a FieldTranslator.</p><p>The editor is a block inside the
component template:</p><parameter ac:name="">java</parameter><plain-text-body>
<t:block id="currency">
+</pre>
+</div></div><p>The hard part is the translator; this is a piece of code that
understands how to format and how to parse a currency value. It must be wrapped
to create a FieldTranslator.</p><p>The editor is a block inside the component
template:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> <t:block id="currency">
<t:label for="currency"/>
<t:textfield t:id="currency" size="10"/>
</t:block>
-</plain-text-body><p>Finally, we tell the BeanEditForm component about the
editor via a contribution to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/BeanBlockSource.html";>BeanBlockSource</a>
service:</p><parameter ac:name="">java</parameter><plain-text-body>public
static void
contributeBeanBlockSource(Configuration<BeanBlockContribution>
configuration)
+</pre>
+</div></div><p>Finally, we tell the BeanEditForm component about the editor
via a contribution to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/BeanBlockSource.html";>BeanBlockSource</a>
service:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public static void
contributeBeanBlockSource(Configuration<BeanBlockContribution>
configuration)
{
configuration.add(new BeanBlockContribution("currency",
"AppPropertyEditBlocks", "currency", true));
}
-</plain-text-body><p>Now, when the BeanEditForm sees a property of type
BigDecimal, it will map that to datatype "currency" and from there to the
currency block of the AppPropertyEditBlocks page of the application.</p></div>
+</pre>
+</div></div><p>Now, when the BeanEditForm sees a property of type BigDecimal,
it will map that to datatype "currency" and from there to the currency block of
the AppPropertyEditBlocks page of the application.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/case-insensitivity.html
==============================================================================
--- websites/production/tapestry/content/case-insensitivity.html (original)
+++ websites/production/tapestry/content/case-insensitivity.html Wed Sep 20
12:29:16 2017
@@ -36,26 +36,13 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
-
-</div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
-<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form>
-
-</div>
-
-
-<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
-
-
-<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Case Insensitivity</h1></div>
-
-</div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Case Insensitivity</h1></div></div>
<div class="clearer"></div>
</div>
Modified: websites/production/tapestry/content/chainbuilder-service.html
==============================================================================
--- websites/production/tapestry/content/chainbuilder-service.html (original)
+++ websites/production/tapestry/content/chainbuilder-service.html Wed Sep 20
12:29:16 2017
@@ -27,6 +27,14 @@
</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>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -36,26 +44,13 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
-
-</div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
-<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form>
-
-</div>
-
-
-<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
-
-
-<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">ChainBuilder Service</h1></div>
-
-</div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">ChainBuilder Service</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,15 +62,49 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>The <strong>ChainBuilder
Service</strong> is a built-in service used to implement of one of the most
useful of the <em>Gang Of Four</em> design patterns, the <a
class="external-link"
href="https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern";
rel="nofollow">chain of responsibility</a>.</p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label in
("chain-of-command","service-builders") and space =
currentSpace()</parameter></rich-text-body><p>With the chain of responsibility
design pattern, a complex process is broken down into many individual steps.
Each step is a <em>command</em> (see <a class="external-link"
href="https://en.wi
kipedia.org/wiki/Command_pattern" rel="nofollow">command pattern</a>). A key
part of this is that the commands are expected to implement some common
interface. The commands are also carefully arranged into a specific
order.</p><p>The process operates by working down the list of commands, and
each command is given a chance to operate. In the ChainBuilder service, a
command can terminate the process either by throwing an exception, or by
returning true.</p><p>The return type of the command method does not have to be
boolean: For object types, any non-null value short-circuits the process. For
numeric type, any non-zero value. For void methods, only throwing an exception
will short circuit the process.</p><p>Often, the command interface consists of
a single method. When the command interface has multiple methods, each can be
thought of as its own chain.</p><p>This is a useful pattern because it makes it
very easy to <em>extend</em> a given process, simply by providing new commands
and
specifying where they fit into the overall process. Most often chain of
command is combined with an ordered <a
href="tapestry-ioc-configuration.html">configuration</a> to define what the
list of commands are (and in what order they should execute).</p><h1
id="ChainBuilderService-ChainBuilderService">ChainBuilder
Service</h1><p>Because this pattern is used so often inside Tapestry, a
built-in service exists to create implementations of the pattern as needed. The
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/ChainBuilder.html";>ChainBuilder</a>
service takes care of all the work:</p><parameter
ac:name="">java</parameter><plain-text-body>public interface ChainBuilder
+ <div id="ConfluenceContent"><p>The <strong>ChainBuilder
Service</strong> is a built-in service used to implement of one of the most
useful of the <em>Gang Of Four</em> design patterns, the <a
class="external-link"
href="https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern";
rel="nofollow">chain of responsibility</a>.</p><div class="aui-label"
style="float:right" title="Related Articles"><h3>Related Articles</h3><ul
class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="chainbuilder-service.html">ChainBuilder Service</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="shadowbuilder-service.html">ShadowBuilder Service</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="ioc-cookbook-patterns.html">IoC Cookbook - Patterns</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="strategybuilder-service.html">StrategyBuilder Service</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="pipelinebuilder-service.html">PipelineBuilder Service</a>
+ </div> </li></ul></div><p>With the chain of responsibility design pattern, a
complex process is broken down into many individual steps. Each step is a
<em>command</em> (see <a class="external-link"
href="https://en.wikipedia.org/wiki/Command_pattern"; rel="nofollow">command
pattern</a>). A key part of this is that the commands are expected to implement
some common interface. The commands are also carefully arranged into a specific
order.</p><p>The process operates by working down the list of commands, and
each command is given a chance to operate. In the ChainBuilder service, a
command can terminate the process either by throwing an exception, or by
returning true.</p><p>The return type of the command method does not have to be
boolean: For object types, any non-null value short-circuits the process. For
numeric type, any non-zero value. For void methods, only throwing an exception
will short circuit the process.</p><p>Often, the command interface consists of
a single method. When
the command interface has multiple methods, each can be thought of as its own
chain.</p><p>This is a useful pattern because it makes it very easy to
<em>extend</em> a given process, simply by providing new commands and
specifying where they fit into the overall process. Most often chain of command
is combined with an ordered <a
href="tapestry-ioc-configuration.html">configuration</a> to define what the
list of commands are (and in what order they should execute).</p><h1
id="ChainBuilderService-ChainBuilderService">ChainBuilder
Service</h1><p>Because this pattern is used so often inside Tapestry, a
built-in service exists to create implementations of the pattern as needed. The
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/ChainBuilder.html";>ChainBuilder</a>
service takes care of all the work:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public interface ChainBuilder
{
<T> T build(Class<T> commandInterface, List<T> commands);
-}</plain-text-body><p>All that generics parameterization just ensures that the
command interface matches the items in the list, and confirms that a single
instance of the command interface will be returned.</p><p>Invoking this method
returns an object that encapsulates the chain of command for a particular
interface and a particular list of commands implementing that
interface.</p><p>This can be used inside a service builder method. Nothing says
a service builder method just has to instantiate a class; it is only required
to return an appropriate object. We can just let the ChainBuilder service
create that object.</p><parameter ac:name="">java</parameter><plain-text-body>
public static MyChainService build(List<MyChainService> commands,
+}</pre>
+</div></div><p>All that generics parameterization just ensures that the
command interface matches the items in the list, and confirms that a single
instance of the command interface will be returned.</p><p>Invoking this method
returns an object that encapsulates the chain of command for a particular
interface and a particular list of commands implementing that
interface.</p><p>This can be used inside a service builder method. Nothing says
a service builder method just has to instantiate a class; it is only required
to return an appropriate object. We can just let the ChainBuilder service
create that object.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> public static MyChainService
build(List<MyChainService> commands,
@InjectService("ChainBuilder")
ChainBuilder chainBuilder)
{
return chainBuilder.build(MyChainService.class, commands);
- }</plain-text-body><p>Here, the behavior of the MyChainService is defined by
its configuration: an ordered list of MyChainService commands that are
contributed by one or more modules.</p><p>Internally, the ChainBuilder creates
a new class that implements the service interface. The list of commands is
converted into an array, which is used inside the service implementation (for
maximum efficiency). Therefore, changing the list after creating the chain
instance will not affect the chain instance's behavior.</p><p>ChainBuilder will
reuse the fabricated class for any number of chains of the same command
interface.</p><p> </p><p></p></div>
+ }</pre>
+</div></div><p>Here, the behavior of the MyChainService is defined by its
configuration: an ordered list of MyChainService commands that are contributed
by one or more modules.</p><p>Internally, the ChainBuilder creates a new class
that implements the service interface. The list of commands is converted into
an array, which is used inside the service implementation (for maximum
efficiency). Therefore, changing the list after creating the chain instance
will not affect the chain instance's behavior.</p><p>ChainBuilder will reuse
the fabricated class for any number of chains of the same command
interface.</p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
![http://tapestry.apache.org/images/tapestry_small.png"](http://tapestry.apache.org/images/tapestry_small.png"){kind=link}