Author: buildbot
Date: Sun Feb 18 15:19:48 2018
New Revision: 1025555
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-events.html
websites/production/tapestry/content/component-rendering.html
websites/production/tapestry/content/configuration.html
websites/production/tapestry/content/dom.html
websites/production/tapestry/content/url-rewriting.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-events.html
==============================================================================
--- websites/production/tapestry/content/component-events.html (original)
+++ websites/production/tapestry/content/component-events.html Sun Feb 18
15:19:48 2018
@@ -154,7 +154,7 @@
</div>
</t:loop>
</pre>
-</div></div><p>Notice that Review.tml contains an ActionLink component in a
loop. For each rendering within the loop, the ActionLink component creates a
component event request URL, with the event type set to "action". In this case,
each URL might look like:</p><p><code><span
class="external-link">    <a class="external-link"
href="http://localhost:8080/review.edit/3";
rel="nofollow">http://localhost:8080/review.edit/3</a></span></code></p><p>This
URL identifies the <strong>page</strong> that contains the component
("review"), the <strong>Component id</strong> of the component within the
page ("edit"), and the <strong>context</strong> value ("3", the "id" property
of the document). <em>Additional context values, if any, are appended to the
path.</em> (The URL may also contain the <strong>event name</strong>, unless,
as here, it is "action".)</p><p>There's no direct mapping from URL to a piece
of code. Instead, when the user clicks on the link, the ActionLink comp
onent triggers events. And then Tapestry ensures that the correct bits of code
(your event handler method, see below) get invoked for those events.</p><p>This
demonstrates a critical difference between Tapestry and a more traditional,
action oriented framework. The URL doesn't say what happens when the link is
clicked, it identifies <em>which component is responsible</em> when the link is
clicked.</p><p>Often, a navigation request (originating with the user) will
spawn a number of flow-of-control requests. For example, a form component may
trigger an action event, which will then trigger notification events to
announce when the form submission is about to be processed, and whether it was
successful or not, and those event could be further handled by the page
component.</p><h1 id="ComponentEvents-EventHandlerMethods">Event Handler
Methods</h1><p>When a component event occurs, Tapestry invokes any event
handler methods that you have identified for that event. You can identify your
eve
nt handler methods via a naming convention (see Method Naming Convention
below), or via the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/OnEvent.html";>OnEvent</a>
annotation.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>Notice that Review.tml contains an ActionLink component in a
loop. For each rendering within the loop, the ActionLink component creates a
component event request URL, with the event type set to "action". In this case,
each URL might look like:</p><p><code><span
class="external-link">    <span
class="nolink">http://localhost:8080/review.edit/3</span></span></code></p><p>This
URL identifies the <strong>page</strong> that contains the component
("review"), the <strong>Component id</strong> of the component within the
page ("edit"), and the <strong>context</strong> value ("3", the "id" property
of the document). <em>Additional context values, if any, are appended to the
path.</em> (The URL may also contain the <strong>event name</strong>, unless,
as here, it is "action".)</p><p>There's no direct mapping from URL to a piece
of code. Instead, when the user clicks on the link, the ActionLink component
triggers events. And then Tapestry ensures that the co
rrect bits of code (your event handler method, see below) get invoked for
those events.</p><p>This demonstrates a critical difference between Tapestry
and a more traditional, action oriented framework. The URL doesn't say what
happens when the link is clicked, it identifies <em>which component is
responsible</em> when the link is clicked.</p><p>Often, a navigation request
(originating with the user) will spawn a number of flow-of-control requests.
For example, a form component may trigger an action event, which will then
trigger notification events to announce when the form submission is about to be
processed, and whether it was successful or not, and those event could be
further handled by the page component.</p><h1
id="ComponentEvents-EventHandlerMethods">Event Handler Methods</h1><p>When a
component event occurs, Tapestry invokes any event handler methods that you
have identified for that event. You can identify your event handler methods via
a naming convention (see Method Namin
g Convention below), or via the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/OnEvent.html";>OnEvent</a>
annotation.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@OnEvent(component="edit")
void editDocument(int docId)
{
@@ -169,7 +169,6 @@ void editDocument(int docId)
<div class="aui-message aui-message-info">
Added in 5.3
Starting in release 5.3, Tapestry will throw an exception if the component
identified for the event handler method doesn't exist in the containing
component's template. This helps prevent typos.
-
</div><p>In the above example, the editDocument() method will be invoked when
any event occurs in in the "edit" component (and has at least one context
value).</p><p>For some components, more than one type of event can occur, in
which case you will want to be more specific:</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;">@OnEvent(value="action", component="edit")
void editDocument(int docId)
@@ -189,7 +188,7 @@ void editDocument(int docId)
// do something with the document here
}
</pre>
-</div></div><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>Many people prefer the naming
convention approach, reserving the annotation just for situations that don't
otherwise fit.</p></div></div><h2
id="ComponentEvents-MethodReturnValues">Method Return Values</h2><p>Main
Article: <a href="component-events.html">Component Events</a></p><p>For page
navigation events (originating in components such as EventLink, ActionLink and
Form), the value returned from an event handler method determines how Tapestry
will render a response.</p><ul><li><strong>Null</strong>: For no value, or
null, the current page (the page containing the component) will render the
response.</li><li><strong>Page</strong>: For the name of a page, or a page
class or page instance, a render request URL will be constructed and sent to the
client as a redirect to that page.</li><li><strong>URL</strong>: For a <a
class="external-link" href="http://java.net"; rel="nofollow">java.net</a>.URL, a
redirect will be sent to the client. (In Tapestry 5.3.x and earlier, this only
works for non-Ajax requests.)</li><li><strong>Zone body</strong>: In the case
of an Ajax request to update a zone, the component event handler will return
the new zone body, typically via an injected component or
block.</li><li><strong>HttpError</strong>: For an <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpError.html";>HttpError</a>,
an error response is sent to the client.</li><li><strong>Link</strong>: For a
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html";>Link</a>,
a redirect is sent to the client.</li><li><strong>Stream</strong>: For a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5
/StreamResponse.html">StreamResponse</a>, a stream of data is sent to the
client</li><li><strong>boolean:</strong> <em>true</em> prevents the event from
bubbling up further; <em>false</em> lets it bubble up. See Event Bubbling,
below.</li></ul><p>See <a href="component-events.html">Component Events</a>
for more details.</p><h2 id="ComponentEvents-MultipleMethodMatches">Multiple
Method Matches</h2><p>In some cases, there may be multiple event handler
methods matching a single event. In that case, Tapestry invokes them in the
following order:</p><ul><li>Base class methods before sub-class
methods.</li><li>Matching methods within a class in alphabetical
order.</li><li>For a single method name with multiple overrides, by number of
parameters, descending.</li></ul><p>Of course, ordinarily would you
<em>not</em> want to create more than one method to handle an event.</p><p>When
a sub-class overrides an event handler method of a base class, the event
handler method is only invoked once, a
long with any other base class methods. The subclass can change the
<em>implementation</em> of the base class method via an override, but can't
change the <em>timing</em> of when that method is invoked. See <a
class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-51";>issue TAP5-51</a>.</p><h2
id="ComponentEvents-EventContext">Event Context</h2><p>The context values (the
context parameter to the EventLink or ActionLink component) can be any object.
However, only a simple conversion to string occurs. (This is in contrast to
Tapestry 4, which had an elaborate type mechanism with the odd name
"DataSqueezer".)</p><p>Again, whatever your value is (string, number, date), it
is converted into a plain string. This results in a more readable URL.</p><p>If
you have multiple context values (by binding a list or array of objects to the
<em>context</em> parameter of the EventLink or ActionLink), then each one, in
order, will be added to the URL.</p><p>When an event handler metho
d is invoked, the strings are converted back into values, or even objects. A
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValueEncoder.html";>ValueEncoder</a>
is used to convert between client-side strings and server-side objects. The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ValueEncoderSource.html";>ValueEncoderSource</a>
service provides the necessary value encoders.</p><p>As shown in the example
above, most of the parameters passed to the event handler method are derived
from the values provided in the event context. Each successive method parameter
matches against a value provided in the event context (the context parameter of
the ActionLink component; though many components have a similar context
parameter).</p><p>In many cases it is helpful to have direct access to the
context (for example, to adapt to cases where there are a variable number of
context values). The
context values may be passed to an event handler method as parameter of the
following types:</p><ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/EventContext.html";>EventContext</a></li><li>Object[]</li><li>List<Object></li></ul><p>The
latter two should be avoided, they may be removed in a future release. In all
of these cases, the context parameter acts as a freebie; it doesn't match
against a context value as it represents <em>all</em> context values.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div></div><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>Many people prefer the naming
convention approach, reserving the annotation just for situations that don't
otherwise fit.</p></div></div><h2
id="ComponentEvents-MethodReturnValues">Method Return Values</h2><p>Main
Article: <a href="page-navigation.html">Page Navigation</a></p><p>For page
navigation events (originating in components such as EventLink, ActionLink and
Form), the value returned from an event handler method determines how Tapestry
will render a response.</p><ul><li><strong>Null</strong>: For no value, or
null, the current page (the page containing the component) will render the
response.</li><li><strong>Page</strong>: For the name of a page, or a page
class or page instance, a render request URL will be constructed and sent to
the c
lient as a redirect to that page.</li><li><strong>URL</strong>: For a
<code>java.net.URL</code>, a redirect will be sent to the client. (In Tapestry
5.3.x and earlier, this only works for non-Ajax requests.)</li><li><strong>Zone
body</strong>: In the case of an Ajax request to update a zone, the component
event handler will return the new zone body, typically via an injected
component or block.</li><li><strong>HttpError</strong>: For an <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpError.html";>HttpError</a>,
an error response is sent to the client.</li><li><strong>Link</strong>: For a
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html";>Link</a>,
a redirect is sent to the client.</li><li><strong>Stream</strong>: For a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html";>StreamResponse</a>,
a stream of dat
a is sent to the client</li><li><strong>boolean:</strong> <em>true</em>
prevents the event from bubbling up further; <em>false</em> lets it bubble up.
See Event Bubbling, below.</li></ul><p>See <a href="page-navigation.html">Page
Navigation</a> for more details.</p><h2
id="ComponentEvents-MultipleMethodMatches">Multiple Method Matches</h2><p>In
some cases, there may be multiple event handler methods matching a single
event. In that case, Tapestry invokes them in the following
order:</p><ul><li>Base class methods before sub-class methods.</li><li>Matching
methods within a class in alphabetical order.</li><li>For a single method name
with multiple overrides, by number of parameters, descending.</li></ul><p>Of
course, ordinarily would you <em>not</em> want to create more than one method
to handle an event.</p><p>When a sub-class overrides an event handler method of
a base class, the event handler method is only invoked once, along with any
other base class methods. The subclass can ch
ange the <em>implementation</em> of the base class method via an override, but
can't change the <em>timing</em> of when that method is invoked. See <a
class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-51";>issue TAP5-51</a>.</p><h2
id="ComponentEvents-EventContext">Event Context</h2><p>The context values (the
context parameter to the EventLink or ActionLink component) can be any object.
However, only a simple conversion to string occurs. (This is in contrast to
Tapestry 4, which had an elaborate type mechanism with the odd name
"DataSqueezer".)</p><p>Again, whatever your value is (string, number, date), it
is converted into a plain string. This results in a more readable URL.</p><p>If
you have multiple context values (by binding a list or array of objects to the
<em>context</em> parameter of the EventLink or ActionLink), then each one, in
order, will be added to the URL.</p><p>When an event handler method is invoked,
the strings are converted back into values, o
r even objects. A <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ValueEncoder.html";>ValueEncoder</a>
is used to convert between client-side strings and server-side objects. The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ValueEncoderSource.html";>ValueEncoderSource</a>
service provides the necessary value encoders.</p><p>As shown in the example
above, most of the parameters passed to the event handler method are derived
from the values provided in the event context. Each successive method parameter
matches against a value provided in the event context (the context parameter of
the ActionLink component; though many components have a similar context
parameter).</p><p>In many cases it is helpful to have direct access to the
context (for example, to adapt to cases where there are a variable number of
context values). The context values may be passed to an event handler method as
parameter of the following types:</p><ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/EventContext.html";>EventContext</a></li><li>Object[]</li><li>List<Object></li></ul><p>The
latter two should be avoided, they may be removed in a future release. In all
of these cases, the EventContext parameter acts as a freebie; it doesn't match
against a context value as it represents <em>all</em> context values.</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;">Object onActionFromEdit(EventContext context)
{
if (context.getCount() > 0) {
@@ -200,7 +199,7 @@ void editDocument(int docId)
return null;
}
}</pre>
-</div></div><h2 id="ComponentEvents-AccessingRequestQueryParameters">Accessing
Request Query Parameters</h2><p>A parameter may be annotated with the
@RequestParameter annotation; this allows query parameters
(?name1=value1&name2=value2, etc) to be extracted from the request,
converted to the correct type, and passed to the method. Again, this doesn't
count against the event context values.</p><p>See the example in the <a
href="component-events.html">Component Events</a>.</p><h2
id="ComponentEvents-MethodMatching">Method Matching</h2><p>An event handler
method will only be invoked <em>if the context contains at least as many values
as the method has parameters</em>. Methods with too many parameters will be
silently skipped.</p><p>Tapestry will silently skip over a method if there are
insufficient values in the context to satisfy the number of parameters
requested.</p><p>EventContext parameters, and parameters annotated with
@RequestParameter, do not count against this limit.</p>
<h2 id="ComponentEvents-MethodOrdering">Method Ordering</h2><p>When multiple
methods match within the same class, Tapestry will invoke them in ascending
alphabetical order. When there are multiple overrides of the same method name,
Tapestry invokes them in descending order by number of parameters. In general,
these situations don't happen ... in most cases, only a single method is
required to handle a specific event form a specific component.</p><p>An event
handler method may return the value <code>true</code> to indicate that the
event has been handled; this immediately stops the search for additional
methods in the same class (or in base classes) or in containing
components.</p><h1 id="ComponentEvents-EventBubbling">Event Bubbling</h1><p>The
event will bubble up the component hierarchy, first to the containing
component, then <em>that</em> component's containing component or page, and so
on, until it is <em>aborted</em> by an event handler method returning
<em>true</em> or a non-n
ull value.</p><p>Returning a boolean value from an event handler method is
special. Returning <em>true</em> will abort the event with no result; use this
when the event is fully handled without a return value and no further event
handlers (in the same component, or in containing components) should be
invoked.</p><p>Returning <em>false</em> is the same as returning null; event
processing will continue to look for more event handlers, in the same component
or its parent.</p><p>When an event bubbles up from a component to its
container, the origin of the event is changed to be the component. For example,
a Form component inside a BeanEditForm component may trigger a success event.
The page containing the BeanEditForm may listen for that event, but it will be
from the BeanEditForm component (which makes sense, because the id of the Form
inside the BeanEditForm is part of the BeanEditForm's implementation, not its
public interface).</p><p>If you want to handle events that have bubbled up
from nested component, you'll soon find that you don't have easy access to
the component ID of the firing component. In practical terms this means that
you'll want to trigger custom events for the events triggered by those nested
components (see Triggering Events, below), and use that custom event name in
your event handler method.</p><h1
id="ComponentEvents-EventMethodExceptions">Event Method Exceptions</h1><p>Event
methods are allowed to throw any exception (not just runtime exceptions). If an
event method does throw an exception, Tapestry will catch the thrown exception
and ultimately display the exception report page.</p><p>In other words, there's
no need to do this:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><h2 id="ComponentEvents-AccessingRequestQueryParameters">Accessing
Request Query Parameters</h2><p>A parameter may be annotated with the
@RequestParameter annotation; this allows query parameters
(?name1=value1&name2=value2, etc) to be extracted from the request,
converted to the correct type, and passed to the method. Again, this doesn't
count against the event context values.</p><p>See the example in the <a
href="link-components-faq.html">Link Components FAQ</a>.</p><h2
id="ComponentEvents-MethodMatching">Method Matching</h2><p>An event handler
method will only be invoked <em>if the context contains at least as many values
as the method has parameters</em>. Methods with too many parameters will be
silently skipped.</p><p>Tapestry will silently skip over a method if there are
insufficient values in the context to satisfy the number of parameters
requested.</p><p>EventContext parameters, and parameters annotated with
@RequestParameter, do not count against this limi
t.</p><h2 id="ComponentEvents-MethodOrdering">Method Ordering</h2><p>When
multiple methods match within the same class, Tapestry will invoke them in
ascending alphabetical order. When there are multiple overrides of the same
method name, Tapestry invokes them in descending order by number of parameters.
In general, these situations don't happen ... in most cases, only a single
method is required to handle a specific event form a specific
component.</p><p>An event handler method may return the value <code>true</code>
to indicate that the event has been handled; this immediately stops the search
for additional methods in the same class (or in base classes) or in containing
components.</p><h1 id="ComponentEvents-EventBubbling">Event Bubbling</h1><p>The
event will bubble up the component hierarchy, first to the containing
component, then <em>that</em> component's containing component or page, and so
on, until it is <em>aborted</em> by an event handler method returning
<em>true</em> or a
non-null value.</p><p>Returning a boolean value from an event handler method
is special. Returning <em>true</em> will abort the event with no result; use
this when the event is fully handled without a return value and no further
event handlers (in the same component, or in containing components) should be
invoked.</p><p>Returning <em>false</em> is the same as returning null; event
processing will continue to look for more event handlers, in the same component
or its parent.</p><p>When an event bubbles up from a component to its
container, the origin of the event is changed to be the component. For example,
a Form component inside a BeanEditForm component may trigger a success event.
The page containing the BeanEditForm may listen for that event, but it will be
from the BeanEditForm component (which makes sense, because the id of the Form
inside the BeanEditForm is part of the BeanEditForm's implementation, not its
public interface).</p><p>If you want to handle events that have bubb
led up from nested component, you'll soon find that you don't have easy access
to the component ID of the firing component. In practical terms this means that
you'll want to trigger custom events for the events triggered by those nested
components (see Triggering Events, below), and use that custom event name in
your event handler method.</p><h1
id="ComponentEvents-EventMethodExceptions">Event Method Exceptions</h1><p>Event
methods are allowed to throw any exception (not just runtime exceptions). If an
event method does throw an exception, Tapestry will catch the thrown exception
and ultimately display the exception report page.</p><p>In other words, there's
no need to do this:</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;"> void onActionFromRunQuery()
{
try
@@ -229,9 +228,9 @@ void editDocument(int docId)
return this;
}
</pre>
-</div></div><p>The return value of the exception event handler
<em>replaces</em> the return value of original event handler method. For the
typical case (an exception thrown by an "activate" or "action" event), this
will be a <a href="component-events.html">navigational response</a> such as a
page instance or page name.</p><p>This can be handy for handling cases where
the data in the URL is incorrectly formatted.</p><p>In the above example, the
navigational response is the page itself.</p><p>If there is no exception event
handler, or the exception event handler returns null (or is void), then the
exception will be passed to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestExceptionHandler.html";>RequestExceptionHandler</a>
service, which (in the default configuration) will render the exception
page.</p><h1 id="ComponentEvents-TriggeringEvents">Triggering
Events</h1><p></p><div class="navmenu" style="float:right; back
ground:#eee; margin:3px; padding:0 1em">
+</div></div><p>The return value of the exception event handler
<em>replaces</em> the return value of original event handler method. For the
typical case (an exception thrown by an "activate" or "action" event), this
will be a <a href="page-navigation.html">navigational response</a> such as a
page instance or page name.</p><p>This can be handy for handling cases where
the data in the URL is incorrectly formatted.</p><p>In the above example, the
navigational response is the page itself.</p><p>If there is no exception event
handler, or the exception event handler returns null (or is void), then the
exception will be passed to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestExceptionHandler.html";>RequestExceptionHandler</a>
service, which (in the default configuration) will render the exception
page.</p><h1 id="ComponentEvents-TriggeringEvents">Triggering
Events</h1><p></p><div class="navmenu" style="float:right; backg
round:#eee; margin:3px; padding:0 1em">
<p> <strong>JumpStart Demo:</strong><br clear="none">
- <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/together/ajaxcomponentscrud/persons";
rel="nofollow">AJAX Components CRUD</a></p></div>If you want your own
component to trigger events, just call the <a rel="nofollow">triggerEvent</a>
method of <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
from within the component class.<p>For example, the following triggers an
"updateAll" event. A containing component can then respond to it, if desired,
with an "onUpdateAll()" method in its own component class.</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Your component class
(partial)</b></div><div class="codeContent panelContent pdl">
+ <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/together/ajaxcomponentscrud/persons";
rel="nofollow">AJAX Components CRUD</a></p></div>If you want your own
component to trigger events, just call the <code>triggerEvent</code> method of
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>
from within your component class.<p>For example, the following triggers an
"updateAll" event. A containing component can then respond to it, if desired,
with an "onUpdateAll()" method in its own component class.</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Your component class
(partial)</b></div><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@Inject
ComponentResources componentResources;
 ...
Modified: websites/production/tapestry/content/component-rendering.html
==============================================================================
--- websites/production/tapestry/content/component-rendering.html (original)
+++ websites/production/tapestry/content/component-rendering.html Sun Feb 18
15:19:48 2018
@@ -155,7 +155,7 @@
</div>
-<h2 id="ComponentRendering-RenderingPhases">Rendering Phases</h2><p>The
rendering of each component is divided into a number of phases, illustrated
below.</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2";
data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2";></span><br
clear="none"> Each of the orange phases (SetupRender, BeginRender,
BeforeRenderBody, etc.) corresponds to an annotation you may place on one or
more methods of your class. The annotation directs Tapestry to invoke your
method as part of that phase.</p><p>Methods marked with these annotations are
called <strong>render phase methods</strong>.</p><p>Your methods may be void,
or r
eturn a boolean value. Returning a value can force phases to be skipped, or
even be re-visited. In the diagram, solid lines show the normal processing
path. Dashed lines are alternate flows that are triggered when your render
phase methods return false instead of true (or void).</p><p>Render phase
methods may take no parameters, or may take a parameter of type <a
href="component-rendering.html">MarkupWriter</a>. The methods can have any
visibility you like ... typically, package private is used, as this visibility
makes it possible to unit test your code (from within the same Java package)
without making the methods part of the component's <em>public</em>
API.</p><p>All Render phase methods are <em>optional</em>; a default behavior
is associated with each phase.</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>When Called</p></th></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><strong><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html";>@SetupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When initial setup actions, if
any, are needed</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender";>@BeginRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When Tapestry is ready for the
component's start tag, if any, to be rendered</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link" href
="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate";>@BeforeRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>beforeRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before Tapestry renders the component's
template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody";>@BeforeRenderBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderBody()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the
body of the component, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody";>@AfterRenderBody</a></p></td><td
colspan="1" rowspan="1" class=
"confluenceTd"><p>afterRenderBody()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After Tapestry renders the body of the component, if
any, but before the rest of the component's template is
rendered</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderTemplate";>@AfterRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>afterRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>After Tapestry finishes rendering the
component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender";>@AfterRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>afterRender()</p></td><td
colspan="1" rowspan="1" class="confluence
Td"><p>After Tapestry has finished rendering both the template and body of the
component</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender";>@CleanupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>cleanupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When final cleanup actions, if
any, are needed</p></td></tr></tbody></table></div><p>The large number of
phases reflects the need for precise control of components from <a
href="component-rendering.html">component mixins</a>. Several of the phases
exist almost exclusively for mixins.</p><p>Generally, your code will use the
SetupRender, BeginRender, AfterRender and CleanupRender phases ... often just
one or two of those.</p><h2 id="ComponentRendering-AnExample">An
Example</h2><p>Here's the source for a looping component that counts up or
down between two values, renders its body a number of times, and stores the
current index value in a parameter:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<h2 id="ComponentRendering-RenderingPhases">Rendering Phases</h2><p>The
rendering of each component is divided into a number of phases, illustrated
below.</p><p><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2";
data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2";></span><br
clear="none"> Each of the orange phases (SetupRender, BeginRender,
BeforeRenderBody, etc.) corresponds to an annotation you may place on one or
more methods of your class. The annotation directs Tapestry to invoke your
method as part of that phase.</p><p>Methods marked with these annotations are
called <strong>render phase methods</strong>.</p><p>Your methods may be void,
or r
eturn a boolean value. Returning a value can force phases to be skipped, or
even be re-visited. In the diagram, solid lines show the normal processing
path. Dashed lines are alternate flows that are triggered when your render
phase methods return false instead of true (or void).</p><p>Render phase
methods may take no parameters, or may take a parameter of type <a
href="dom.html">MarkupWriter</a>. The methods can have any visibility you like
... typically, package private is used, as this visibility makes it possible to
unit test your code (from within the same Java package) without making the
methods part of the component's <em>public</em> API.</p><p>All Render phase
methods are <em>optional</em>; a default behavior is associated with each
phase.</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>When Called</p></th></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html";>@SetupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When initial setup actions, if
any, are needed</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender";>@BeginRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When Tapestry is ready for the
component's start tag, if any, to be rendered</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestr
y.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate">@BeforeRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>beforeRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Before Tapestry renders the component's
template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody";>@BeforeRenderBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderBody()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the
body of the component, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody";>@AfterRenderBody</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><
p>afterRenderBody()</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>After Tapestry renders the body of the component, if
any, but before the rest of the component's template is
rendered</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderTemplate";>@AfterRenderTemplate</a></p></td><td
colspan="1" rowspan="1"
class="confluenceTd"><p>afterRenderTemplate()</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>After Tapestry finishes rendering the
component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender";>@AfterRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>afterRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>After Tap
estry has finished rendering both the template and body of the
component</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><strong><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender";>@CleanupRender</a></strong></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>cleanupRender()</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>When final cleanup actions, if
any, are needed</p></td></tr></tbody></table></div><p>The large number of
phases reflects the need for precise control of components from <a
href="component-mixins.html">component mixins</a>. Several of the phases exist
almost exclusively for mixins.</p><p>Generally, your code will use the
SetupRender, BeginRender, AfterRender and CleanupRender phases ... often just
one or two of those.</p><h2 id="ComponentRendering-AnExample">An
Example</h2><p>Here's the source for a looping component that counts up or down
between two va
lues, renders its body a number of times, and stores the current index value
in a parameter:</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.app.components;
import org.apache.tapestry5.annotations.Parameter;
@@ -283,7 +283,7 @@ public class Count
}
}
</pre>
-</div></div><h2 id="ComponentRendering-ShortCircuiting">Short
Circuiting</h2><p>If a method returns a true or false value, this will short
circuit processing. Other methods within the phase that would ordinarily be
invoked will not be invoked.</p><p>Most render phase methods should return
void, to avoid unintentionally short circuiting other methods for the same
phase.</p><h2 id="ComponentRendering-MethodConflictsandOrdering">Method
Conflicts and Ordering</h2><p>It is possible to have multiple methods that are
annotated with the same render phase annotation. This may include methods in
the same class, or a mix of method defined in a class and inherited from other
classes.</p><h3 id="ComponentRendering-MixinsBeforeComponent">Mixins Before
Component</h3><p>When a component has <a
href="component-rendering.html">mixins</a>, then the mixins' render phase
methods execute <em>before</em> the component's render phase methods. If a
mixin extends from a base class, the mixin's parent class
methods execute before the mixin subclass' render phase
methods.</p><p>Exception: Mixins whose class is annotated with @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html";>MixinAfter</a>
are ordered <em>after</em> the component, not before.</p><p>The order in which
the mixins of a given class (@MixinAfter or mixins before) execute is
determined by the ordering constraints specified for the mixins. If no
constraints are provided, the order is undefined. See <a
href="component-rendering.html">Component Rendering</a> for more
details.</p><h3 id="ComponentRendering-ParentsbeforeChild">Parents before
Child</h3><p>Ordering is always parent-first. Methods defined in the parent
class are always invoked before methods defined in the child class.</p><p>When
a sub-class overrides an render phase method of a base class, the method is
only invoked once, along with any other base class methods. The subclass can
change the <
em>implementation</em> of the base class method via an override, but can't
change the <em>timing</em> of when that method is invoked. See <a
class="external-link"
href="https://issues.apache.org/jira/browse/TAPESTRY-2311";>TAPESTRY-2311</a>.</p><h3
id="ComponentRendering-ReverseOrderingforAfterXXXandCleanupRender">Reverse
Ordering for AfterXXX and CleanupRender</h3><p>The After_XXX_ phases exists to
balance the Begin_XXX_ and Before_XXX_ phases. Often elements will be started
inside an earlier phase and then the elements will be ended (closed) inside the
corresponding After_XXX_ phase (with the body and template of the component
rendering between).</p><p>In order to ensure that operations occur in the
correct, and natural order, the render phase methods for these two stages are
invoked in <em>reverse order</em>:</p><ul><li>Subclass methods</li><li>Parent
class methods</li><li>Mixin subclass methods</li><li>Mixin parent class
methods</li></ul><h3 id="ComponentRendering-WithinaSingleC
lass">Within a Single Class</h3><p>Currently, rendering methods having the
same annotation within a single class are executed in alphabetical order by
method name. Methods with the same name are ordered by number of parameters.
Even so, annotating multiple methods with the same rendering phase is not a
great idea. Instead, just define one method, and have it call the other methods
in the order you desire.</p><h2
id="ComponentRendering-RenderingComments">Rendering Comments</h2><p>Starting
with version 5.3, Tapestry can optionally emit rendering comments for all
requests; these are comments such as <!--BEGIN Index:loop
(context:Index.tml, line 15)--> that can assist you in debugging markup
output on the client-side. This will significantly increase the size of the
rendered markup, but can be very helpful with complex layouts to determine
which component was responsible for which portion of the rendered
page.</p><p>Rendering comments are only available when not running in <a hre
f="component-rendering.html">production mode</a>.</p><p>To turn on rendering
comments for all requests, set the <a
href="component-rendering.html">tapestry.component-render-tracing-enabled</a>
configuration symbol to "true".</p><p>To turn on rendering comments only for a
particular request, add the query parameter <code>t:component-trace=true</code>
to the URL:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><h2 id="ComponentRendering-ShortCircuiting">Short
Circuiting</h2><p>If a method returns a true or false value, this will short
circuit processing. Other methods within the phase that would ordinarily be
invoked will not be invoked.</p><p>Most render phase methods should return
void, to avoid unintentionally short circuiting other methods for the same
phase.</p><h2 id="ComponentRendering-MethodConflictsandOrdering">Method
Conflicts and Ordering</h2><p>It is possible to have multiple methods that are
annotated with the same render phase annotation. This may include methods in
the same class, or a mix of method defined in a class and inherited from other
classes.</p><h3 id="ComponentRendering-MixinsBeforeComponent">Mixins Before
Component</h3><p>When a component has <a
href="component-mixins.html">mixins</a>, then the mixins' render phase methods
execute <em>before</em> the component's render phase methods. If a mixin
extends from a base class, the mixin's parent class met
hods execute before the mixin subclass' render phase methods.</p><p>Exception:
Mixins whose class is annotated with @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html";>MixinAfter</a>
are ordered <em>after</em> the component, not before.</p><p>The order in which
the mixins of a given class (@MixinAfter or mixins before) execute is
determined by the ordering constraints specified for the mixins. If no
constraints are provided, the order is undefined. See <a
href="component-mixins.html">Component Mixins</a> for more details.</p><h3
id="ComponentRendering-ParentsbeforeChild">Parents before Child</h3><p>Ordering
is always parent-first. Methods defined in the parent class are always invoked
before methods defined in the child class.</p><p>When a sub-class overrides an
render phase method of a base class, the method is only invoked once, along
with any other base class methods. The subclass can change the <em>implem
entation</em> of the base class method via an override, but can't change the
<em>timing</em> of when that method is invoked. See <a class="external-link"
href="https://issues.apache.org/jira/browse/TAPESTRY-2311";>TAPESTRY-2311</a>.</p><h3
id="ComponentRendering-ReverseOrderingforAfterXXXandCleanupRender">Reverse
Ordering for AfterXXX and CleanupRender</h3><p>The After_XXX_ phases exists to
balance the Begin_XXX_ and Before_XXX_ phases. Often elements will be started
inside an earlier phase and then the elements will be ended (closed) inside the
corresponding After_XXX_ phase (with the body and template of the component
rendering between).</p><p>In order to ensure that operations occur in the
correct, and natural order, the render phase methods for these two stages are
invoked in <em>reverse order</em>:</p><ul><li>Subclass methods</li><li>Parent
class methods</li><li>Mixin subclass methods</li><li>Mixin parent class
methods</li></ul><h3 id="ComponentRendering-WithinaSingleClass">Wit
hin a Single Class</h3><p>Currently, rendering methods having the same
annotation within a single class are executed in alphabetical order by method
name. Methods with the same name are ordered by number of parameters. Even so,
annotating multiple methods with the same rendering phase is not a great idea.
Instead, just define one method, and have it call the other methods in the
order you desire.</p><h2 id="ComponentRendering-RenderingComments">Rendering
Comments</h2><p>Starting with version 5.3, Tapestry can optionally emit
rendering comments for all requests; these are comments such as <!--BEGIN
Index:loop (context:Index.tml, line 15)--> that can assist you in debugging
markup output on the client-side. This will significantly increase the size of
the rendered markup, but can be very helpful with complex layouts to determine
which component was responsible for which portion of the rendered
page.</p><p>Rendering comments are only available when not running in <a
href="config
uration.html">production mode</a>.</p><p>To turn on rendering comments for all
requests, set the <a
href="configuration.html">tapestry.component-render-tracing-enabled</a>
configuration symbol to "true".</p><p>To turn on rendering comments only for a
particular request, add the query parameter <code>t:component-trace=true</code>
to the URL:</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;">
http://www.example.com/myapp/mypage?t:component-trace=true
</pre>
</div></div></div>
Modified: websites/production/tapestry/content/configuration.html
==============================================================================
--- websites/production/tapestry/content/configuration.html (original)
+++ websites/production/tapestry/content/configuration.html Sun Feb 18 15:19:48
2018
@@ -147,11 +147,11 @@
<h1 id="Configuration-ConfiguringTapestry">Configuring Tapestry</h1><p>This
page discusses all the ways in which Tapestry can be configured. Tapestry
applications are configured almost entirely using Java, with very little XML at
all.</p><p><strong>Contents</strong></p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1518906043725 {padding: 0px;}
-div.rbtoc1518906043725 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1518906043725 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1518967168018 {padding: 0px;}
+div.rbtoc1518967168018 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1518967168018 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1518906043725">
+/*]]>*/</style></p><div class="toc-macro rbtoc1518967168018">
<ul class="toc-indentation"><li><a
href="#Configuration-XMLconfiguration(web.xml)">XML configuration
(web.xml)</a></li><li><a
href="#Configuration-YourApplication'sModuleClass">Your Application's Module
Class</a></li><li><a
href="#Configuration-ConfigurationSymbolNames">Configuration Symbol
Names</a></li><li><a
href="#Configuration-SettingComponentParameterDefaults">Setting Component
Parameter Defaults</a></li><li><a
href="#Configuration-ConfiguringIgnoredPaths">Configuring Ignored
Paths</a></li><li><a
href="#Configuration-ConfiguringContentTypeMapping">Configuring Content Type
Mapping</a></li><li><a href="#Configuration-SettingExecutionModes">Setting
Execution Modes</a></li></ul>
</div><h2 id="Configuration-XMLconfiguration(web.xml)">XML configuration
(web.xml)</h2><p>Tapestry runs on top of the standard Java Servlet API. To the
servlet container, such as Tomcat, Tapestry appears as a <em>servlet
filter</em>. This gives Tapestry great flexibility in matching URLs without
requiring lots of XML configuration.</p><p>Although most configuration is done
with Java, a small but necessary amount of configuration occurs inside the
servlet deployment descriptor, WEB-INF/web.xml. Most of the configuration is
boilerplate, nearly the same for all applications.</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>web.xml (partial)</b></div><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><!DOCTYPE web-app
@@ -188,7 +188,7 @@ div.rbtoc1518906043725 li {margin-left:
}
}
</pre>
-</div></div><h2 id="Configuration-ConfigurationSymbolNames">Configuration
Symbol Names</h2><p>Main Article: <a
href="symbols.html">Symbols</a></p><p>Many of Tapestry's built-in services
(some of which are not even public) are configured via symbols. These symbols
can be overridden by contributing to the ApplicationDefaults service
configuration, or by placing a <context-param> element into the
application's web.xml, or on the command line by defining JVM System Properties
with the -D command line option.</p><p>These symbols are always defined in
terms of strings, and those strings are coerced to the appropriate type (a
number, a boolean, etc.). Of special note are <em>time intervals</em>, which
are specified in a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html";>particular
format</a>.</p><p>Most of these symbols have a constant defined in the <a
class="external-link" href="http://tapestry.apache.org/cu
rrent/apidocs/org/apache/tapestry5/SymbolConstants.html">SymbolConstants</a>
class, while others are in the <a
href="https://cwiki.apache.org/confluence/tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCSymbols.html";>IOCSymbols</a>
class. Those are noted in <strong>bold</strong> below. Use the symbol name
(tapestry.*) for JVM System Properties with the -D option, and use the constant
(in bold below) from within your Java classes (e.g. AppModule.java).</p><h3
id="Configuration-tapestry.app-catalog">tapestry.app-catalog</h3><p><strong>SymbolConstants.APPLICATION_CATALOG</strong> – The
location of the global application message catalog, the default is
context:WEB-INF/<em>app-name</em>.properties.</p><h3
id="Configuration-tapestry.application-version">tapestry.application-version</h3><p><strong>SymbolConstants.APPLICATION_VERSION</strong> –
The version of the application, which is incorporated into URLs for context
and classpath assets. Assets m
ay be <a href="configuration.html">compressed</a>, and will have far-future
expiration headers; they will be aggressively cached by the client web browser.
You should change the application version on each new deployment of the
application (that is, any time assets in the context change), to force clients
to re-download changed versions of files. If you do not specify an application
version, a <em>random</em> one will be assigned on every deployment (which is
good for development but very bad for production).</p><h3
id="Configuration-tapestry.application-folder">tapestry.application-folder</h3>
+</div></div><h2 id="Configuration-ConfigurationSymbolNames">Configuration
Symbol Names</h2><p>Main Article: <a
href="symbols.html">Symbols</a></p><p>Many of Tapestry's built-in services
(some of which are not even public) are configured via symbols. These symbols
can be overridden by contributing to the ApplicationDefaults service
configuration, or by placing a <context-param> element into the
application's web.xml, or on the command line by defining JVM System Properties
with the -D command line option.</p><p>These symbols are always defined in
terms of strings, and those strings are coerced to the appropriate type (a
number, a boolean, etc.). Of special note are <em>time intervals</em>, which
are specified in a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html";>particular
format</a>.</p><p>Most of these symbols have a constant defined in the <a
class="external-link" href="http://tapestry.apache.org/cu
rrent/apidocs/org/apache/tapestry5/SymbolConstants.html">SymbolConstants</a>
class, while others are in the <a
href="https://cwiki.apache.org/confluence/tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCSymbols.html";>IOCSymbols</a>
class. Those are noted in <strong>bold</strong> below. Use the symbol name
(tapestry.*) for JVM System Properties with the -D option, and use the constant
(in bold below) from within your Java classes (e.g. AppModule.java).</p><h3
id="Configuration-tapestry.app-catalog">tapestry.app-catalog</h3><p><strong>SymbolConstants.APPLICATION_CATALOG</strong> – The
location of the global application message catalog, the default is
context:WEB-INF/<em>app-name</em>.properties.</p><h3
id="Configuration-tapestry.application-version">tapestry.application-version</h3><p><strong>SymbolConstants.APPLICATION_VERSION</strong> –
The version of the application, which is incorporated into URLs for context
and classpath assets. Assets m
ay be <a href="response-compression.html">compressed</a>, and will have
far-future expiration headers; they will be aggressively cached by the client
web browser. You should change the application version on each new deployment
of the application (that is, any time assets in the context change), to force
clients to re-download changed versions of files. If you do not specify an
application version, a <em>random</em> one will be assigned on every deployment
(which is good for development but very bad for production).</p><h3
id="Configuration-tapestry.application-folder">tapestry.application-folder</h3>
Modified: websites/production/tapestry/content/dom.html
==============================================================================
--- websites/production/tapestry/content/dom.html (original)
+++ websites/production/tapestry/content/dom.html Sun Feb 18 15:19:48 2018
@@ -79,7 +79,7 @@
<div id="content">
<div id="ConfluenceContent"><h1
id="DOM-DocumentObjectModel">Document Object Model</h1><p>Tapestry 5 takes a
very different approach to markup generation than most other frameworks.
Components render out a Document Object Model (DOM). This is a tree of nodes
representing elements, attributes and text within a document.</p><p>Once all
rendering is complete, the DOM tree is streamed to the client.</p><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter</a>
interface allows the majority of component code to treat the generation of
output as a stream. In reality, MarkupWriter is more like a cursor into the DOM
tree, and the DOM may ultimately be operated upon in a random access manner
(rather than the serial (or buffered) approach used in Tapestry 4).</p><div
class="navmenu" style="float:right; width:30%; background:white; margin:3px;
padding:3px">
<div class="confluence-information-macro
confluence-information-macro-information"><p class="title">A Note For Tapestry
4 Users</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-<p>In Tapestry 4, markup generation was based on generating a character
stream. At the lowest level, the fact that the output was in a markup format
such as HTML, XHTML or WML was not known. Higher levels, such as the
IMarkupWriter interface (and its implementations) provide the concept of markup
generation: elements, attributes, start tags and end tags. This technique
breaks down when two elements are peers, and not in a parent/child
relationship. For example, the rendering of a FieldLabel component is affected
by its companion TextField component. Handling these cases in Tapestry 4
required a number of kludges and special cases.</p></div></div></div><h1
id="DOM-DOMClasses">DOM Classes</h1><p>The implementation of this DOM is part
of Tapestry, despite the fact that several third-party alternatives exist. This
represents a desire to limit dependencies for the framework, but also the
Tapestry DOM is streamlined for initial creation, and a limited amount of
subsequent modification. Mo
st DOM implementations are more sophisticated than needed for Tapestry, with
greater support for querying (often using XPath) and manipulation.</p><p>Once
the Document object is created, you don't directly create new DOM objects;
instead, each DOM object includes methods that create new sub-objects. This
primarily applies to the Element class, which can be a container of text,
comments and other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html";>Document
Object</a> represents the an entire document, which is to say, an entire
response to be sent to the client.</p><p>Documents will have a single root
element. The newRootElement() method is used to create the root element for the
document.</p><p>The Document class also has methods for setting and getting the
DTD, adding comments and text, and finding an element based on a path of
element names.</p><h2 id="DOM-Element"
>Element</h2><p>An <a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html";>Element
> Object</a> represents an element of the document. Elements may have
>attributes, and they may themselves contain other elements, as well as text
>and comments.</p><p>The Element class has methods for searching, traversing
>and manipulating the DOM after it is built.</p><h1
>id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A
>powerful feature of Tapestry 5 is the ability to manipulate the structure and
>ordering of the DOM after it has been rendered. For example, this can be used
>to alter the output of a component that may otherwise be outside of your
>control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on
>Node (and Element, which is a subclass of Node) allow an existing node to be
>moved relative to an Element. Nodes may be moved before or after the Element,
>or may be moved inside an Element at the top (the firs
t child) or the bottom (the last child).</p><p>Element's
<code>attribute</code> method adds a new attribute name/value pair to the
Element. If an existing attribute with the specified name already exists, then
then the new value is ignored. This has implications when different pieces of
code try to add attributes to an Element ... the first to add an attribute will
"win". Conversely, the <code>forceAttributes</code> method can be used to
update or remove an attribute.</p><p>In addition, the children of an Element
may be removed or a Node (and all of its children) removed
entirely.</p><p>Finally, an Element may "pop": the Element is removed and
replaced with its children.</p><h1
id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter
interface</a> allows the structure of the document to be built while
maintaining a streaming metaphor.</p><h2 id="DOM-element()andend()m
ethods">element() and end() methods</h2><p>Calls to element() create a new
element within the tree, and may provide attributes for the new element as
well. Calls to write(), writeln() and writef() write text nodes within the
current element. <em>Every call to element() should be matched with a call to
end()</em>, which is used to move the current node up one level.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<p>In Tapestry 4, markup generation was based on generating a character
stream. At the lowest level, the fact that the output was in a markup format
such as HTML, XHTML or WML was not known. Higher levels, such as the
IMarkupWriter interface (and its implementations) provide the concept of markup
generation: elements, attributes, start tags and end tags. This technique
breaks down when two elements are peers, and not in a parent/child
relationship. For example, the rendering of a FieldLabel component is affected
by its companion TextField component. Handling these cases in Tapestry 4
required a number of kludges and special cases.</p></div></div></div><h1
id="DOM-DOMClasses">DOM Classes</h1><p>The implementation of this DOM is part
of Tapestry, despite the fact that several third-party alternatives exist. This
represents a desire to limit dependencies for the framework, but also the
Tapestry DOM is streamlined for initial creation, and a limited amount of
subsequent modification. Mo
st DOM implementations are more sophisticated than needed for Tapestry, with
greater support for querying (often using XPath) and manipulation.</p><p>Once
the Document object is created, you don't directly create new DOM objects;
instead, each DOM object includes methods that create new sub-objects. This
primarily applies to the Element class, which can be a container of text,
comments and other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html";>Document</a>
object represents the an entire document, which is to say, an entire response
to be sent to the client.</p><p>Documents will have a single root element. The
newRootElement() method is used to create the root element for the
document.</p><p>The Document class also has methods for setting and getting the
DTD, adding comments and text, and finding an element based on a path of
element names.</p><h2 id="DOM-Element"
>Element</h2><p>An <a class="external-link"
>href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html";>Element</a>
> object represents an element of the document. Elements may have attributes,
>and they may themselves contain other elements, as well as text and
>comments.</p><p>The Element class has methods for searching, traversing and
>manipulating the DOM after it is built.</p><h1
>id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A
>powerful feature of Tapestry 5 is the ability to manipulate the structure and
>ordering of the DOM after it has been rendered. For example, this can be used
>to alter the output of a component that may otherwise be outside of your
>control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on
>Node (and Element, which is a subclass of Node) allow an existing node to be
>moved relative to an Element. Nodes may be moved before or after the Element,
>or may be moved inside an Element at the top (the firs
t child) or the bottom (the last child).</p><p>Element's
<code>attribute</code> method adds a new attribute name/value pair to the
Element. If an existing attribute with the specified name already exists, then
then the new value is ignored. This has implications when different pieces of
code try to add attributes to an Element ... the first to add an attribute will
"win". Conversely, the <code>forceAttributes</code> method can be used to
update or remove an attribute.</p><p>In addition, the children of an Element
may be removed or a Node (and all of its children) removed
entirely.</p><p>Finally, an Element may "pop": the Element is removed and
replaced with its children.</p><h1
id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter
interface</a> allows the structure of the document to be built while
maintaining a streaming metaphor.</p><h2 id="DOM-element()andend()m
ethods">element() and end() methods</h2><p>Calls to element() create a new
element within the tree, and may provide attributes for the new element as
well. Calls to write(), writeln() and writef() write text nodes within the
current element. <em>Every call to element() should be matched with a call to
end()</em>, which is used to move the current node up one level.</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;"> writer.element("img", "src", "icon.png", "width", 20,
"height", 20, alt, "*");
writer.end();
</pre>
Modified: websites/production/tapestry/content/url-rewriting.html
==============================================================================
--- websites/production/tapestry/content/url-rewriting.html (original)
+++ websites/production/tapestry/content/url-rewriting.html Sun Feb 18 15:19:48
2018
@@ -204,7 +204,7 @@
}
</pre>
-</div></div><p>This examples shows the URL rewriting chaining: the first rule
rewrites requests to <code>/struts</code> and rewrites them to
<code>/jsf</code> and leaves requests to other URLs unchanged. The second
rewrites <code>/jsf</code> to <code>/tapestry</code> and the third rewrites
<code>/tapestry</code> to <code>/urlrewritesuccess</code>.</p><p>The result is
that any request to <code>/struts</code> end up being handled by the same class
that handles <code>/urlrewritesuccess</code>, while the browser, the user and
Tapestry still sees <code>/struts</code>.</p><p>Note that this applies to
rewriting links generated by Tapestry too: a <code>PageLink</code> to the
<code>urlrewritesuccess</code> page with an activation context of
<code>login</code> (path <code>/urlrewritesuccess/login</code>) will generate
an <code>a</code> tag pointing to <code><a class="external-link"
href="http://login.domain.com";
rel="nofollow">http://login.domain.com</a></code>.</p><p>The URLRewriteContext (
added in 5.1.0.4) provides additional information for rewriting, particularly
in the context of rewriting generated link urls. In the following example,
we'll reconfigure the url used to render pages. Whereas the previous examples
used separate rules for handling inbound and outbound rewriting, this
demonstration will utilize a single rule for both scenarios. To simplify the
example, we will assume that every page is named "XXXPage" (UserPage,
TransactionPage, IndexPage, etc.). This naming convention also means that we
don't have to worry about tapestry's auto-stripping of "index" from URLs,
because our page would be IndexPage, rather than Index.</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This examples shows the URL rewriting chaining: the first rule
rewrites requests to <code>/struts</code> and rewrites them to
<code>/jsf</code> and leaves requests to other URLs unchanged. The second
rewrites <code>/jsf</code> to <code>/tapestry</code> and the third rewrites
<code>/tapestry</code> to <code>/urlrewritesuccess</code>.</p><p>The result is
that any request to <code>/struts</code> end up being handled by the same class
that handles <code>/urlrewritesuccess</code>, while the browser, the user and
Tapestry still sees <code>/struts</code>.</p><p>Note that this applies to
rewriting links generated by Tapestry too: a <code>PageLink</code> to the
<code>urlrewritesuccess</code> page with an activation context of
<code>login</code> (path <code>/urlrewritesuccess/login</code>) will generate
an <code>a</code> tag pointing to <code><span
class="nolink">http://login.domain.com</span></code>.</p><p>The
URLRewriteContext (added in 5.1.0.4) provides additional informatio
n for rewriting, particularly in the context of rewriting generated link urls.
In the following example, we'll reconfigure the url used to render pages.
Whereas the previous examples used separate rules for handling inbound and
outbound rewriting, this demonstration will utilize a single rule for both
scenarios. To simplify the example, we will assume that every page is named
"XXXPage" (UserPage, TransactionPage, IndexPage, etc.). This naming convention
also means that we don't have to worry about tapestry's auto-stripping of
"index" from URLs, because our page would be IndexPage, rather than
Index.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public static void
contributeURLRewriter(OrderedConfiguration<URLRewriterRule> configuration)
{
URLRewriterRule rule = new URLRewriterRule()
![https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2"](https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2"){kind=link}