You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2018/02/18 15:19:48 UTC
svn commit: r1025555 - in /websites/production/tapestry/content:
cache/main.pageCache component-events.html component-rendering.html
configuration.html dom.html url-rewriting.html
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()