Author: buildbot
Date: Sun Feb 18 23:21:05 2018
New Revision: 1025573
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/application-module-class-cheat-sheet.html
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-cheat-sheet.html
Modified:
websites/production/tapestry/content/application-module-class-cheat-sheet.html
==============================================================================
---
websites/production/tapestry/content/application-module-class-cheat-sheet.html
(original)
+++
websites/production/tapestry/content/application-module-class-cheat-sheet.html
Sun Feb 18 23:21:05 2018
@@ -76,11 +76,11 @@
<div id="content">
<div id="ConfluenceContent"><p> </p><p>The
<strong>Application Module</strong> class is a simple Java class used to
configure Tapestry. A system of annotations and naming conventions allows
Tapestry to determine what services are provided by the module to your
application. This is the place where you bind your custom implementation of
services, contribute to, decorate and override existing services.</p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1518405664290 {padding: 0px;}
-div.rbtoc1518405664290 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1518405664290 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1518996049804 {padding: 0px;}
+div.rbtoc1518996049804 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1518996049804 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1518405664290">
+/*]]>*/</style></p><div class="toc-macro rbtoc1518996049804">
<ul class="toc-indentation"><li>Related Articles</li></ul>
<ul><li><a href="#ApplicationModuleClassCheatSheet-Namingconventions">Naming
conventions</a>
<ul class="toc-indentation"><li><a
href="#ApplicationModuleClassCheatSheet-Thebindmethod">The bind
method</a></li><li><a
href="#ApplicationModuleClassCheatSheet-Servicebuildermethods">Service builder
methods</a></li><li><a
href="#ApplicationModuleClassCheatSheet-Contributemethods">Contribute
methods</a>
@@ -160,7 +160,7 @@ div.rbtoc1518405664290 li {margin-left:
</div>
-<p>For complete documentation, you should refer to the <a
href="application-module-class-cheat-sheet.html">IOC Service
guideline</a>.</p><h2
id="ApplicationModuleClassCheatSheet-Namingconventions">Naming
conventions</h2><p>The use of naming conventions implies that every public
method of your module class should be meaningful to Tapestry: it either should
follow the naming conventions, or should have an appropriate annotation. Any
extra public methods will result in startup exceptions ... this helps identify
methods names that have typos.</p><p>Methods should be <strong>public</strong>
and, preferably <strong>static</strong>.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Allowing for non-static methods
may have been a design error, a kind of premature optimization. The thinking
was that the module coul
d have common dependencies that it could then easily access when building
services. This was partly about runtime efficiency but mostly about reducing
redundancy in the various service building, contribution, and decorating
methods; the ServiceBinder came later, and was a better solution (trading
runtime efficiency for developer ease of use).</p></div></div><h3
id="ApplicationModuleClassCheatSheet-Thebindmethod">The bind
method</h3><p>Every module may have an optional, static bind() method which is
passed a ServiceBinder. By using the ServiceBinder, you will let Tapestry
<em>autobuild</em> your services. Autobuilding is the <strong>preferred
way</strong> to instantiate your services.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p>For complete documentation, you should refer to the <a
href="defining-tapestry-ioc-services.html">IOC Service guideline</a>.</p><h2
id="ApplicationModuleClassCheatSheet-Namingconventions">Naming
conventions</h2><p>The use of naming conventions implies that every public
method of your module class should be meaningful to Tapestry: it either should
follow the naming conventions, or should have an appropriate annotation. Any
extra public methods will result in startup exceptions ... this helps identify
methods names that have typos.</p><p>Methods should be <strong>public</strong>
and, preferably <strong>static</strong>.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Allowing for non-static methods
may have been a design error, a kind of premature optimization. The thinking
was that the module could have
common dependencies that it could then easily access when building services.
This was partly about runtime efficiency but mostly about reducing redundancy
in the various service building, contribution, and decorating methods; the
ServiceBinder came later, and was a better solution (trading runtime efficiency
for developer ease of use).</p></div></div><h3
id="ApplicationModuleClassCheatSheet-Thebindmethod">The bind
method</h3><p>Every module may have an optional, static bind() method which is
passed a ServiceBinder. By using the ServiceBinder, you will let Tapestry
<em>autobuild</em> your services. Autobuilding is the <strong>preferred
way</strong> to instantiate your services.</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;">package org.example.myapp.services;
import org.apache.tapestry5.ioc.ServiceBinder;
@@ -220,7 +220,7 @@ public class MyAppModule
configuration.add(myTuple);
}
</pre>
-</div></div><h3 id="ApplicationModuleClassCheatSheet-Decoratemethods">Decorate
methods</h3><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Annotations">Annotations</h2><p>Main
Article: <a href="application-module-class-cheat-sheet.html">Application
Module Class Cheat Sheet</a></p><p>Tapestry 5.2 comes with a set of annotations
to better your understanding of module classes.</p><p><em>content under
development</em></p><h2
id="ApplicationModuleClassCheatSheet-parameter-typesParametertypes"><span
class="confluence-anchor-link"
id="ApplicationModuleClassCheatSheet-parameter-types"></span>Parameter
types</h2><p>These methods may have any number of parameters, tapestry will try
to resolve each parameter value as a configuration element or a registry
element.</p><h3
id="ApplicationModuleClassCheatSheet-Configurationparametertypes">Configuration
parameter types</h3><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-Linktoserv
ices">Link to services</h3><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-Symbols">Symbols</h3><p>Main Article: <a
href="application-module-class-cheat-sheet.html">Application Module Class Cheat
Sheet</a></p><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Loadservicesonregistrystartup">Load
services on registry startup</h2><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Defineservicescope">Define service
scope</h2><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Disambiguateservices">Disambiguate
services</h2><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-WithserviceId">With service
Id</h3><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-WithMarkers">With
Markers</h3><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Overrideexistingservices">Override
existing services</h2><p><em>content under
development</em></p><p> </p><p></p></div>
+</div></div><h3 id="ApplicationModuleClassCheatSheet-Decoratemethods">Decorate
methods</h3><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Annotations">Annotations</h2><p>Main
Article: <a href="annotations.html">Annotations</a></p><p>Tapestry versions
5.2 and later come with a set of annotations that are commonly used in module
classes.</p><p>See <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/package-summary.html";>this
list of IOC annotations</a></p><h2
id="ApplicationModuleClassCheatSheet-parameter-typesParametertypes"><span
class="confluence-anchor-link"
id="ApplicationModuleClassCheatSheet-parameter-types"></span>Parameter
types</h2><p>These methods may have any number of parameters, tapestry will try
to resolve each parameter value as a configuration element or a registry
element.</p><h3
id="ApplicationModuleClassCheatSheet-Configurationparametertypes">Configuration
parameter type
s</h3><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-Linktoservices">Link to
services</h3><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-Symbols">Symbols</h3><p>Main Article: <a
href="symbols.html">Symbols</a></p><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Loadservicesonregistrystartup">Load
services on registry startup</h2><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Defineservicescope">Define service
scope</h2><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheatSheet-Disambiguateservices">Disambiguate
services</h2><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-WithserviceId">With service
Id</h3><p><em>content under development</em></p><h3
id="ApplicationModuleClassCheatSheet-WithMarkers">With
Markers</h3><p><em>content under development</em></p><h2
id="ApplicationModuleClassCheat
Sheet-Overrideexistingservices">Override existing services</h2><p><em>content
under development</em></p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-cheat-sheet.html
==============================================================================
--- websites/production/tapestry/content/component-cheat-sheet.html (original)
+++ websites/production/tapestry/content/component-cheat-sheet.html Sun Feb 18
23:21:05 2018
@@ -100,7 +100,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="templating-and-markup-faq.html">Templating
and Markup FAQ</a>
+ <a href="component-reference.html">Component
Reference</a>
</div>
@@ -109,7 +109,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-classes.html">Component Classes</a>
+ <a href="component-libraries.html">Component
Libraries</a>
</div>
@@ -118,7 +118,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-reference.html">Component
Reference</a>
+ <a href="templating-and-markup-faq.html">Templating
and Markup FAQ</a>
</div>
@@ -127,7 +127,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-libraries.html">Component
Libraries</a>
+ <a href="component-classes.html">Component Classes</a>
</div>
@@ -162,13 +162,13 @@
</div>
-<p>For an exhaustive list, see the <a
href="component-cheat-sheet.html">annotations list</a>.</p><h2
id="ComponentCheatSheet-FieldInjectionAnnotations">Field Injection
Annotations</h2><p>Main articles: <a
href="component-cheat-sheet.html">Component Cheat Sheet</a>, <a
href="component-cheat-sheet.html">Component Cheat Sheet</a>, <a
href="component-cheat-sheet.html">Component Cheat Sheet</a></p><h3
id="ComponentCheatSheet-@Inject">@Inject</h3><p>@Inject is the Swiss Army knife
of annotations; it's designed to connect your component to services, resources,
and other objects. See <a href="component-cheat-sheet.html">Component Cheat
Sheet</a>.</p><h4 id="ComponentCheatSheet-ServiceInjection">Service
Injection</h4><p>In most cases, the injected value is a service; the service is
located by type. If there are ambiguities, caused by multiple services
implementing the same interface, you'll see injection exceptions. You can
resolve those exceptions by adding marker annotations to select
a specific service, or by adding @Service to specify the specific service ID
you want.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Use of @Service is discouraged. If
marker annotations are available, that is preferred.</p></div></div><h3
id="ComponentCheatSheet-@InjectComponent">@InjectComponent</h3><p>Injects a
component from this component's template into this component's class. Injecting
a component is based on the component's ID, which should match the field name.
However, the value attribute of the @InjectComponent annotation can be
specified as well, this takes precedence over the field name.</p><p>It is
common to inject a component in order to obtain its client-side ID (used when
generating client-side JavaScript).</p><h3
id="ComponentCheatSheet-@InjectContainer">@InjectContainer</h3><p>Inject
s the container of a component or, when used in a mixin, injects the component
the mixin is attached to.</p><h3
id="ComponentCheatSheet-@InjectPage">@InjectPage</h3><p>Injects a page of the
application. Normally, the page to inject is identified based on the field
type. The value attribute can be specified, in which case the page to be
injected is identified by name.</p><h3
id="ComponentCheatSheet-@Environmental">@Environmental</h3><p>Injects an <a
href="component-cheat-sheet.html">environmental object</a>; such objects are
request scoped but may be overridden at any time using the methods of the
Environment service. Environmental objects are used to allow outer components
to communicate with components they enclose.</p><p>Most often, @Environmental
is used with type JavaScriptSupport, which is used to add JavaScript code and
libraries to the rendered page.</p><h2
id="ComponentCheatSheet-FieldBehaviorAnnotations">Field Behavior
Annotations</h2><p>Main articles: <a href="component-
cheat-sheet.html">Component Cheat Sheet</a>, <a
href="component-cheat-sheet.html">Component Cheat Sheet</a></p><h3
id="ComponentCheatSheet-@PageActivationContext">@PageActivationContext</h3><p>This
annotation is allowed on a <em>single</em> field; the value of the field will
be included in URLs for the page as the page's activation context. This is an
alternative to implementing event handler methods<br clear="none"> for the
activate and passivate events directly.</p><h3
id="ComponentCheatSheet-@Parameter">@Parameter</h3><p>Marks the field as a
component parameter. Attributes of the annotation allow the parameter to be
marked as required or optional. If the parameter value will typically be a
literal string (for example, the title parameter to a Layout component), you
should add <code>defaultPrefix=BindingConstants.LITERAL</code> to the
annotation so that users of the component won't have to use the "literal:"
binding prefix with the parameter. See <a href="component-cheat-sheet.h
tml">Component Cheat Sheet</a></p><h3
id="ComponentCheatSheet-@Persist">@Persist</h3><p>Marks the field as a
persistent value, one that maintains its value between requests. The default
<em>strategy</em> is to simply store the value in the session (which is created
as needed). Other strategies can be specified by name as the value attribute.
See <a href="component-cheat-sheet.html">Component Cheat Sheet</a>.</p><h3
id="ComponentCheatSheet-@Property">@Property</h3><p>Directs Tapestry to
automatically generate a getter and a setter for the field, converting it to a
JavaBeans property than can be referenced from the template.</p><h3
id="ComponentCheatSheet-@SessionState">@SessionState</h3><p>Marks the field as
a Session State Object (SSO). SSOs store global data, and can be injected into
any page or component. The SSOs are stored in the session, using a key based on
the Java type. SSOs are usually created on demand, but the <code>create</code>
attribute can turn this off. See <a href
="component-cheat-sheet.html">Component Cheat Sheet</a></p><h3
id="ComponentCheatSheet-@SessionAttribute">@SessionAttribute</h3><p>In Tapestry
5.2 and later, marks the field as a Session Attribute. Like Session State
Objects (SSO), a Session Attribute is stored in the session, however Session
Attributes are stored by using a name you choose rather than based on the Java
type. See <a href="component-cheat-sheet.html">Component Cheat
Sheet</a>.</p><h3
id="ComponentCheatSheet-@ActivationRequestParameter">@ActivationRequestParameter</h3><p>Fields
with this annotation will be encoded into URLs as query parameters, in much
the same way as data is encoded into the URL path. The query parameter name
matches the field name, unless the value attribute is specified.</p><h2
id="ComponentCheatSheet-MethodAnnotations">Method Annotations</h2><p>Main
articles: <a href="component-cheat-sheet.html">Component Cheat Sheet</a>, <a
href="component-cheat-sheet.html">Component Cheat Sheet</a></p><h3 id=
"ComponentCheatSheet-@OnEvent">@OnEvent</h3><p>Marks a method as an event
handler method. Such methods may have any visibility, and typically use package
private visibility (that is, no visibility keyword at all). By default, the
method will handle the action event from any component; the value attribute
controls the matched event, and the component annotation is used to limit the
event source.</p><p>An event handler method may take parameters, corresponding
the event context associated with the event, such as the page activation
context for the activate event. The method will not be invoked if it defines
more parameters than there are values in the context.</p><p>The
@RequestParameter annotation can be used on parameters, in which case the
parameters value comes from a request query parameter, and not from the event
context.</p><p>Events fired on a component bubble up the component's container.
Return a non-null value to cancel event bubbling. What values may be returned
from an ev
ent handler method is dependent on the type of event.</p><p>You may also
return true to indicate that the event is handled and bubbling should cancel
(even for events that do not permit a return value).</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>An alternative to @OnEvent is the
naming convention <code>on</code><em>EventName</em> or
<code>on</code><em>EventName</em><code>From</code><em>ComponentId</em>.</p></div></div><h3
id="ComponentCheatSheet-@Log">@Log</h3><p>Marks the method to be logged for
debugging purposes: method entry (with parameters) and exit (with return value)
will be logged at debug level, as will any thrown exception. This is primarily
for debugging purposes. The Logger name will match the component classes' fully
qualified class name.</p><h3 id="ComponentCheatSheet-@CommitAfter">@Co
mmitAfter</h3><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>The support for this annotation
comes from the <a href="component-cheat-sheet.html">tapestry-hibernate</a>
module or tapestry-jpa module.</p></div></div><h3
id="ComponentCheatSheet-@Cached">@Cached</h3><p>Used on methods that perform
expensive operations, such as database queries. The first time such a method is
invoked, the return value is cached. Future invocations of the same method
return the cached value.</p><p>The result cache is per-request and is discarded
at the end of the request.</p><p>@Cached only works on methods that take no
parameters.</p><h2 id="ComponentCheatSheet-ParameterAnnotations">Parameter
Annotations</h2><p>Main article: <a
href="component-cheat-sheet.html">Component Cheat Sheet</a></p><h3
id="ComponentCheatSheet-@Request
Parameter">@RequestParameter</h3><p>Used with event handler methods to get the
value for the parameter from a request query parameter.</p><h2
id="ComponentCheatSheet-TypeAnnotations">Type Annotations</h2><h3
id="ComponentCheatSheet-@Events">@Events</h3><p>Lists the names of events that
may be fired from within this component; used for documentation purposes
only.</p><h3 id="ComponentCheatSheet-@Import">@Import</h3><p>Allows JavaScript
libraries and CSS stylesheet files to be included in the rendered page. Each
such file is added to the page only once, in the order in which the page
renders.</p><p>It is allowed to use symbol expansions (with the
<code>${...</code>} syntax) inside a library or stylesheet path.</p><p>@Import
may also be applied to individual methods, in which case the import operation
only occurs when the method is invoked.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning confluence
-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>When specifying a file to import,
you'll often use the prefix <code>context:</code> to indicate that the file is
stored in the web application context, and not on the classpath. Relative paths
will be on the classpath, relative to the Java class.</p></div></div><h3
id="ComponentCheatSheet-@SupportsInformalParameters">@SupportsInformalParameters</h3><p>Marks
the component as allowing informal parameters (extra attributes in the
template that do not match formally declared parameters). Normally, informal
parameters are simply discarded.</p><p>The method
ComponentResources.renderInformalParameters() can be used to include the
informal parameters within the element rendered by your component.</p><h3
id="ComponentCheatSheet-@Secure">@Secure</h3><p>Marks the page as accessible
only via secure (HTTPs). Any attempt to access the page via standard HTTP will
be redirected to the HTTPs version.</p><p>By default,
the @Secure annotation is ignored in development mode and only active in
production mode.</p><h2 id="ComponentCheatSheet-RenderPhaseMethods">Render
Phase Methods</h2><p>Main article: <a
href="component-cheat-sheet.html">Component Cheat Sheet</a></p><p>Render phase
methods are close cousins to event handler methods; they are how Tapestry
integrates your code into the overall rendering of the page. For each render
phase, there's an annotation and corresponding naming convention to define a
render phase method:</p><div class="table-wrap"><table
class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1"
class="confluenceTh"><p>Annotation</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Method Name</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>General Use</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>@SetupRender</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td colspan="1"
rowspan="1" class="conflue
nceTd"><p>Initializes the component before rendering</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>@BeginRender</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Renders the element and primary
attributes of the component</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@AfterRender</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>afterRender()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Closes the element started in
beginRender()</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@CleanupRender</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>cleanupRender()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Performs cleanup after all rendering of the component
finishes</p></td></tr></tbody></table></div><p>Render phase methods either take
no parameters, or take a single parameter of type Mark
upWriter.</p><p>Render phase methods may return <code>void</code>, a
<code>boolean</code>, or a <em>renderable object</em>.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Generally, a <code>renderable
object</code> is a <a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/Block.html";>Block</a>
or a component. The object is pushed onto the stack of rendering operations,
temporarily replacing the current component as the object to be
rendered.</p></div></div><p>Returning true is the same as returning void; it
means that the component should follow the typical
flow:</p><ul><li>@SetupRender</li><li>@BeginRender</li><li>Render the
component's template, if any</li><li>Render the component's
body</li><li>@AfterRender</li><li>@CleanupRender</li></ul><p>If a component has
a
template, the component's body will only render if the template contains a
<t:body> element. If a component has no template, then it will always
render its body (between @BeginRender and @AfterRender).</p><p>A render phase
method may also return false, in which case the flow continues to an alternate
render phase, as per the chart in the <a
href="component-cheat-sheet.html">Component Cheat Sheet</a> reference
page.</p><p>The most common cases:</p><ul><li>return <code>false</code> from
@BeginRender to skip the rendering of the component's template and/or body, and
continue with @AfterRender</li><li>return <code>false</code> from @AfterRender
to return to @BeginRender (this is used in component, such as
<code>Loop</code>, that render themselves multiple times)</li></ul><h2
id="ComponentCheatSheet-PageLifeCycleMethods">Page Life Cycle
Methods</h2><p>Main article: <a href="component-cheat-sheet.html">Component
Cheat Sheet</a></p><p>Pages have a life cycle and this is represented
by a <em>third</em> set of annotations or method naming conventions. Life
cycle methods may appear on a page or any component of a page.</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Annotation</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Method Name</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Description</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>@PageLoaded</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>pageLoaded()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The page instance has been
loaded but not yet attached for the first time.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>@PageAttached</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>pageAttached()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>The page is being used within a
particular request. This occurs before the a
ctivate event.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@PageReset</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>pageReset()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>See notes below.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>@PageDetached</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>pageDetached()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>End of request
notification.</p></td></tr></tbody></table></div><p>Page life cycle methods may
be any visibility. They must take no parameters and return void.</p><p>Page
life cycle methods are of lower importance starting in Tapestry 5.2, since page
instances are now shared across threads, rather than pooled.</p><p>The
@PageReset life cycle is new in Tapestry 5.2. It will be invoked on a page
render request when linked to from some other page of the application. This is
to allow the page to reset its state, if any, when a user r
eturns to the page from some other part of the application.</p><h2
id="ComponentCheatSheet-ConfiguringAnnotations">Configuring
Annotations</h2><p>The SymbolProvider service has two interfaces :
FactoryDefaults and ApplicationDefaults. Tapestry provides 2 annotations in
order to define which implementation you want to override in your AppModule
: </p><ul><li><p>@FactoryDefaults</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>AppModule with
@FactoryDefaults</b></div><div class="codeContent panelContent pdl">
+<p>For an exhaustive list, see the <a href="annotations.html">annotations
list</a>.</p><h2 id="ComponentCheatSheet-FieldInjectionAnnotations">Field
Injection Annotations</h2><p>Main articles: <a
href="component-classes.html">Component Classes</a>, <a
href="injection.html">Injection</a>, <a
href="annotations.html">Annotations</a></p><h3
id="ComponentCheatSheet-@Inject">@Inject</h3><p class="confluence-link">@Inject
is the Swiss Army knife of annotations; it's designed to connect your component
to services, resources, and other objects. See <a
href="injection.html">Injection</a>.</p><h4
id="ComponentCheatSheet-ServiceInjection">Service Injection</h4><p>In most
cases, the injected value is a service; the service is located by type. If
there are ambiguities, caused by multiple services implementing the same
interface, you'll see injection exceptions. You can resolve those exceptions by
adding marker annotations to select a specific service, or by adding @Service
to specify the
specific service ID you want.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Use of @Service is discouraged. If
marker annotations are available, that is preferred.</p></div></div><h3
id="ComponentCheatSheet-@InjectComponent">@InjectComponent</h3><p>Injects a
component from this component's template into this component's class. Injecting
a component is based on the component's ID, which should match the field name.
However, the value attribute of the @InjectComponent annotation can be
specified as well, this takes precedence over the field name.</p><p>It is
common to inject a component in order to obtain its client-side ID (used when
generating client-side JavaScript).</p><h3
id="ComponentCheatSheet-@InjectContainer">@InjectContainer</h3><p>Injects the
container of a component or, when used in a mixin,
injects the component the mixin is attached to.</p><h3
id="ComponentCheatSheet-@InjectPage">@InjectPage</h3><p>Injects a page of the
application. Normally, the page to inject is identified based on the field
type. The value attribute can be specified, in which case the page to be
injected is identified by name.</p><h3
id="ComponentCheatSheet-@Environmental">@Environmental</h3><p>Injects an <a
href="environmental-services.html">environmental object</a>; such objects are
request scoped but may be overridden at any time using the methods of the
Environment service. Environmental objects are used to allow outer components
to communicate with components they enclose.</p><p>Most often, @Environmental
is used with type JavaScriptSupport, which is used to add JavaScript code and
libraries to the rendered page.</p><h2
id="ComponentCheatSheet-FieldBehaviorAnnotations">Field Behavior
Annotations</h2><p>Main articles: <a href="component-classes.html">Component
Classes</a>, <a href="annotatio
ns.html">Annotations</a></p><h3
id="ComponentCheatSheet-@PageActivationContext">@PageActivationContext</h3><p>This
annotation is allowed on a <em>single</em> field; the value of the field will
be included in URLs for the page as the page's activation context. This is an
alternative to implementing event handler methods<br clear="none"> for the
activate and passivate events directly.</p><h3
id="ComponentCheatSheet-@Parameter">@Parameter</h3><p>Marks the field as a
component parameter. Attributes of the annotation allow the parameter to be
marked as required or optional. If the parameter value will typically be a
literal string (for example, the title parameter to a Layout component), you
should add <code>defaultPrefix=BindingConstants.LITERAL</code> to the
annotation so that users of the component won't have to use the "literal:"
binding prefix with the parameter. See <a
href="component-parameters.html">Component Parameters</a>.</p><h3
id="ComponentCheatSheet-@Persist">@Persist</h3>
<p>Marks the field as a persistent value, one that maintains its value between
requests. The default <em>strategy</em> is to simply store the value in the
session (which is created as needed). Other strategies can be specified by name
as the value attribute. See <a href="persistent-page-data.html">Persistent
Page Data</a>.</p><h3
id="ComponentCheatSheet-@Property">@Property</h3><p>Directs Tapestry to
automatically generate a getter and a setter for the field, converting it to a
JavaBeans property than can be referenced from the template.</p><h3
id="ComponentCheatSheet-@SessionState">@SessionState</h3><p>Marks the field as
a Session State Object (SSO). SSOs store global data, and can be injected into
any page or component. The SSOs are stored in the session, using a key based on
the Java type. SSOs are usually created on demand, but the <code>create</code>
attribute can turn this off. See <a
href="component-cheat-sheet.html">Component Cheat Sheet</a></p><h3
id="ComponentCheatSheet-
@SessionAttribute">@SessionAttribute</h3><p>In Tapestry 5.2 and later, marks
the field as a Session Attribute. Like Session State Objects (SSO), a Session
Attribute is stored in the session, however Session Attributes are stored by
using a name you choose rather than based on the Java type. See <a
href="session-storage.html">Session Storage</a>.</p><h3
id="ComponentCheatSheet-@ActivationRequestParameter">@ActivationRequestParameter</h3><p>Fields
with this annotation will be encoded into URLs as query parameters, in much
the same way as data is encoded into the URL path. The query parameter name
matches the field name, unless the value attribute is specified.</p><h2
id="ComponentCheatSheet-MethodAnnotations">Method Annotations</h2><p>Main
articles: <a href="component-classes.html">Component Classes</a>, <a
href="annotations.html">Annotations</a></p><h3
id="ComponentCheatSheet-@OnEvent">@OnEvent</h3><p>Marks a method as an event
handler method. Such methods may have any visibility,
and typically use package private visibility (that is, no visibility keyword
at all). By default, the method will handle the action event from any
component; the value attribute controls the matched event, and the component
annotation is used to limit the event source.</p><p>An event handler method may
take parameters, corresponding the event context associated with the event,
such as the page activation context for the activate event. The method will not
be invoked if it defines more parameters than there are values in the
context.</p><p>The @RequestParameter annotation can be used on parameters, in
which case the parameters value comes from a request query parameter, and not
from the event context.</p><p>Events fired on a component bubble up the
component's container. Return a non-null value to cancel event bubbling. What
values may be returned from an event handler method is dependent on the type of
event.</p><p>You may also return true to indicate that the event is handled and
bubbling should cancel (even for events that do not permit a return
value).</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>An alternative to @OnEvent is the
naming convention <code>on</code><em>EventName</em> or
<code>on</code><em>EventName</em><code>From</code><em>ComponentId</em>.</p></div></div><h3
id="ComponentCheatSheet-@Log">@Log</h3><p>Marks the method to be logged for
debugging purposes: method entry (with parameters) and exit (with return value)
will be logged at debug level, as will any thrown exception. This is primarily
for debugging purposes. The Logger name will match the component classes' fully
qualified class name.</p><h3
id="ComponentCheatSheet-@CommitAfter">@CommitAfter</h3><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>The support for this annotation
comes from the <a href="hibernate.html">tapestry-hibernate</a> module or <a
href="integrating-with-jpa.html">tapestry-jpa</a> module.</p></div></div><h3
id="ComponentCheatSheet-@Cached">@Cached</h3><p>Used on methods that perform
expensive operations, such as database queries. The first time such a method is
invoked, the return value is cached. Future invocations of the same method
return the cached value.</p><p>The result cache is per-request and is discarded
at the end of the request.</p><p>@Cached only works on methods that take no
parameters.</p><h2 id="ComponentCheatSheet-ParameterAnnotations">Parameter
Annotations</h2><p>Main article: <a href="component-parameters.html">Component
Parameters</a></p><h3
id="ComponentCheatSheet-@RequestParameter">@RequestParameter</h3><p>Used with
event handler methods to get the value for the paramet
er from a request query parameter.</p><h2
id="ComponentCheatSheet-TypeAnnotations">Type Annotations</h2><h3
id="ComponentCheatSheet-@Events">@Events</h3><p>Lists the names of events that
may be fired from within this component; used for documentation purposes
only.</p><h3 id="ComponentCheatSheet-@Import">@Import</h3><p>Allows JavaScript
libraries and CSS stylesheet files to be included in the rendered page. Each
such file is added to the page only once, in the order in which the page
renders.</p><p>It is allowed to use symbol expansions (with the
<code>${...</code>} syntax) inside a library or stylesheet path.</p><p>@Import
may also be applied to individual methods, in which case the import operation
only occurs when the method is invoked.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>When specifying a
file to import, you'll often use the prefix <code>context:</code> to indicate
that the file is stored in the web application context, and not on the
classpath. Relative paths will be on the classpath, relative to the Java
class.</p></div></div><h3
id="ComponentCheatSheet-@SupportsInformalParameters">@SupportsInformalParameters</h3><p>Marks
the component as allowing informal parameters (extra attributes in the
template that do not match formally declared parameters). Normally, informal
parameters are simply discarded.</p><p>The method
ComponentResources.renderInformalParameters() can be used to include the
informal parameters within the element rendered by your component.</p><h3
id="ComponentCheatSheet-@Secure">@Secure</h3><p>Main Article: <a
href="security.html">Security</a></p><p>Marks the page as accessible only via
secure (HTTPs). Any attempt to access the page via standard HTTP will be
redirected to the HTTPs version.</p><p>By default, the @Secure annotation is
ignored in devel
opment mode and only active in production mode.</p><h2
id="ComponentCheatSheet-RenderPhaseMethods">Render Phase Methods</h2><p>Main
article: <a href="component-rendering.html">Component
Rendering</a></p><p>Render phase methods are close cousins to event handler
methods; they are how Tapestry integrates your code into the overall rendering
of the page. For each render phase, there's an annotation and corresponding
naming convention to define a render phase method:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Annotation</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>Method Name</p></th><th colspan="1"
rowspan="1" class="confluenceTh"><p>General Use</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>@SetupRender</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Initializes the component
before ren
dering</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@BeginRender</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>beginRender()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Renders the element and primary attributes of the
component</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@AfterRender</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>afterRender()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Closes the element started in
beginRender()</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@CleanupRender</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>cleanupRender()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Performs cleanup after all rendering of the component
finishes</p></td></tr></tbody></table></div><p>Render phase methods either take
no parameters, or take a single parameter of type MarkupWriter.</p><p>Render
phase methods may retur
n <code>void</code>, a <code>boolean</code>, or a <em>renderable
object</em>.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Generally, a <code>renderable
object</code> is a <a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/Block.html";>Block</a>
or a component. The object is pushed onto the stack of rendering operations,
temporarily replacing the current component as the object to be
rendered.</p></div></div><p>Returning true is the same as returning void; it
means that the component should follow the typical
flow:</p><ul><li>@SetupRender</li><li>@BeginRender</li><li>Render the
component's template, if any</li><li>Render the component's
body</li><li>@AfterRender</li><li>@CleanupRender</li></ul><p>If a component has
a template, the component's body will only rende
r if the template contains a <t:body> element. If a component has no
template, then it will always render its body (between @BeginRender and
@AfterRender).</p><p>A render phase method may also return false, in which case
the flow continues to an alternate render phase, as per the chart in the <a
href="component-cheat-sheet.html">Component Cheat Sheet</a> reference
page.</p><p>The most common cases:</p><ul><li>return <code>false</code> from
@BeginRender to skip the rendering of the component's template and/or body, and
continue with @AfterRender</li><li>return <code>false</code> from @AfterRender
to return to @BeginRender (this is used in component, such as
<code>Loop</code>, that render themselves multiple times)</li></ul><h2
id="ComponentCheatSheet-PageLifeCycleMethods">Page Life Cycle
Methods</h2><p>Main article: <a href="page-life-cycle.html">Page Life
Cycle</a></p><p>Pages have a life cycle and this is represented by a
<em>third</em> set of annotations or method naming c
onventions. Life cycle methods may appear on a page or any component of a
page.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th
colspan="1" rowspan="1" class="confluenceTh"><p>Annotation</p></th><th
colspan="1" rowspan="1" class="confluenceTh"><p>Method Name</p></th><th
colspan="1" rowspan="1"
class="confluenceTh"><p>Description</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>@PageLoaded</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>pageLoaded()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>The page instance has been loaded but not
yet attached for the first time.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>@PageAttached</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>pageAttached()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The page is being used within a particular request.
This occurs before the activate event.</p></td></tr><tr><td colspan="1"
rowspan="1
" class="confluenceTd"><p>@PageReset</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>pageReset()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>See notes below.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>@PageDetached</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>pageDetached()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>End of request
notification.</p></td></tr></tbody></table></div><p>Page life cycle methods may
be any visibility. They must take no parameters and return void.</p><p>Page
life cycle methods are of lower importance starting in Tapestry 5.2, since page
instances are now shared across threads, rather than pooled.</p><p>The
@PageReset life cycle is new in Tapestry 5.2. It will be invoked on a page
render request when linked to from some other page of the application. This is
to allow the page to reset its state, if any, when a user returns to the page
from some other part of the application
.</p><h2 id="ComponentCheatSheet-ConfiguringAnnotations">Configuring
Annotations</h2><p>The SymbolProvider service has two interfaces :
FactoryDefaults and ApplicationDefaults. Tapestry provides 2 annotations in
order to define which implementation you want to override in your AppModule
: </p><ul><li><p>@FactoryDefaults</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>AppModule.java (partial) with
@FactoryDefaults</b></div><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Contribute(SymbolProvider.class)
@FactoryDefaults
public void setParam(MappedConfiguration< String, String> configuration){
configuration.add(SymbolConstants.PRODUCTION_MODE, "false");
}</pre>
-</div></div></li><li><p>@ApplicationDefaults</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>AppModule with
@ApplicationDefaults</b></div><div class="codeContent panelContent pdl">
+</div></div></li><li><p>@ApplicationDefaults</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>AppModule.java (partial) with
@ApplicationDefaults</b></div><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Contribute(SymbolProvider.class)
@ApplicationDefaults
public void setParam(MappedConfiguration< String, String> configuration){
