Modified: websites/production/tapestry/content/environmental-services.html
==============================================================================
--- websites/production/tapestry/content/environmental-services.html (original)
+++ websites/production/tapestry/content/environmental-services.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,11 +67,11 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><div class="navmenu"
style="float:right; width:30%; background:#eee; margin:3px; padding:3px">
-<p>Environmental services represent yet another, distinct form of
injection.</p>
+ <div
id="ConfluenceContent"><p><plain-text-body>{float:right|background=#eee|width=30%}
+Environmental services represent yet another, distinct form of injection.
-<p>Unlike service injection (injection via a service implementation's
constructor) or normal component injection (directly into component fields, via
the @Inject annotation) where the injected value is always the same, with
environmental services, the injected value is very late bound and
dynamic.</p></div><strong>Environmental services</strong> provide a conduit of
communication between two components (usually a component and the components it
encloses). The first component pushes an object of a certain type into the
<em>environment</em>, and then the second component can access that object
merely by defining an annotated property of the same type.<p>An example of how
this works is Tapestry's built-in <em>form support</em>. The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html";>Form</a>
component creates an object of type <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/t
apestry5/services/FormSupport.html">FormSupport</a> and pushes it into the
environment. Then, the enclosed form components can use that FormSupport object
to participate in both the rendering of the Form and the Form's eventual
submission. This is how control names and client-side ids are determined, how
fields register callbacks so that they can process their part of the
submission, and how fields hook themselves to client-side validation.</p><h1
id="EnvironmentalServices-Usingthe@Environmentalannotation">Using the
@Environmental annotation</h1><p>The @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html";>Environmental</a>
annotation, when used in a component class, causes the associated field to be
replaced at runtime with a read-only value obtained from an Environment service
provided by an enclosing component.</p><p>A very common Environmental is <a
class="external-link" href="http://tapestry.apache.org/c
urrent/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html">JavaScriptSupport</a>,
used when generating <a href="legacy-javascript.html">client-side
JavaScript</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;"> @Inject @Path("${tapestry.scriptaculous}/dragdrop.js")
+Unlike service injection (injection via a service implementation's
constructor) or normal component injection (directly into component fields, via
the @Inject annotation) where the injected value is always the same, with
environmental services, the injected value is very late bound and dynamic.
+{float}</plain-text-body><strong>Environmental services</strong> provide a
conduit of communication between two components (usually a component and the
components it encloses). The first component pushes an object of a certain type
into the <em>environment</em>, and then the second component can access that
object merely by defining an annotated property of the same type.</p><p>An
example of how this works is Tapestry's built-in <em>form support</em>. The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html";>Form</a>
component creates an object of type <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/FormSupport.html";>FormSupport</a>
and pushes it into the environment. Then, the enclosed form components can use
that FormSupport object to participate in both the rendering of the Form and
the Form's eventual submission. This is how control names and client-si
de ids are determined, how fields register callbacks so that they can process
their part of the submission, and how fields hook themselves to client-side
validation.</p><h1
id="EnvironmentalServices-Usingthe@Environmentalannotation">Using the
@Environmental annotation</h1><p>The @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html";>Environmental</a>
annotation, when used in a component class, causes the associated field to be
replaced at runtime with a read-only value obtained from an Environment service
provided by an enclosing component.</p><p>A very common Environmental is <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>,
used when generating <a href="legacy-javascript.html">client-side
JavaScript</a>.</p><parameter ac:name="">java</parameter><plain-text-body>
@Inject @Path("${tapestry.scripta
culous}/dragdrop.js")
private Asset dragDropLibrary;
@Environmental
@@ -92,9 +82,7 @@
javaScriptSupport.importJavaScriptLibrary(dragDropLibrary);
}
-</pre>
-</div></div><p>Environmental services are, by their nature, per-thread (and
therefore per-request).</p><p>Accessing an environmental field causes a lookup,
by type, against the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Environment.html";>Environment</a>
service.</p><p>Normally, an environmental of the specified type must be
available in the Environment, or an exception is thrown when accessing the
field. However, if the value of the Environmental annotation's value is false,
then the environmental value is optional.</p><h1
id="EnvironmentalServices-Placingavalueintheenvironment">Placing a value in the
environment</h1><p>The Environment service has push() and pop() methods to put
a value in the Environment, and discard it.</p><p>For example, say you were
building a tab-based menu system and you needed to allow an outer TabGroup
component to communicate with inner Tab components, to control various aspects
of presentation.<
/p><p>The relevant information could be exposed as an interface,
TabModel.</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 TabGroup
+</plain-text-body><p>Environmental services are, by their nature, per-thread
(and therefore per-request).</p><p>Accessing an environmental field causes a
lookup, by type, against the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Environment.html";>Environment</a>
service.</p><p>Normally, an environmental of the specified type must be
available in the Environment, or an exception is thrown when accessing the
field. However, if the value of the Environmental annotation's value is false,
then the environmental value is optional.</p><h1
id="EnvironmentalServices-Placingavalueintheenvironment">Placing a value in the
environment</h1><p>The Environment service has push() and pop() methods to put
a value in the Environment, and discard it.</p><p>For example, say you were
building a tab-based menu system and you needed to allow an outer TabGroup
component to communicate with inner Tab components, to control various aspects
of presenta
tion.</p><p>The relevant information could be exposed as an interface,
TabModel.</p><parameter ac:name="">java</parameter><plain-text-body>public
class TabGroup
{
@Inject
private Environment environment;
@@ -120,14 +108,11 @@ public class Tab
...
}
}
-</pre>
-</div></div><p>Notice that when pushing a value into the Environment, you
identify its type as well as the instance. Environment maintains a number of
stacks, one for each type. Thus, pushing a TabModel into the environment won't
disturb the RenderSupport or other environmentals already there.</p><p>What's
important here is that the code that pushes a environmental onto a stack should
also pop it off.</p><p>The enclosed class, Tab, has full access to whatever
object was pushed onto the stack by the TabGroup.</p><p>The reason why
Environment is a stack is so that a component can, when it makes sense, easily
replace or intercept access to an Environmental.</p><h1
id="EnvironmentalServices-FundamentalEnvironmentals">Fundamental
Environmentals</h1><p>Not all environmentals are pushed into the Environment by
components.</p><p>A number of environmentals are initialized as part of page
rendering, even before the first component starts to render. This
initialization is accomplished with <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html";>MarkupRendererFilter</a>
contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRenderer.html";>MarkupRenderer</a>
service.</p><h1
id="EnvironmentalServices-AccessingEnvironmentalsinServices">Accessing
Environmentals in Services</h1><p>The Environmental annotation only works
inside components.</p><p>To access an Environmental inside a service
implementation, you must inject the Environment service and obtain values from
it using the peek() method.</p><p>If this is something that will occur
frequently, it is possible to create a service implementation that is "backed"
by the Environment. For example, RenderSupport is accessible as a normal
injection, because a service is built for it in TapestryModule:</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 RenderSupport
buildRenderSupport(EnvironmentalShadowBuilder builder)
+</plain-text-body><p>Notice that when pushing a value into the Environment,
you identify its type as well as the instance. Environment maintains a number
of stacks, one for each type. Thus, pushing a TabModel into the environment
won't disturb the RenderSupport or other environmentals already
there.</p><p>What's important here is that the code that pushes a environmental
onto a stack should also pop it off.</p><p>The enclosed class, Tab, has full
access to whatever object was pushed onto the stack by the TabGroup.</p><p>The
reason why Environment is a stack is so that a component can, when it makes
sense, easily replace or intercept access to an Environmental.</p><h1
id="EnvironmentalServices-FundamentalEnvironmentals">Fundamental
Environmentals</h1><p>Not all environmentals are pushed into the Environment by
components.</p><p>A number of environmentals are initialized as part of page
rendering, even before the first component starts to render. This
initialization is accomplished wi
th <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html";>MarkupRendererFilter</a>
contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRenderer.html";>MarkupRenderer</a>
service.</p><h1
id="EnvironmentalServices-AccessingEnvironmentalsinServices">Accessing
Environmentals in Services</h1><p>The Environmental annotation only works
inside components.</p><p>To access an Environmental inside a service
implementation, you must inject the Environment service and obtain values from
it using the peek() method.</p><p>If this is something that will occur
frequently, it is possible to create a service implementation that is "backed"
by the Environment. For example, RenderSupport is accessible as a normal
injection, because a service is built for it in TapestryModule:</p><parameter
ac:name="">java</parameter><plain-text-body> public RenderSu
pport buildRenderSupport(EnvironmentalShadowBuilder builder)
{
return builder.build(RenderSupport.class);
}
-</pre>
-</div></div><p>The EnvironmentShadowBuilder service creates a service
implementation that delegates to the proper instance in the environment. The
same technique can be used for your own services and environmentals.</p></div>
+</plain-text-body><p>The EnvironmentShadowBuilder service creates a service
implementation that delegates to the proper instance in the environment. The
same technique can be used for your own services and environmentals.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/error-page-recipe.html
==============================================================================
--- websites/production/tapestry/content/error-page-recipe.html (original)
+++ websites/production/tapestry/content/error-page-recipe.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,50 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h1
id="ErrorPageRecipe-ServingTapestryPagesasServletErrorPages">Serving Tapestry
Pages as Servlet Error Pages</h1><p>Do you want to dress up your site and use a
snazzy Tapestry page instead of the default 404 error page? Using modern
servlet containers, this is a snap!</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="error-page-recipe.html">Error Page Recipe</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="specific-errors-faq.html">Specific Errors
FAQ</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="overriding-exception-reporting.html">Overriding Exception Reporting</a>
-
-
- </div>
- </li></ul>
-</div>
-
-
-<p>Simply upgrade your application web.xml to the 2.4 version, and make a
couple of changes:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>web.xml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+ <div
id="ConfluenceContent"><p><plain-text-body>{scrollbar}</plain-text-body></p><parameter
ac:name="hidden">true</parameter><parameter
ac:name="atlassian-macro-output-type">BLOCK</parameter><rich-text-body><p>Serving
up a Tapestry page as your site's custom 404 response
page</p></rich-text-body><h1
id="ErrorPageRecipe-ServingTapestryPagesasServletErrorPages">Serving Tapestry
Pages as Servlet Error Pages</h1><p>Do you want to dress up your site and use a
snazzy Tapestry page instead of the default 404 error page? Using modern
servlet containers, this is a snap!</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 = "errors" and space =
currentSpace()</parameter></rich-te
xt-body><p>Simply upgrade your application web.xml to the 2.4 version, and
make a couple of changes:</p><parameter
ac:name="language">xml</parameter><parameter
ac:name="title">web.xml</parameter><plain-text-body><?xml version="1.0"
encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee";
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd";
@@ -149,9 +96,7 @@
</error-page>
</web-app>
-</pre>
-</div></div><p>Tapestry's filter must be marked as a handler for both standard
requests and errors. That's accomplished with the
<code><dispatcher></code> elements inside the
<code><filter-mapping></code> section.</p><p>You must then map error
codes to Tapestry URLs. In this case, the 404 error is send to the
<code>/error404</code> resource, which is really the "Error404" Tapestry
page.</p><p>We'll create a simple Error404 page, one that displays a message
and (in development mode) displays the details about the incoming
request.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Error404.tml</b></div><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_4.xsd">
+</plain-text-body><p>Tapestry's filter must be marked as a handler for both
standard requests and errors. That's accomplished with the
<code><dispatcher></code> elements inside the
<code><filter-mapping></code> section.</p><p>You must then map error
codes to Tapestry URLs. In this case, the 404 error is send to the
<code>/error404</code> resource, which is really the "Error404" Tapestry
page.</p><p>We'll create a simple Error404 page, one that displays a message
and (in development mode) displays the details about the incoming
request.</p><parameter ac:name="language">xml</parameter><parameter
ac:name="title">Error404.tml</parameter><plain-text-body><html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<head>
<title>Resource not found.</title>
@@ -168,9 +113,7 @@
</div>
</body>
-</html></pre>
-</div></div><p>The page simply makes the request and productionMode properties
available:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Error404.java</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.example.newapp.pages;
+</html></plain-text-body><p>The page simply makes the request and
productionMode properties available:</p><parameter
ac:name="language">java</parameter><parameter
ac:name="title">Error404.java</parameter><plain-text-body>package
com.example.newapp.pages;
import org.apache.tapestry5.SymbolConstants;
import org.apache.tapestry5.annotations.Property;
@@ -191,8 +134,7 @@ public class Error404
}
-</pre>
-</div></div><p>The end-result, in when <em>not</em> in production mode, looks
like this:</p><p><span class="confluence-embedded-file-wrapper
image-center-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border image-center"
width="500"
src="error-page-recipe.data/Resource_not_found_.png"></span></p><div
class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>An issue with an application that
has a root Index page is that any invalid path, which would normally generate a
404 error, is instead routed to the Index page (because the invalid path looks
like page's activation context). See <a class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-2070";>Issue
TAP5-2070</a>.</p></div></div></div>
+</plain-text-body><p>The end-result, in when <em>not</em> in production mode,
looks like this:</p><p><span class="confluence-embedded-file-wrapper
image-center-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image confluence-content-image-border image-center"
width="500"
src="error-page-recipe.data/Resource_not_found_.png"></span></p><rich-text-body><p>An
issue with an application that has a root Index page is that any invalid path,
which would normally generate a 404 error, is instead routed to the Index page
(because the invalid path looks like page's activation context). See <a
class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-2070";>Issue
TAP5-2070</a>.</p></rich-text-body></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/exploring-the-project.html
==============================================================================
--- websites/production/tapestry/content/exploring-the-project.html (original)
+++ websites/production/tapestry/content/exploring-the-project.html Tue Sep 26
19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,8 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>The layout of the project
follows the sensible standards promoted by Maven:</p><ul><li>Java source files
under <code>src/main/java</code></li><li>Web application files under
<code>src/main/webapp</code> (including
<code>src/main/webapp/WEB-INF</code>)</li><li>Java test sources under
<code>src/test/java</code></li><li>Non-code resources (including Tapestry page
and component templates) under <code>src/main/resources</code> and
<code>src/test/resources</code></li></ul><p>Let's look at what Maven has
created from the archetype, starting with the web.xml configuration
file:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>src/main/webapp/WEB-INF/web.xml</b></div><div class="codeContent
panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><?xml version="1.0" encoding="UTF-8"?>
+ <div id="ConfluenceContent"><p>The layout of the project
follows the sensible standards promoted by Maven:</p><ul><li>Java source files
under <code>src/main/java</code></li><li>Web application files under
<code>src/main/webapp</code> (including
<code>src/main/webapp/WEB-INF</code>)</li><li>Java test sources under
<code>src/test/java</code></li><li>Non-code resources (including Tapestry page
and component templates) under <code>src/main/resources</code> and
<code>src/test/resources</code></li></ul><p>Let's look at what Maven has
created from the archetype, starting with the web.xml configuration
file:</p><parameter ac:name="language">xml</parameter><parameter
ac:name="title">src/main/webapp/WEB-INF/web.xml</parameter><plain-text-body><?xml
version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
@@ -116,9 +105,7 @@ of where to look for pages, components a
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
-</pre>
-</div></div><p>This is short and sweet: you can see that the package name you
provided earlier shows up as the <code>tapestry.app-package</code> context
parameter; the TapestryFilter instance will use this information to locate the
Java classes for pages and components.</p><p>Tapestry operates as a <em>servlet
filter</em> rather than as a traditional <em>servlet</em>. In this way,
Tapestry has a chance to intercept all incoming requests, to determine which
ones apply to Tapestry pages (or other resources). The net effect is that you
don't have to maintain any additional configuration for Tapestry to operate,
regardless of how many pages or components you add to your
application.</p><p>Much of the rest of web.xml is configuration to match
Tapestry execution modes against module classes. An execution mode defines how
the application is being run: the default execution mode is "production", but
the web.xml defines two additional modes: "development" and "qa" (for "Quality
Assurance").
The module classes indicated will be loaded for those execution modes, and can
change the configuration of the application is various ways. We'll come back to
execution modes and module classes later in the tutorial.</p><p>Tapestry pages
minimally consist of an ordinary Java class plus a component template
file.</p><p>In the root of your web application, a page named "Index" will be
used for any request that specifies no additional path after the context
name.</p><h1 id="ExploringtheProject-IndexJavaClass">Index Java
Class</h1><p>Tapestry has very specific rules for where page classes go.
Tapestry adds a sub-package, "pages", to the root application package
("com.example.tutorial1"); the Java classes for pages goes there. Thus the full
Java class name is
<code>com.example.</code>tutorial<code>1.pages.Index</code>.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width:
1px;"><b>src/main/java/com/example/tutorial/p
ages/Index.java</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.example.tutorial1.pages;
+</plain-text-body><p>This is short and sweet: you can see that the package
name you provided earlier shows up as the <code>tapestry.app-package</code>
context parameter; the TapestryFilter instance will use this information to
locate the Java classes for pages and components.</p><p>Tapestry operates as a
<em>servlet filter</em> rather than as a traditional <em>servlet</em>. In this
way, Tapestry has a chance to intercept all incoming requests, to determine
which ones apply to Tapestry pages (or other resources). The net effect is that
you don't have to maintain any additional configuration for Tapestry to
operate, regardless of how many pages or components you add to your
application.</p><p>Much of the rest of web.xml is configuration to match
Tapestry execution modes against module classes. An execution mode defines how
the application is being run: the default execution mode is "production", but
the web.xml defines two additional modes: "development" and "qa" (for "Quality
Assuran
ce"). The module classes indicated will be loaded for those execution modes,
and can change the configuration of the application is various ways. We'll come
back to execution modes and module classes later in the
tutorial.</p><p>Tapestry pages minimally consist of an ordinary Java class plus
a component template file.</p><p>In the root of your web application, a page
named "Index" will be used for any request that specifies no additional path
after the context name.</p><h1 id="ExploringtheProject-IndexJavaClass">Index
Java Class</h1><p>Tapestry has very specific rules for where page classes go.
Tapestry adds a sub-package, "pages", to the root application package
("com.example.tutorial1"); the Java classes for pages goes there. Thus the full
Java class name is
<code>com.example.</code>tutorial<code>1.pages.Index</code>.</p><parameter
ac:name="language">java</parameter><parameter
ac:name="title">src/main/java/com/example/tutorial/pages/Index.java</parameter><plain-text-body>package
c
om.example.tutorial1.pages;
import org.apache.tapestry5.Block;
import org.apache.tapestry5.EventContext;
@@ -188,9 +175,7 @@ public class Index
return new Date();
}
}
-</pre>
-</div></div><p>There's a bit going on in this listing, as the Index page
attempts to demonstrate a bunch of different ideas in Tapestry. Even so, the
class is essentially pretty simple: Tapestry pages and components have no base
classes to extend, no interfaces to implement, and are just a very pure POJO
(Plain Old Java Object) ... with some special naming conventions and
annotations for fields and methods.</p><p>You do have to meet the Tapestry
framework partway:</p><ul><li>You need to put the Java class in the expected
package, here com.example.tutorial1.pages</li><li>The class must be
public</li><li>You need to make sure there's a public, no-arguments constructor
(here, the Java compiler has silently provided one for us)</li><li>All
non-static fields must be <strong>private</strong></li></ul><p>As we saw when
running the application, the page displays the current date and time, as well
as a couple of extra links. The <code>currentTime</code> property is where that
value comes fro
m; shortly we'll see how that value is referenced in the template, so it can
be extracted from the page and output.</p><p>Tapestry always matches a page
class to a template; neither is functional without the other. In fact,
components within a page are treated the same way (except that components do
not always have templates).</p><p>You will often hear about the <a
class="external-link" href="http://en.wikipedia.org/wiki/Model_view_controller";
rel="nofollow">Model-View-Controller pattern</a> (MVC). In Tapestry, the page
class acts as both the Model (the source of data) and the controller (the logic
that responds to user interaction). The template is the View in MVC. As a
model, the page exposes JavaBeans properties that can be referenced in the
template.</p><p>Let's look at how the component template builds on the Java
class to provide the full user interface.</p><h1
id="ExploringtheProject-ComponentTemplate">Component Template</h1><p>Tapestry
pages are the combination of a POJO Ja
va class with a Tapestry component template. The template has the same name as
the Java class, but has the extension <code>.tml</code>. Since the Java class
here is com.example.tutorial.pages.Index, the template file will be located at
src/main/resource/com/example/tutorial/pages/Index.tml. Ultimately, both the
Java class and the component template file will be stored in the same folder
within the deployed WAR file.</p><p>Tapestry component templates are
well-formed XML documents. This means that you can use any available XML
editor. Templates may even have a DOCTYPE or an XML schema to validate the
structure of the template page.</p><p><em>Note that Tapestry parses component
templates using a non-validating parser; it only checks for well-formedness:
proper syntax, balanced elements, attribute values are quoted, and so forth. It
is reasonable for your build process to perform some kind of template
validation, but Tapestry accepts the template as-is, as long as it parses
cleanly.</e
m></p><p>For the most part, a Tapestry component template looks like ordinary
XHTML:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>src/main/resources/com/example/tutorial1/pages/Index.tml</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><html t:type="layout" title="tutorial1 Index"
+</plain-text-body><p>There's a bit going on in this listing, as the Index page
attempts to demonstrate a bunch of different ideas in Tapestry. Even so, the
class is essentially pretty simple: Tapestry pages and components have no base
classes to extend, no interfaces to implement, and are just a very pure POJO
(Plain Old Java Object) ... with some special naming conventions and
annotations for fields and methods.</p><p>You do have to meet the Tapestry
framework partway:</p><ul><li>You need to put the Java class in the expected
package, here com.example.tutorial1.pages</li><li>The class must be
public</li><li>You need to make sure there's a public, no-arguments constructor
(here, the Java compiler has silently provided one for us)</li><li>All
non-static fields must be <strong>private</strong></li></ul><p>As we saw when
running the application, the page displays the current date and time, as well
as a couple of extra links. The <code>currentTime</code> property is where that
value com
es from; shortly we'll see how that value is referenced in the template, so it
can be extracted from the page and output.</p><p>Tapestry always matches a page
class to a template; neither is functional without the other. In fact,
components within a page are treated the same way (except that components do
not always have templates).</p><p>You will often hear about the <a
class="external-link" href="http://en.wikipedia.org/wiki/Model_view_controller";
rel="nofollow">Model-View-Controller pattern</a> (MVC). In Tapestry, the page
class acts as both the Model (the source of data) and the controller (the logic
that responds to user interaction). The template is the View in MVC. As a
model, the page exposes JavaBeans properties that can be referenced in the
template.</p><p>Let's look at how the component template builds on the Java
class to provide the full user interface.</p><h1
id="ExploringtheProject-ComponentTemplate">Component Template</h1><p>Tapestry
pages are the combination of a P
OJO Java class with a Tapestry component template. The template has the same
name as the Java class, but has the extension <code>.tml</code>. Since the Java
class here is com.example.tutorial.pages.Index, the template file will be
located at src/main/resource/com/example/tutorial/pages/Index.tml. Ultimately,
both the Java class and the component template file will be stored in the same
folder within the deployed WAR file.</p><p>Tapestry component templates are
well-formed XML documents. This means that you can use any available XML
editor. Templates may even have a DOCTYPE or an XML schema to validate the
structure of the template page.</p><p><em>Note that Tapestry parses component
templates using a non-validating parser; it only checks for well-formedness:
proper syntax, balanced elements, attribute values are quoted, and so forth. It
is reasonable for your build process to perform some kind of template
validation, but Tapestry accepts the template as-is, as long as it parses clean
ly.</em></p><p>For the most part, a Tapestry component template looks like
ordinary XHTML:</p><parameter ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><parameter
ac:name="title">src/main/resources/com/example/tutorial1/pages/Index.tml</parameter><plain-text-body><html
t:type="layout" title="tutorial1 Index"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd";
xmlns:p="tapestry:parameter">
@@ -231,59 +216,27 @@ public class Index
<p>The current time is:
<strong>${currentTime}</strong></p>
</t:block>
-</html></pre>
-</div></div><div class="confluence-information-macro
confluence-information-macro-tip"><span class="aui-icon aui-icon-small
aui-iconfont-approve confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>You do have to name your component
template file, Index.tml, with the <strong>exact same case</strong> as the
component class name, Index. If you get the case wrong, it may work on some
operating systems (such as Mac OS X, Windows) and not on others (Linux, and
most others). This can be really vexing, as it is common to develop on Windows
and deploy on Linux or Solaris, so be careful about case in this one
area.</p></div></div><p>The goal in Tapestry is for component templates, such
as Index.tml, to look as much as possible like ordinary, static HTML files. (By
static, we mean unchanging, as opposed to a dynamically generated Tapestry
page.)</p><p>In fact, the expectation is that in many cases, the templates will
start as static HTML files, created b
y a web developer, and then be <em>instrumented</em> to act as live Tapestry
pages.</p><p>Tapestry hides non-standard elements and attributes inside XML
namespaces. By convention, the prefix "t:" is used for the primary namespace,
but that is not a requirement, any prefix you want to use is fine.</p><p>This
short template demonstrates quite a few features of Tapestry.</p><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>Part of the concept of the
quickstart archetype is to demonstrate a bunch of different features,
approaches, and common patterns used in Tapestry. So yes, we're hitting you
with a lot all at once.</p></div></div><p>First of all, there are two XML
namespaces commonly defined:</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;">
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd";
+</html></plain-text-body><rich-text-body><p>You do have to name your
component template file, Index.tml, with the <strong>exact same case</strong>
as the component class name, Index. If you get the case wrong, it may work on
some operating systems (such as Mac OS X, Windows) and not on others (Linux,
and most others). This can be really vexing, as it is common to develop on
Windows and deploy on Linux or Solaris, so be careful about case in this one
area.</p></rich-text-body><p>The goal in Tapestry is for component templates,
such as Index.tml, to look as much as possible like ordinary, static HTML
files. (By static, we mean unchanging, as opposed to a dynamically generated
Tapestry page.)</p><p>In fact, the expectation is that in many cases, the
templates will start as static HTML files, created by a web developer, and then
be <em>instrumented</em> to act as live Tapestry pages.</p><p>Tapestry hides
non-standard elements and attributes inside XML namespaces. By convention, th
e prefix "t:" is used for the primary namespace, but that is not a
requirement, any prefix you want to use is fine.</p><p>This short template
demonstrates quite a few features of Tapestry.</p><rich-text-body><p>Part of
the concept of the quickstart archetype is to demonstrate a bunch of different
features, approaches, and common patterns used in Tapestry. So yes, we're
hitting you with a lot all at once.</p></rich-text-body><p>First of all, there
are two XML namespaces commonly defined:</p><parameter
ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body>
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd";
xmlns:p="tapestry:parameter"
-</pre>
-</div></div><p>The first namespace, "t:", it used to identify
Tapestry-specific elements and attributes. Although there is an XSD (that is, a
XML schema definition), it is incomplete (for reasons explained
shortly).</p><p>The second namespace, "p:", is a way of marking a chunk of the
template as a parameter passed into another component. We'll expand on that
shortly.</p><p>A Tapestry component template consists mostly of standard XHTML
that will pass down to the client web browser unchanged. The dynamic aspects of
the template are represented by <em>components</em> and
<em>expansions</em>.</p><h1
id="ExploringtheProject-ExpansionsinTemplates">Expansions in
Templates</h1><p>Let's start with expansions. Expansions are an easy way of
including some dynamic output when rendering the page. By default, an expansion
refers to a JavaBeans property of the page:</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;"> <p>The current time is: ${currentTime}</p>
-</pre>
-</div></div><p>The value inside the curly braces is a <em>property
expression</em>. Tapestry uses its own property expression language that is
expressive, fast, and type-safe.</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"><pre>Tapestry does NOT use reflection
to implement property expressions.</pre></div></div><p>More advanced property
expressions can traverse multiple properties (for example,
<code>user.address.city</code>), or even invoke public methods. Here the
expansion simply reads the <code>currentTime</code> property of the
page.</p><p>Tapestry follows the rules defined by Sun's JavaBeans
specification: a property name of <code>currentTime</code> maps to two methods:
<code>getCurrentTime()</code> and <code>setCurrentTime()</code>. If you omit
one or the other of these methods, the property is eithe
r read only (as here), or write only. (Keep in mind that as far as JavaBeans
properties go, it's the <em>methods</em> that count; the names of the instance
variables, or even whether they exist, is immaterial.)</p><p>Tapestry does go
one step further: it ignores case when matching properties inside the expansion
to properties of the page. In the template we could say ${currenttime} or
${CurrentTime} or any variation, and Tapestry will <em>still</em> invoke the
<code>getCurrentTime()</code> method.</p><p>Note that in Tapestry it is not
necessary to configure what object holds the <code>currentTime</code> property;
a template and a page are always used in combination with each other;
expressions are always rooted in the page instance, in this case, an instance
of the Index class.</p><p>The Index.tml template includes a second
expansion:</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;"> <p>${message:greeting}</p>
-</pre>
-</div></div><p>Here <code>greeting</code> is not a property of the page; its
actually a localized message key. Every Tapestry page and component is allowed
to have its own message catalog. (There's also a global message catalog,
<em>which we'll describe later</em>.)</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width:
1px;"><b>src/main/resources/com/example/tutorial/pages/Index.properties</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">greeting=Welcome to Tapestry 5! We hope that this
project template will get you going in style.
-</pre>
-</div></div><p>Message catalogs are useful for storing repeating strings
outside of code or templates, though their primary purpose is related to
localization of the application (which will be described in more detail in a
later chapter). Messages that may be used across multiple pages can be stored
in the application's global message catalog,
src/main/webapp/WEB-INF/app.properties, instead.</p><p>This "message:" prefix
is not some special case; there are actually quite a few of these <em>binding
prefixes</em> built into Tapestry, each having a specific purpose. In fact,
omitting a binding prefix in an expansion is exactly the same as using the
"prop:" binding prefix, which means to treat the binding as a property
expression.</p><p>Expansions are useful for extracting a piece of information
and rendering it out to the client as a string, but the real heavy lifting of
Tapestry occurs inside components.</p><h1
id="ExploringtheProject-ComponentsInsideTemplates">Components Inside Templa
tes</h1><p>Components can be represented inside a component template in two
ways:</p><ul><li>As an ordinary element, but with a t:type attribute to define
the type of component.</li></ul><ul><li>As an element in the Tapestry
namespace, in which case the element name determines the type.</li></ul><p>Here
we've used an <html> element to represent the application's Layout
component.</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 t:type="layout" ...>
+</plain-text-body><p>The first namespace, "t:", it used to identify
Tapestry-specific elements and attributes. Although there is an XSD (that is, a
XML schema definition), it is incomplete (for reasons explained
shortly).</p><p>The second namespace, "p:", is a way of marking a chunk of the
template as a parameter passed into another component. We'll expand on that
shortly.</p><p>A Tapestry component template consists mostly of standard XHTML
that will pass down to the client web browser unchanged. The dynamic aspects of
the template are represented by <em>components</em> and
<em>expansions</em>.</p><h1
id="ExploringtheProject-ExpansionsinTemplates">Expansions in
Templates</h1><p>Let's start with expansions. Expansions are an easy way of
including some dynamic output when rendering the page. By default, an expansion
refers to a JavaBeans property of the page:</p><parameter
ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body> <p>The curre
nt time is: ${currentTime}</p>
+</plain-text-body><p>The value inside the curly braces is a <em>property
expression</em>. Tapestry uses its own property expression language that is
expressive, fast, and type-safe.</p><rich-text-body><pre>Tapestry does NOT use
reflection to implement property expressions.</pre></rich-text-body><p>More
advanced property expressions can traverse multiple properties (for example,
<code>user.address.city</code>), or even invoke public methods. Here the
expansion simply reads the <code>currentTime</code> property of the
page.</p><p>Tapestry follows the rules defined by Sun's JavaBeans
specification: a property name of <code>currentTime</code> maps to two methods:
<code>getCurrentTime()</code> and <code>setCurrentTime()</code>. If you omit
one or the other of these methods, the property is either read only (as here),
or write only. (Keep in mind that as far as JavaBeans properties go, it's the
<em>methods</em> that count; the names of the instance variables, or even
whether they exist, i
s immaterial.)</p><p>Tapestry does go one step further: it ignores case when
matching properties inside the expansion to properties of the page. In the
template we could say ${currenttime} or ${CurrentTime} or any variation, and
Tapestry will <em>still</em> invoke the <code>getCurrentTime()</code>
method.</p><p>Note that in Tapestry it is not necessary to configure what
object holds the <code>currentTime</code> property; a template and a page are
always used in combination with each other; expressions are always rooted in
the page instance, in this case, an instance of the Index class.</p><p>The
Index.tml template includes a second expansion:</p><parameter
ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body>
<p>${message:greeting}</p>
+</plain-text-body><p>Here <code>greeting</code> is not a property of the page;
its actually a localized message key. Every Tapestry page and component is
allowed to have its own message catalog. (There's also a global message
catalog, <em>which we'll describe later</em>.)</p><parameter
ac:name="title">src/main/resources/com/example/tutorial/pages/Index.properties</parameter><plain-text-body>greeting=Welcome
to Tapestry 5! We hope that this project template will get you going in style.
+</plain-text-body><p>Message catalogs are useful for storing repeating strings
outside of code or templates, though their primary purpose is related to
localization of the application (which will be described in more detail in a
later chapter). Messages that may be used across multiple pages can be stored
in the application's global message catalog,
src/main/webapp/WEB-INF/app.properties, instead.</p><p>This "message:" prefix
is not some special case; there are actually quite a few of these <em>binding
prefixes</em> built into Tapestry, each having a specific purpose. In fact,
omitting a binding prefix in an expansion is exactly the same as using the
"prop:" binding prefix, which means to treat the binding as a property
expression.</p><p>Expansions are useful for extracting a piece of information
and rendering it out to the client as a string, but the real heavy lifting of
Tapestry occurs inside components.</p><h1
id="ExploringtheProject-ComponentsInsideTemplates">Components Inside
Templates</h1><p>Components can be represented inside a component template in
two ways:</p><ul><li>As an ordinary element, but with a t:type attribute to
define the type of component.</li></ul><ul><li>As an element in the Tapestry
namespace, in which case the element name determines the type.</li></ul><p>Here
we've used an <html> element to represent the application's Layout
component.</p><parameter ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body><html t:type="layout" ...>
...
</html>
-</pre>
-</div></div><p>But for the EventLink component, we've used an element in the
Tapestry namespace:</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;"><t:eventlink page="Index">refresh
page</t:eventlink>
-</pre>
-</div></div><p>Which form you select is a matter of choice. In the vast
majority of cases, they are exactly equivalent.</p><p>As elsewhere, case is
ignored. Here the types ("layout" and "eventlink") were in all lower case; the
actual class names are Layout and EventLink. Further, Tapestry "blends" the
core library components in with the components defined by this application;
thus type "layout" is mapped to application component class
com.example.tutorial.components.Layout, but "eventlink" is mapped to Tapestry's
built-in org.apache.tapestry5.corelib.components.EventLink
class.</p><p>Tapestry components are configured using parameters; for each
component, there is a set of parameters, each with a specific type and purpose.
Some parameters are required, others are optional. Attributes of the element
are used to <em>bind</em> parameters to specific literal values, or to page
properties. Tapestry is flexible here as well; you can always place an
attribute in the Tapestry namespace (usi
ng the "t:" prefix), but in most cases, this is unnecessary.</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 t:type="layout" title="tutorial1 Index"
+</plain-text-body><p>But for the EventLink component, we've used an element in
the Tapestry namespace:</p><parameter
ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body><t:eventlink
page="Index">refresh page</t:eventlink>
+</plain-text-body><p>Which form you select is a matter of choice. In the vast
majority of cases, they are exactly equivalent.</p><p>As elsewhere, case is
ignored. Here the types ("layout" and "eventlink") were in all lower case; the
actual class names are Layout and EventLink. Further, Tapestry "blends" the
core library components in with the components defined by this application;
thus type "layout" is mapped to application component class
com.example.tutorial.components.Layout, but "eventlink" is mapped to Tapestry's
built-in org.apache.tapestry5.corelib.components.EventLink
class.</p><p>Tapestry components are configured using parameters; for each
component, there is a set of parameters, each with a specific type and purpose.
Some parameters are required, others are optional. Attributes of the element
are used to <em>bind</em> parameters to specific literal values, or to page
properties. Tapestry is flexible here as well; you can always place an
attribute in the Tapestry namespac
e (using the "t:" prefix), but in most cases, this is
unnecessary.</p><parameter ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body><html t:type="layout"
title="tutorial1 Index"
p:sidebarTitle="Framework Version" ...
-</pre>
-</div></div><p>This binds two parameters, <code>title</code> and
<code>sidebarTitle</code>, of the Layout component to the literal strings
"tutorial1 Index" and "Framework Version", respectively.</p><p>The Layout
component will actually provide the bulk of the HTML ultimately sent to the
browser; we'll look at its template in a later chapter. The point is, the
page's template is integrated into the Layout component's template. The
following diagram shows how parameters passed to the Layout component end up
rendered in the final page:</p><p>
-
-
-
-
-<span class="gliffy-container" id="gliffy-container-24346949-9349"
data-fullwidth="913" data-ceoid="24188263"
data-edit="${diagramEditLink.getLinkUrl()}"
data-full="${diagramZoomLink.getLinkUrl()}" data-filename="Templates and
Parameters">
-
- <map id="gliffy-map-24346949-5348" name="gliffy-map-24346949-5348"></map>
-
- <img class="gliffy-image gliffy-image-border"
id="gliffy-image-24346949-9349" width="304" height="300" data-full-width="913"
data-full-height="901"
src="https://cwiki.apache.org/confluence/download/attachments/24188263/Templates%20and%20Parameters.png?version=2&modificationDate=1371888025000&api=v2";
alt="Templates and Parameters" usemap="#gliffy-map-24346949-5348">
-
- <map class="gliffy-dynamic" id="gliffy-dynamic-map-24346949-9349"
name="gliffy-dynamic-map-24346949-9349"></map>
-</span>
-
-
-</p><p>The interesting point here (and this is an advanced concept in
Tapestry, one we'll return to later) is that we can pass a chunk of the
Index.tml template to the Layout component as the <code>sidebar</code>
parameter. That's what the tapestry:parameter namespace (the "p:" prefix) is
for; the element name is matched against a parameter of the component and the
entire block of the template is passed into the Layout component ... which
decides where, inside <em>its</em> template, that block gets rendered.</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;"><t:eventlink event="complete" class="btn
btn-default">Complete&raquo;</t:eventlink>
-</pre>
-</div></div><p>This time, it's the <code>page</code> parameter of the PageLink
component that is bound, to the literal value "Index" (which is the name of
this page). This gets rendered as a URL that re-renders the page, which is how
the current time gets updated. You can also create links to other pages in the
application and, as we'll see in later chapters, attach additional information
to the URL beyond just the page name.</p><h1
id="ExploringtheProject-AMagicTrick">A Magic Trick</h1><p>Now it's time for a
magic trick. Edit Index.java and change the <code>getCurrentTime()</code>
method to:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Index.java (partial)</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> public String getCurrentTime()
+</plain-text-body><p>This binds two parameters, <code>title</code> and
<code>sidebarTitle</code>, of the Layout component to the literal strings
"tutorial1 Index" and "Framework Version", respectively.</p><p>The Layout
component will actually provide the bulk of the HTML ultimately sent to the
browser; we'll look at its template in a later chapter. The point is, the
page's template is integrated into the Layout component's template. The
following diagram shows how parameters passed to the Layout component end up
rendered in the final page:</p><p><parameter
ac:name="border">false</parameter><parameter
ac:name="size">S</parameter><parameter ac:name="name">Templates and
Parameters</parameter></p><p>The interesting point here (and this is an
advanced concept in Tapestry, one we'll return to later) is that we can pass a
chunk of the Index.tml template to the Layout component as the
<code>sidebar</code> parameter. That's what the tapestry:parameter namespace
(the "p:" prefix) is for; the
element name is matched against a parameter of the component and the entire
block of the template is passed into the Layout component ... which decides
where, inside <em>its</em> template, that block gets rendered.</p><parameter
ac:name="language">xml</parameter><parameter
ac:name="lang">xml</parameter><plain-text-body><t:eventlink event="complete"
class="btn btn-default">Complete&raquo;</t:eventlink>
+</plain-text-body><p>This time, it's the <code>page</code> parameter of the
PageLink component that is bound, to the literal value "Index" (which is the
name of this page). This gets rendered as a URL that re-renders the page, which
is how the current time gets updated. You can also create links to other pages
in the application and, as we'll see in later chapters, attach additional
information to the URL beyond just the page name.</p><h1
id="ExploringtheProject-AMagicTrick">A Magic Trick</h1><p>Now it's time for a
magic trick. Edit Index.java and change the <code>getCurrentTime()</code>
method to:</p><parameter ac:name="language">xml</parameter><parameter
ac:name="lang">java</parameter><parameter ac:name="title">Index.java
(partial)</parameter><plain-text-body> public String getCurrentTime()
{
return "A great day to learn Tapestry";
}
-</pre>
-</div></div><p>Make sure you save changes; then click the refresh link in the
web browser:</p><p><span class="confluence-embedded-file-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image"
width="700"
src="exploring-the-project.data/app-live-reload.png"></span></p><div
class="navmenu" style="float:right; width:30%; background:white; margin:3px;
padding:3px">
-<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>If Live Class Reloading isn't working for you, check the Troubleshooting
section at <a href="class-reloading.html" title="Class Reloading">Class
Reloading</a>.</p></div></div></div>This is one of Tapestry's early <em>wow
factor</em> features: changes to your component classes are picked up
immediately (a feature we call Live Class Reloading). No restart. No re-deploy.
Make the changes and see them <em>now</em>. Nothing should slow you down or get
in the way of you getting your job done.<p>But ... what if you make a mistake?
What if you got the name in the template wrong. Give it a try; in the template,
change ${currentTime} to, say, ${currenTime}, and see what you get:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" width="700"
src="exploring-the-project.data/app-error-1.png"></span></p><p>This is
Tapestry's exception report page. It's quite detailed. It clearly identifies
what Tapestry was doing, and re
lates the problem to a specific line in the template, which is shown in
context. Tapestry always expands out the entire stack of exceptions, because it
is so common for exceptions to be thrown, caught, and re-thrown inside other
exceptions. In fact, if we scroll down just a little bit, we see more detail
about this exception, plus a little bit of help:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" width="700"
src="exploring-the-project.data/app-error-2.png"></span></p><p>This is part of
Tapestry's way: it not only spells out exactly what it was doing and what went
wrong, but it even helps you find a solution; here it tells you the names of
properties you could have used.</p><div class="confluence-information-macro
confluence-information-macro-information"><span class="aui-icon aui-icon-small
aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This l
evel of detail reflects that the application has been configured to run in
<em>development mode</em> instead of <em>production mode</em>. In production
mode, the exception report would simply be the top level exception message.
However, most production applications go further and customize how Tapestry
handles and reports exceptions.</p></div></div><p>Tapestry displays the stack
trace of the deepest exception, along with lots of details about the run-time
environment: details about the current request, the HttpSession (if one
exists), and even a detailed list of all JVM system properties. Scroll down to
see all this information.</p><p>Next: <a
href="implementing-the-hi-lo-guessing-game.html">Implementing the Hi-Lo
Guessing Game</a></p><p> </p><p></p></div>
+</plain-text-body><p>Make sure you save changes; then click the refresh link
in the web browser:</p><p><span class="confluence-embedded-file-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image"
width="700"
src="exploring-the-project.data/app-live-reload.png"></span><plain-text-body>{float:right|width=30%}
+{note}
+If Live Class Reloading isn't working for you, check the Troubleshooting
section at [Class Reloading].
+{note}
+{float}</plain-text-body>This is one of Tapestry's early <em>wow factor</em>
features: changes to your component classes are picked up immediately (a
feature we call Live Class Reloading). No restart. No re-deploy. Make the
changes and see them <em>now</em>. Nothing should slow you down or get in the
way of you getting your job done.</p><p>But ... what if you make a mistake?
What if you got the name in the template wrong. Give it a try; in the template,
change ${currentTime} to, say, ${currenTime}, and see what you get:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" width="700"
src="exploring-the-project.data/app-error-1.png"></span></p><p>This is
Tapestry's exception report page. It's quite detailed. It clearly identifies
what Tapestry was doing, and relates the problem to a specific line in the
template, which is shown in context. Tapestry always expands out the entire
stack of exceptions, because it is s
o common for exceptions to be thrown, caught, and re-thrown inside other
exceptions. In fact, if we scroll down just a little bit, we see more detail
about this exception, plus a little bit of help:</p><p><span
class="confluence-embedded-file-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image" width="700"
src="exploring-the-project.data/app-error-2.png"></span></p><p>This is part of
Tapestry's way: it not only spells out exactly what it was doing and what went
wrong, but it even helps you find a solution; here it tells you the names of
properties you could have used.</p><rich-text-body><p>This level of detail
reflects that the application has been configured to run in <em>development
mode</em> instead of <em>production mode</em>. In production mode, the
exception report would simply be the top level exception message. However, most
production applications go further and customize how Tapestry handles and
reports exceptions.</p></rich-text-body><p>Tapestry
displays the stack trace of the deepest exception, along with lots of details
about the run-time environment: details about the current request, the
HttpSession (if one exists), and even a detailed list of all JVM system
properties. Scroll down to see all this information.</p><p>Next: <a
href="implementing-the-hi-lo-guessing-game.html">Implementing the Hi-Lo
Guessing Game</a></p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/extending-the-if-component.html
==============================================================================
--- websites/production/tapestry/content/extending-the-if-component.html
(original)
+++ websites/production/tapestry/content/extending-the-if-component.html Tue
Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,8 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h1
id="ExtendingtheIfComponent-ExtendingtheIfComponent">Extending the If
Component</h1><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/If.html";>If</a>
component can be made very flexible; its main parameter, <code>test</code>,
does not <em>have</em> to be bound to a boolean value, it merely has to be
bound to a value that can be <a href="type-coercion.html">coerced</a> to
boolean.</p><p>For example, you may be working on an application that does a
lot of <a class="external-link"
href="http://lucene.apache.org/java/docs/index.html";>Lucene</a> searches, and
you represent the results as a SearchResult object:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>SearchResult.java</b></div><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class SearchResult<T> {
+ <div
id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><parameter
ac:name="hidden">true</parameter><parameter
ac:name="atlassian-macro-output-type">BLOCK</parameter><rich-text-body><p>Adding
a type coercion to enable the If component to test for
anything</p></rich-text-body><h1
id="ExtendingtheIfComponent-ExtendingtheIfComponent">Extending the If
Component</h1><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/If.html";>If</a>
component can be made very flexible; its main parameter, <code>test</code>,
does not <em>have</em> to be bound to a boolean value, it merely has to be
bound to a value that can be <a href="type-coercion.html">coerced</a> to
boolean.</p><p>For example, you may be working on an application that does a
lot of <a class="external-link"
href="http://lucene.apache.org/java/docs/index.html";>Lucene</a> searches, and
you represent the results as a SearchResult obje
ct:</p><parameter ac:name="language">java</parameter><parameter
ac:name="title">SearchResult.java</parameter><plain-text-body>public class
SearchResult<T> {
public final Class<T> itemType;
public final List<T> items;
public final int size;
@@ -100,16 +89,12 @@
return size == 0;
}
}
-</pre>
-</div></div><p>In a SearchResult, the <code>size</code> property is the
overall number of results from the search. The <code>items</code> list is a
single "page" of those results to present to the user, consisting of items from
<code>firstIndex</code> to <code>lastIndex</code> within the overall
set.</p><p>In your templates, you have to check to see if the SearchResult
exists, then see if it is empty, before you can get to the part that displays
the content:</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;"><t:if test="searchResult">
+</plain-text-body><p>In a SearchResult, the <code>size</code> property is the
overall number of results from the search. The <code>items</code> list is a
single "page" of those results to present to the user, consisting of items from
<code>firstIndex</code> to <code>lastIndex</code> within the overall
set.</p><p>In your templates, you have to check to see if the SearchResult
exists, then see if it is empty, before you can get to the part that displays
the content:</p><parameter
ac:name="language">xml</parameter><plain-text-body><t:if
test="searchResult">
<t:if test="! searchResult.empty">
. . .
</t:if>
</t:if>
-</pre>
-</div></div><p>The first test checks to see if <code>searchResult</code> is
not null (null is treated as false). The second checks to see if the search
result is empty.</p><p>What we'd like is for the test to look at the
<code>searchResult</code> directly and treat an empty search result as false,
and a non-empty search result as true. This is similar to what Tapestry already
does for Collections.</p><p>This is just a matter of extending the TypeCoercer
service:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent
pdl">
-<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public static void
contributeTypeCoercer(Configuration<CoercionTuple> configuration) {
+</plain-text-body><p>The first test checks to see if <code>searchResult</code>
is not null (null is treated as false). The second checks to see if the search
result is empty.</p><p>What we'd like is for the test to look at the
<code>searchResult</code> directly and treat an empty search result as false,
and a non-empty search result as true. This is similar to what Tapestry already
does for Collections.</p><p>This is just a matter of extending the TypeCoercer
service:</p><parameter ac:name="language">java</parameter><parameter
ac:name="title">AppModule.java (partial)</parameter><plain-text-body>public
static void contributeTypeCoercer(Configuration<CoercionTuple>
configuration) {
add(configuration, SearchResult.class, Boolean.class,
new Coercion<SearchResult, Boolean>() {
@@ -126,13 +111,10 @@ private static <S, T> void add(Con
configuration.add(tuple);
}
-</pre>
-</div></div><p>Inside this thicket of generics and brackets is the code that
treats a SearchResult as a boolean: <code>return
!input.isEmpty();</code>.</p><p>With this in place, the previous template can
be simplified:</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;"><t:if test="searchResult">
+</plain-text-body><p>Inside this thicket of generics and brackets is the code
that treats a SearchResult as a boolean: <code>return
!input.isEmpty();</code>.</p><p>With this in place, the previous template can
be simplified:</p><parameter
ac:name="language">xml</parameter><plain-text-body><t:if
test="searchResult">
. . .
</t:if>
-</pre>
-</div></div><p>The single test now implies that <code>searchResult</code> is
not null and not empty.</p></div>
+</plain-text-body><p>The single test now implies that
<code>searchResult</code> is not null and not empty.</p></div>
</div>
<div class="clearer"></div>
Modified:
websites/production/tapestry/content/forms-and-form-components-faq.html
==============================================================================
--- websites/production/tapestry/content/forms-and-form-components-faq.html
(original)
+++ websites/production/tapestry/content/forms-and-form-components-faq.html Tue
Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,8 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h2
id="FormsandFormComponentsFAQ-FormsandFormComponents">Forms and Form
Components</h2><p>Main article: <a href="forms-and-validation.html">Forms and
Validation</a></p><h3
id="FormsandFormComponentsFAQ-Whatisthet:formdatahiddenfieldfor?">What is the
<code>t:formdata</code> hidden field for?</h3><p>In Tapestry, rendering a form
can be a complicated process; inside the body of the Form component are many of
field components: TextField, Select, TextArea, and so forth. Each of these must
pull data out of your data model and convert it to the string form used inside
the client web browser. In addition, JavaScript to support client-side
validation must be generated. This can be further complicated by the use of
Loop and If components, or made really complicated by the use of Block (to
render portions of other pages: this is what the BeanEditForm component
does).</p><p>Along the way, the Form is generating unique form control names
for each fie
ld component, as it renders.</p><p>When the client-side Form is submitted, an
event is triggered on the server-side Form component. It now needs to locate
each component, in turn, inform the component of its control name, and allow
the component to read the corresponding query parameter. The component then
converts the client-side string back into a server-side value and performs
validations before updating the data model.</p><p>That's where
<code>t:formdata</code> comes in. While components are rendering, they are
using the FormSupport environmental object to record callbacks:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>FormSupport.java
(partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default"
style="font-size:12px;">public interface FormSupport extends ClientElement
+ <div
id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><h2
id="FormsandFormComponentsFAQ-FormsandFormComponents">Forms and Form
Components</h2><p>Main article: <a href="forms-and-validation.html">Forms and
Validation</a></p><h3
id="FormsandFormComponentsFAQ-Whatisthet:formdatahiddenfieldfor?">What is the
<code>t:formdata</code> hidden field for?</h3><p>In Tapestry, rendering a form
can be a complicated process; inside the body of the Form component are many of
field components: TextField, Select, TextArea, and so forth. Each of these must
pull data out of your data model and convert it to the string form used inside
the client web browser. In addition, JavaScript to support client-side
validation must be generated. This can be further complicated by the use of
Loop and If components, or made really complicated by the use of Block (to
render portions of other pages: this is what the BeanEditForm component
does).</p><p>Along the way, the Form is gen
erating unique form control names for each field component, as it
renders.</p><p>When the client-side Form is submitted, an event is triggered on
the server-side Form component. It now needs to locate each component, in turn,
inform the component of its control name, and allow the component to read the
corresponding query parameter. The component then converts the client-side
string back into a server-side value and performs validations before updating
the data model.</p><p>That's where <code>t:formdata</code> comes in. While
components are rendering, they are using the FormSupport environmental object
to record callbacks:</p><parameter
ac:name="controls">true</parameter><parameter ac:name="title">FormSupport.java
(partial)</parameter><parameter
ac:name="linenumbers">true</parameter><plain-text-body>public interface
FormSupport extends ClientElement
{
/**
* Stores an action for execution during a later request. If the action
contains any mutable state, it should be in
@@ -95,25 +84,16 @@
* @param action the action that will be triggered (and passed the
component)
*/
<T> void storeAndExecute(T component, ComponentAction<T>
action);
-</pre>
-</div></div><p>The <code>ComponentAction</code> objects are the callbacks.
<code>t:formdata</code> is simply an object stream of these callbacks,
compressed and encoded in Base64. When using Ajax, you may see multiple
<code>t:formdata</code> hidden fields (they are processed one after
another).</p><h3
id="FormsandFormComponentsFAQ-HowdoIchangethelabelforafieldonthefly?">How do I
change the label for a field on the fly?</h3><p>Tapestry tries to be smart
about generating the label string for a field. It has some smart default logic,
first checking for the <em>component-id</em><code>-label</code> in the
container's message catalog, then ultimately converting the component's id into
a user-presentable label.</p><p>You can override the label in two
ways:</p><p>First, you can supply a body to the <code>Label</code>
component:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default"
style="font-size:12px;"> <t:label
for="username">${usernameLabel}</t:label>
+</plain-text-body><p>The <code>ComponentAction</code> objects are the
callbacks. <code>t:formdata</code> is simply an object stream of these
callbacks, compressed and encoded in Base64. When using Ajax, you may see
multiple <code>t:formdata</code> hidden fields (they are processed one after
another).</p><h3
id="FormsandFormComponentsFAQ-HowdoIchangethelabelforafieldonthefly?">How do I
change the label for a field on the fly?</h3><p>Tapestry tries to be smart
about generating the label string for a field. It has some smart default logic,
first checking for the <em>component-id</em><code>-label</code> in the
container's message catalog, then ultimately converting the component's id into
a user-presentable label.</p><p>You can override the label in two
ways:</p><p>First, you can supply a body to the <code>Label</code>
component:</p><parameter ac:name="controls">true</parameter><parameter
ac:name="linenumbers">true</parameter><plain-text-body> <t:label
for="username">${usernameLa
bel}</t:label>
<t:textfield t:id="username"/>
-</pre>
-</div></div><p>Here, the component class must provide a
<code>usernameLabel</code> property. That property becomes the text of the
label. An implementation of the property might look something like:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default"
style="font-size:12px;"> public String getUsernameLabel()
+</plain-text-body><p>Here, the component class must provide a
<code>usernameLabel</code> property. That property becomes the text of the
label. An implementation of the property might look something
like:</p><parameter ac:name="controls">true</parameter><parameter
ac:name="linenumbers">true</parameter><plain-text-body> public String
getUsernameLabel()
{
return systemPreferences.useEmailAddressForUserName() ? "Email address" :
"User name";
}
-</pre>
-</div></div><p>However, if there are any validations on the field, the error
message will include the default label (as discussed above).</p><p>To uniformly
update the label both on the page, and in any validation messages, bind the
TextField's <code>label</code> parameter:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default"
style="font-size:12px;"> <t:label for="username"/>
+</plain-text-body><p>However, if there are any validations on the field, the
error message will include the default label (as discussed above).</p><p>To
uniformly update the label both on the page, and in any validation messages,
bind the TextField's <code>label</code> parameter:</p><parameter
ac:name="controls">true</parameter><parameter
ac:name="linenumbers">true</parameter><plain-text-body> <t:label
for="username"/>
<t:textfield t:id="username" label="prop:usernameLabel"/>
-</pre>
-</div></div><p>The "prop:" prefix identifies that "usernameLabel" is to be
interpreted as a property expression (normally, the binding for the
<code>label</code> parameter is interpreted as a string literal). The Label
component gets the text it displays from the TextField component, and the
TextField component uses the same text when generating server-side and
client-side validation messages.</p><h3
id="FormsandFormComponentsFAQ-Tapestryfocusesonthewrongfieldinmyform,howdoIfixthat?">Tapestry
focuses on the wrong field in my form, how do I fix that?</h3><p>Tapestry
normally figures out the correct field in your form to initially receive focus;
this is based on assigning a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/FieldFocusPriority.html";>FieldFocusPriority</a>
to each field as it renders, which works out to the following
logic:</p><ul><li>The first field which has an error</li><li>Or, the first
field which is required</li><li>Or,
the first field</li></ul><p>Occasionally, due a wide range of factors beyond
Tapestry's control, it's selection will not be quite what you want, and it is
necessary to supply an override. The information is tracked inside the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>
environmental. It's just a matter of injecting the component so that you can
determine its client id, then informing JavaScriptSupport about your
override.</p><p>Here's an 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;"> <t:textfield t:id="email"
t:mixins="OverrideFieldFocus" .../>
-</pre>
-</div></div><p>The <a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/OverrideFieldFocus.html";>OverrideFieldFocus</a>
mixin forces the email field to be the focus field, regardless.</p></div>
+</plain-text-body><p>The "prop:" prefix identifies that "usernameLabel" is to
be interpreted as a property expression (normally, the binding for the
<code>label</code> parameter is interpreted as a string literal). The Label
component gets the text it displays from the TextField component, and the
TextField component uses the same text when generating server-side and
client-side validation messages.</p><h3
id="FormsandFormComponentsFAQ-Tapestryfocusesonthewrongfieldinmyform,howdoIfixthat?">Tapestry
focuses on the wrong field in my form, how do I fix that?</h3><p>Tapestry
normally figures out the correct field in your form to initially receive focus;
this is based on assigning a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/FieldFocusPriority.html";>FieldFocusPriority</a>
to each field as it renders, which works out to the following
logic:</p><ul><li>The first field which has an error</li><li>Or, the first
field which is required</li><
li>Or, the first field</li></ul><p>Occasionally, due a wide range of factors
beyond Tapestry's control, it's selection will not be quite what you want, and
it is necessary to supply an override. The information is tracked inside the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>
environmental. It's just a matter of injecting the component so that you can
determine its client id, then informing JavaScriptSupport about your
override.</p><p>Here's an example</p><plain-text-body> <t:textfield
t:id="email" t:mixins="OverrideFieldFocus" .../>
+</plain-text-body><p>The <a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/mixins/OverrideFieldFocus.html";>OverrideFieldFocus</a>
mixin forces the email field to be the focus field,
regardless.</p><plain-text-body>{scrollbar}</plain-text-body></div>
</div>
<div class="clearer"></div>
![https://cwiki.apache.org/confluence/download/attachments/24188263/Templates%20and%20Parameters.png?version=2&modificationDate=1371888025000&api=v2"](https://cwiki.apache.org/confluence/download/attachments/24188263/Templates%20and%20Parameters.png?version=2&modificationDate=1371888025000&api=v2"){kind=link}