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 2015/07/26 23:19:57 UTC
svn commit: r959684 [1/5] - in /websites/production/tapestry/content: ./
cache/
Author: buildbot
Date: Sun Jul 26 21:19:56 2015
New Revision: 959684
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/assets.html
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-events.html
websites/production/tapestry/content/component-mixins.html
websites/production/tapestry/content/component-parameters.html
websites/production/tapestry/content/component-rendering.html
websites/production/tapestry/content/component-templates.html
websites/production/tapestry/content/content-type-and-markup.html
websites/production/tapestry/content/css.html
websites/production/tapestry/content/development-dashboard.html
websites/production/tapestry/content/environmental-services.html
websites/production/tapestry/content/forms-and-validation.html
websites/production/tapestry/content/https.html
websites/production/tapestry/content/injection.html
websites/production/tapestry/content/integration-testing.html
websites/production/tapestry/content/ioc.html
websites/production/tapestry/content/layout-component.html
websites/production/tapestry/content/localization.html
websites/production/tapestry/content/logging.html
websites/production/tapestry/content/page-life-cycle.html
websites/production/tapestry/content/page-navigation.html
websites/production/tapestry/content/parameter-type-coercion.html
websites/production/tapestry/content/persistent-page-data.html
websites/production/tapestry/content/property-expressions.html
websites/production/tapestry/content/response-compression.html
websites/production/tapestry/content/security.html
websites/production/tapestry/content/session-storage.html
websites/production/tapestry/content/tapestry-ioc-configuration.html
websites/production/tapestry/content/unit-testing-pages-or-components.html
Modified: websites/production/tapestry/content/assets.html
==============================================================================
--- websites/production/tapestry/content/assets.html (original)
+++ websites/production/tapestry/content/assets.html Sun Jul 26 21:19:56 2015
@@ -32,7 +32,6 @@
<script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
- <script src='/resources/highlighter/scripts/shBrushPlain.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -67,8 +66,73 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="Assets-Assets">Assets</h1><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
-<div class="error"><span class="error">Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null</span> </div></div><p>In Tapestry, <strong>Assets</strong> are any kind of <em>static</em> content that may be downloaded to a client web browser, such as images, style sheets and JavaScript files.</p><p>Assets are most commonly stored in the web application's context folder ... stored inside the web application WAR file in the usual JEE fashion. In addition, Tapestry treats files stored <em>on the classpath</em>, with your Java class files, as assets visible to the web browser.</p><p>Assets are exposed to your code as instances of the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Asset.html">Asset</a> interface.</p><h3 id="Assets-AssetsinTemplates">Assets in Templates</h3><p>Assets can also be referenced directly in templates. Two <a shape="rect" hr
ef="component-parameters.html">binding prefixes</a> exist for this: "asset:" and "context:". The "asset:" prefix can obtain assets from the classpath (the default) or from the web context (by specifying the "context:" domain explicitly):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<div id="ConfluenceContent"><p>In Tapestry, <strong>Assets</strong> are any kind of <em>static</em> content that may be downloaded to a client web browser, such as images, style sheets and JavaScript files.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="assets.html">Assets</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="layout-component.html">Layout Component</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="request-processing.html">Request Processing</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="configuration.html">Configuration</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="css.html">CSS</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="legacy-javascript.html">Legacy JavaScript</a>
+
+
+ </div>
+ </li></ul>
+</div><p>Assets are most commonly stored in the web application's context folder ... stored inside the web application WAR file in the usual JEE fashion. In addition, Tapestry treats files stored <em>on the classpath</em>, with your Java class files, as assets visible to the web browser.</p><p>Assets are exposed to your code as instances of the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Asset.html">Asset</a> interface.</p><h3 id="Assets-AssetsinTemplates">Assets in Templates</h3><p>Assets can also be referenced directly in templates. Two <a shape="rect" href="component-parameters.html">binding prefixes</a> exist for this: "asset:" and "context:". The "asset:" prefix can obtain assets from the classpath (the default) or from the web context (by specifying the "context:" domain explicitly):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><img src="${asset:context:image/tapestry_banner.gif}" alt="Banner"/>
</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>This is an example of using a <em>template expansion</em> inside an ordinary element (rather than a component).</p></div></div><p>Because accessing context assets is so common, the "context:" binding prefix was introduced:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
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 Jul 26 21:19:56 2015
@@ -67,8 +67,73 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="ComponentEvents-ComponentEvents">Component Events</h1><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
-<div class="error"><span class="error">Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null</span> </div></div><p><strong>Component events</strong> are Tapestry's way of conveying a user's interactions with the web page, such as clicking links and submitting forms, to designated methods in your page and component classes. When a component event occurs, Tapestry calls the event handler method you've provided, if any, in the containing component's class.</p><p>Let's review a simple example. Here's a portion of the template for a page (let's call it "Chooser") that lets the user choose a number between 1 and 10:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<div id="ConfluenceContent"><p><strong>Component events</strong> are Tapestry's way of conveying a user's interactions with the web page, such as clicking links and submitting forms, to designated methods in your page and component classes. When a component event occurs, Tapestry calls the event handler method you've provided, if any, in the containing component's class.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="page-navigation.html">Page Navigation</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-rendering.html">Component Rendering</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-events.html">Component Events</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-events-faq.html">Component Events FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="request-processing.html">Request Processing</a>
+
+
+ </div>
+ </li></ul>
+</div><p>Let's review a simple example. Here's a portion of the template for a page (let's call it "Chooser") that lets the user choose a number between 1 and 10:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><p> Choose a number from 1 to 10:
<t:count end="10" value="index">
@@ -123,7 +188,7 @@
</pre>
</div></div><p>Your event handler method may even declare that it "throws Exception" if that is more convenient.</p><h1 id="ComponentEvents-InterceptingEventExceptions">Intercepting Event Exceptions</h1><p>When an event handler method throws an exception (checked or runtime), Tapestry gives the component and its containing page a chance to handle the exception, before continuing on to report the exception.</p><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:0 1em">
<p> <strong>JumpStart Demo:</strong><br clear="none">
- <a shape="rect" class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/handlingabadcontext/1" >Handling A Bad Context</a></p></div><p>Tapestry emits a new event, of type "exception", passing the thrown exception as the context. In fact, the exception is wrapped inside a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/ComponentEventException.html">ComponentEventException</a>, from which you may extract the event type and context.</p><p>Thus:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+ <a shape="rect" class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/handlingabadcontext/1" >Handling A Bad Context</a></p></div>Tapestry emits a new event, of type "exception", passing the thrown exception as the context. In fact, the exception is wrapped inside a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/ComponentEventException.html">ComponentEventException</a>, from which you may extract the event type and context.<p>Thus:</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 onException(Throwable cause)
{
message = cause.getMessage();
Modified: websites/production/tapestry/content/component-mixins.html
==============================================================================
--- websites/production/tapestry/content/component-mixins.html (original)
+++ websites/production/tapestry/content/component-mixins.html Sun Jul 26 21:19:56 2015
@@ -32,7 +32,6 @@
<script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
<script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
<script src='/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
- <script src='/resources/highlighter/scripts/shBrushPlain.js' type='text/javascript'></script>
<script type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -67,8 +66,64 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><p>A <strong>Component Mixin</strong> is a way to supplement an existing Tapestry component with additional behavior.</p><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
-<div class="error"><span class="error">Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null</span> </div></div><p>You can think of a mixin as a kind of mashup for a component; it combines the new behavior of the mixin with the existing behavior of the component, and bundles it all in one place. Mixins may be used to add specialized validation to user input fields, dynamically modify the HTML output of a component, or to add Ajax effects and behaviors of all sorts to components.</p><p>Tapestry comes with several mixins, such as the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html">Autocomplete mixin</a> which adds autocomplete behavior to an ordinary TextField Component. In addition, you can easily create your own.</p><h2 id="ComponentMixins-MixinClasses">Mixin Classes</h2><p>Mixin classes are stored in the <cod
e>mixins</code> sub-package of your application, below the application (or library) root package. This parallels where your component and page classes are stored.</p><p>Other than that, mixin classes are the same as any other component class.</p><h2 id="ComponentMixins-MixinLimitations">Mixin Limitations</h2><p>Currently, mixins are allowed to do anything a component can do, including having parameters and render phase methods.</p><p>Mixins may not have a template. They integrate with the component strictly in terms of invoking render phase methods.</p><p>Mixins may have persistent fields, but currently, this is not implemented perfectly (there is a potential for a name clash between a mixin and the component or another mixin). Use persistent fields with mixins with care ... or better yet, delegate persistence to the container using parameters.</p><p>Mixins may not, themselves, have mixins.</p><h2 id="ComponentMixins-UsingMixins">Using Mixins</h2><p>Mixins are used in two different
scenarios: <em>Instance mixins</em> and <em>Implementation mixins</em>.</p><h3 id="ComponentMixins-InstanceMixins">Instance Mixins</h3><p>An instance mixin is a mixin applied to a specific <em>instance</em> of a component. This can be done in the <a shape="rect" href="component-templates.html">component template</a> with the <code>mixins</code> attribute of the component tag. This is a comma-separated list of mixin names.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<div id="ConfluenceContent"><p>A <strong>Component Mixin</strong> is a way to supplement an existing Tapestry component with additional behavior.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="page-and-component-classes-faq.html">Page And Component Classes FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="legacy-javascript.html">Legacy JavaScript</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-templates.html">Component Templates</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-cheat-sheet.html">Component Cheat Sheet</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-parameters.html">Component Parameters</a>
+
+
+ </div>
+ </li></ul>
+</div><p>You can think of a mixin as a kind of mashup for a component; it combines the new behavior of the mixin with the existing behavior of the component, and bundles it all in one place. Mixins may be used to add specialized validation to user input fields, dynamically modify the HTML output of a component, or to add Ajax effects and behaviors of all sorts to components.</p><p>Tapestry comes with several mixins, such as the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/mixins/Autocomplete.html">Autocomplete mixin</a> which adds autocomplete behavior to an ordinary TextField Component. In addition, you can easily create your own.</p><h2 id="ComponentMixins-MixinClasses">Mixin Classes</h2><p>Mixin classes are stored in the <code>mixins</code> sub-package of your application, below the application (or library) root package. This parallels where your component and page classes are stored.</p><p>Other than that, mi
xin classes are the same as any other component class.</p><h2 id="ComponentMixins-MixinLimitations">Mixin Limitations</h2><p>Currently, mixins are allowed to do anything a component can do, including having parameters and render phase methods.</p><p>Mixins may not have a template. They integrate with the component strictly in terms of invoking render phase methods.</p><p>Mixins may have persistent fields, but currently, this is not implemented perfectly (there is a potential for a name clash between a mixin and the component or another mixin). Use persistent fields with mixins with care ... or better yet, delegate persistence to the container using parameters.</p><p>Mixins may not, themselves, have mixins.</p><h2 id="ComponentMixins-UsingMixins">Using Mixins</h2><p>Mixins are used in two different scenarios: <em>Instance mixins</em> and <em>Implementation mixins</em>.</p><h3 id="ComponentMixins-InstanceMixins">Instance Mixins</h3><p>An instance mixin is a mixin applied to a specific
<em>instance</em> of a component. This can be done in the <a shape="rect" href="component-templates.html">component template</a> with the <code>mixins</code> attribute of the component tag. This is a comma-separated list of mixin names.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><t:textfield t:id="accountName" t:mixins="Autocomplete,DefaultFromCookie" />
</pre>
</div></div><p>Alternately, when the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation is used to define the component type, you may specify the mixins in two ways:</p><ul><li>The @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Mixins.html">Mixins</a> annotation allows a list of mixin names to be specified.</li><li>The @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinClasses.html">MixinClasses</a> annotation allows a set of mixin classes to be specified directly.</li></ul><p>The former is often less verbose, and allows core mixins to be overridden with application-specific mixins. The later format is more specific and more refactor-safe (renaming a mixin class will rename the entry in the MixinClasses annotation as well).</p>
<p>Example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
Modified: websites/production/tapestry/content/component-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Sun Jul 26 21:19:56 2015
@@ -67,19 +67,111 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
-<div class="error"><span class="error">Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null</span> </div></div><strong>Component parameters</strong> are the primary means for a component instance and its container to communicate with each other. Parameters are used to <em>configure</em> component instances.<p>In the following example, <code>page</code> is a parameter of the <code>pagelink</code> component. The page parameter tells the pagelink component which page to go to when the user clicks on the rendered hyperlink:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<div id="ConfluenceContent"><p><strong>Component parameters</strong> are the primary means for a component instance and its container to communicate with each other. Parameters are used to <em>configure</em> component instances.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-parameters.html">Component Parameters</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-templates.html">Component Templates</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="templating-and-markup-faq.html">Templating and Markup FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-classes.html">Component Classes</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="page-and-component-classes-faq.html">Page And Component Classes FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="enum-parameter-recipe.html">Enum Parameter Recipe</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="supporting-informal-parameters.html">Supporting Informal Parameters</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="default-parameter.html">Default Parameter</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-cheat-sheet.html">Component Cheat Sheet</a>
+
+
+ </div>
+ </li></ul>
+</div><p>In the following example, <code>page</code> is a parameter of the <code>pagelink</code> component. The page parameter tells the pagelink component which page to go to when the user clicks on the rendered hyperlink:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<t:pagelink page="Index">Go Home</t:pagelink>
</html></pre>
</div></div><p>A component may have any number of parameters. Each parameter has a specific name, a specific Java type (which may be a primitive value), and may be <em>optional</em> or <em>required</em>.</p><p>Within a component class, parameters are declared by using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html">Parameter</a> annotation on a private field, as we'll see below.</p><p><span class="confluence-anchor-link" id="ComponentParameters-bindingparameters"></span></p><h1 id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In Tapestry, a parameter is not a slot into which data is pushed: it is a <em>connection</em> between a field of the component (marked with the @Parameter annotation) and a property or resource of the component's container. (Components can be nested, so the container can be either the page or another component.)</p><div class="navmenu" style="float:r
ight; background:white; margin:3px; padding:3px">
<div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width: 1px;"><b>Contents</b></div><div class="panelContent">
<style type="text/css">/*<![CDATA[*/
-div.rbtoc1437340847807 {padding: 0px;}
-div.rbtoc1437340847807 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1437340847807 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1437945576417 {padding: 0px;}
+div.rbtoc1437945576417 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1437945576417 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style><div class="toc-macro rbtoc1437340847807">
+/*]]>*/</style><div class="toc-macro rbtoc1437945576417">
<ul class="toc-indentation"><li><a shape="rect" href="#ComponentParameters-ParameterBindings">Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-BindingExpressions">Binding Expressions</a></li><li><a shape="rect" href="#ComponentParameters-@Parameterannotation">@Parameter annotation</a></li><li><a shape="rect" href="#ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...} syntax!</a></li><li><a shape="rect" href="#ComponentParameters-InformalParameters">Informal Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParametersAreBi-Directional">Parameters Are Bi-Directional</a></li><li><a shape="rect" href="#ComponentParameters-InheritedParameterBindings">Inherited Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter Binding Defaults</a></li><li><a shape="rect" href="#ComponentParameters-UnboundParameters">Unbound Parameters</a></li><li><a shape="rect" href="#Compon
entParameters-ParameterTypeCoercion">Parameter Type Coercion</a></li><li><a shape="rect" href="#ComponentParameters-ParameterNames">Parameter Names</a></li><li><a shape="rect" href="#ComponentParameters-DeterminingifBound">Determining if Bound</a></li><li><a shape="rect" href="#ComponentParameters-PublishingParameters">Publishing Parameters</a></li></ul>
</div>
</div></div></div> <p>The connection between a component and a property (or resource) of its container is called a <em>binding</em>. The binding is two-way: the component can read the bound property by reading its parameter field. Likewise, a component that updates its parameter field will update the bound property.</p><p>This is important in a lot of cases; for example a TextField component can read <em>and update</em> the property bound to its value parameter. It reads the value when rendering, but updates the value when the form is submitted.</p><p>The component listed below is a looping component; it renders its body a number of times, defined by its <code>start</code> and <code>end</code> parameters (which set the boundaries of the loop). The component can update a <code>result</code> parameter bound to a property of its container; it will automatically count up or down depending on whether <code>start</code> or <code>end</code> is larger.</p><div class="code panel pdl" st
yle="border-width: 1px;"><div class="codeContent panelContent pdl">
Modified: websites/production/tapestry/content/component-rendering.html
==============================================================================
--- websites/production/tapestry/content/component-rendering.html (original)
+++ websites/production/tapestry/content/component-rendering.html Sun Jul 26 21:19:56 2015
@@ -67,43 +67,83 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="ComponentRendering-ComponentRendering">Component Rendering</h1>
+<div id="ConfluenceContent"><p><strong>Rendering of components</strong> in Tapestry 5 is based on a <em>state machine</em> and a <em>queue</em> (instead of the tail recursion used in Tapestry 4). This breaks the rendering process up into tiny pieces that can easily be implemented or overridden. Don't worry, in practice, writing components requires a breathtakingly small amount of code.</p><div class="aui-label" style="float:right" title="Related Articles">
-<div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
-<div class="error"><span class="error">Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null</span> </div></div>
-<p>Rendering of components in Tapestry 5 is based on a <em>state machine</em> and a <em>queue</em> (instead of the tail recursion used in Tapestry 4). This breaks the rendering process up into tiny pieces that can easily be implemented or overridden. Don't worry, in practice, writing components requires a breathtakingly small amount of code.</p>
-<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" src="component-rendering.data/tapestry_render_phases.png"></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 return 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 shape="rect" 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 shape="rect" 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 shape="rect" 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="confluen
ceTd"><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 shape="rect" 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 shape="rect" 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 r
enders the body of the component, if any </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> <a shape="rect" 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 shape="rect" 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 shape="rect" 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 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 shape="rect" 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 shape="rect" 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 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">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-package org.example.app.components;
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="content-type-and-markup.html">Content Type and Markup</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="page-navigation.html">Page Navigation</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-rendering.html">Component Rendering</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-events.html">Component Events</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="component-events-faq.html">Component Events FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a shape="rect" href="request-processing.html">Request Processing</a>
+
+
+ </div>
+ </li></ul>
+</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" src="component-rendering.data/tapestry_render_phases.png"></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 return 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 pha
se methods may take no parameters, or may take a parameter of type <a shape="rect" 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 shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html">@SetupRender</a></strong></p></t
d><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 shape="rect" 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 shape="rect" 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 shape="rect" 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 shape="rect" 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 colsp
an="1" rowspan="1" class="confluenceTd"><p><a shape="rect" 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 shape="rect" 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 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 shape="rect" 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 shape="rect" 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 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 p
anelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.AfterRender;
@@ -158,70 +198,10 @@ public class Count
}
}
</pre>
-</div></div>
-
-<p>Returning false from next() causes Tapestry to re-run the BeginRender phase, and from there, re-render the component's body (this component does not have a template). Returning true transitions to the CleanupRender phase.</p>
-
-<p>Notice how Tapestry adapts to your methods, as marked with the annotations. It also adapts in terms of parameters; the two annotated methods here did not perform any output, so they did not need a MarkupWriter.</p>
-
-<p>What's really mind blowing is that the template and body of a component will often contain ... more components! That means that many different components will be in different phases of their own state machine.</p>
-
-<h2 id="ComponentRendering-RenderPhasesinDetail">Render Phases in Detail</h2>
-
-
-<div class="navmenu" style="float:right; width:50%; background:#eee; margin:3px; padding:3px">
+</div></div><p>Returning false from next() causes Tapestry to re-run the BeginRender phase, and from there, re-render the component's body (this component does not have a template). Returning true transitions to the CleanupRender phase.</p><p>Notice how Tapestry adapts to your methods, as marked with the annotations. It also adapts in terms of parameters; the two annotated methods here did not perform any output, so they did not need a MarkupWriter.</p><p>What's really mind blowing is that the template and body of a component will often contain ... more components! That means that many different components will be in different phases of their own state machine.</p><h2 id="ComponentRendering-RenderPhasesinDetail">Render Phases in Detail</h2><p></p><div class="navmenu" style="float:right; width:50%; background:#eee; margin:3px; padding:3px">
<div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
-<p>The SetupRender phase, like all render phases, occurs once for each rendering of the component. If the component is inside a looping component (<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Loop.html">Loop</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Grid.html">Grid</a>, etc.), then the SetupRender method will be called once for <em>each</em> iteration of the loop.</p></div></div></div>
-
-<h3 id="ComponentRendering-SetupRender">SetupRender</h3>
-
-<p>The SetupRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html">SetupRender</a>) is where you can perform any one-time per-render setup for your component. This is a good place to read component parameters and use them to set temporary instance variables.</p>
-
-<h3 id="ComponentRendering-BeginRender">BeginRender</h3>
-
-<p>The BeginRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html">BeginRender</a>) occurs at the start of the rendering of the component. For components that render a tag, the start tag should be rendered here (the close tag should be rendered inside the AfterRender phase). The component can also prevent the template and/or body from being rendered by returning false.</p>
-
-<p>Components may or may not have a template. If a component has a template, and the template includes a <body> element, then the BeforeRenderBody phase will be triggered (giving the component the option of rendering its body or not).</p>
-
-<p>If a component does not have a <body> element in its template, then the BeforeRenderBody phase is not triggered.</p>
-
-<p>If a component does not have a template, but does have a body, the BeforeRenderBody phase is still triggered.</p>
-
-<p>If no methods are annotated with BeginRender, then no special output occurs during this phase, but the template (if present) or body (if no template is present, but the component has a body) will be rendered.</p>
-
-<h3 id="ComponentRendering-BeforeRenderTemplate">BeforeRenderTemplate</h3>
-
-<p>The BeforeRenderTemplate phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate.html">BeforeRenderTemplate</a>) exists to allow a component to decorate its template (creating markup around the template generated markup), or to allow a component to skip its template.</p>
-
-<h3 id="ComponentRendering-BeforeRenderBody">BeforeRenderBody</h3>
-
-<p>The BeforeRenderBody phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody.html">BeforeRenderBody</a>) is associated with a component's body (the portion of its container's template that the component occupies). The BeforeRenderBody phase allows the component the ability to skip the body, while still rendering the rest of the component's template (if any).</p>
-
-<p>If no methods are annotated with BeforeRenderBody, then the body will be rendered by default. Again, this occurs when the <body> element of the component's template is reached, or automatically if the component has no template (but the component does have a body).</p>
-
-<h3 id="ComponentRendering-AfterRenderBody">AfterRenderBody</h3>
-
-<p>The AfterRenderBody phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody.html">AfterRenderBody</a>) is executed after the body is rendered; this only occurs for components with a body.</p>
-
-<h3 id="ComponentRendering-AfterRender">AfterRender</h3>
-
-<p>The AfterRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender.html">AfterRender</a>) complements BeginRender, and is often used to render the close tag that matches the start tag rendered in the BeginRender phase. In any case, the AfterRender phase can continue on to CleanupRender, or revert back to BeginRender (as in our Count component example, above).</p>
-
-<p>If no methods are annotated with AfterRender, then no special output occurs, and the CleanupRender phase is triggered.</p>
-
-<h3 id="ComponentRendering-CleanupRender">CleanupRender</h3>
-
-<p>The CleanupRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender.html">CleanupRender</a>) is the counterpart to SetupRender, allowing final cleanup to occur.</p>
-
-<h2 id="ComponentRendering-UsingMethodNamesinsteadofAnnotations">Using Method Names instead of Annotations</h2>
-
-<p>If you prefer to avoid using annotations on your methods, you may do so by providing specific names for your methods. The required method name is the annotation name, with the first character decapitalized: setupRender(), beginRender(), etc. As with annotated render phase methods, Tapestry is flexible about visibility, return type and parameters.</p>
-
-<p>Using this mechanism, the earlier example can be rewritten as:</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;
+<p>The SetupRender phase, like all render phases, occurs once for each rendering of the component. If the component is inside a looping component (<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Loop.html">Loop</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Grid.html">Grid</a>, etc.), then the SetupRender method will be called once for <em>each</em> iteration of the loop.</p></div></div></div><h3 id="ComponentRendering-SetupRender">SetupRender</h3><p>The SetupRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html">SetupRender</a>) is where you can perform any one-time per-render setup for your component. This is a good place to read component parameters and use them to set temporary instance variables.</p><h3 id="Component
Rendering-BeginRender">BeginRender</h3><p>The BeginRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html">BeginRender</a>) occurs at the start of the rendering of the component. For components that render a tag, the start tag should be rendered here (the close tag should be rendered inside the AfterRender phase). The component can also prevent the template and/or body from being rendered by returning false.</p><p>Components may or may not have a template. If a component has a template, and the template includes a <body> element, then the BeforeRenderBody phase will be triggered (giving the component the option of rendering its body or not).</p><p>If a component does not have a <body> element in its template, then the BeforeRenderBody phase is not triggered.</p><p>If a component does not have a template, but does have a body, the BeforeRenderBody phase is still triggered.
</p><p>If no methods are annotated with BeginRender, then no special output occurs during this phase, but the template (if present) or body (if no template is present, but the component has a body) will be rendered.</p><h3 id="ComponentRendering-BeforeRenderTemplate">BeforeRenderTemplate</h3><p>The BeforeRenderTemplate phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate.html">BeforeRenderTemplate</a>) exists to allow a component to decorate its template (creating markup around the template generated markup), or to allow a component to skip its template.</p><h3 id="ComponentRendering-BeforeRenderBody">BeforeRenderBody</h3><p>The BeforeRenderBody phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody.html">BeforeRenderBody</a>) is associated with a component's body (the portion of its containe
r's template that the component occupies). The BeforeRenderBody phase allows the component the ability to skip the body, while still rendering the rest of the component's template (if any).</p><p>If no methods are annotated with BeforeRenderBody, then the body will be rendered by default. Again, this occurs when the <body> element of the component's template is reached, or automatically if the component has no template (but the component does have a body).</p><h3 id="ComponentRendering-AfterRenderBody">AfterRenderBody</h3><p>The AfterRenderBody phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody.html">AfterRenderBody</a>) is executed after the body is rendered; this only occurs for components with a body.</p><h3 id="ComponentRendering-AfterRender">AfterRender</h3><p>The AfterRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org
/apache/tapestry5/annotations/AfterRender.html">AfterRender</a>) complements BeginRender, and is often used to render the close tag that matches the start tag rendered in the BeginRender phase. In any case, the AfterRender phase can continue on to CleanupRender, or revert back to BeginRender (as in our Count component example, above).</p><p>If no methods are annotated with AfterRender, then no special output occurs, and the CleanupRender phase is triggered.</p><h3 id="ComponentRendering-CleanupRender">CleanupRender</h3><p>The CleanupRender phase (see @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender.html">CleanupRender</a>) is the counterpart to SetupRender, allowing final cleanup to occur.</p><h2 id="ComponentRendering-UsingMethodNamesinsteadofAnnotations">Using Method Names instead of Annotations</h2><p>If you prefer to avoid using annotations on your methods, you may do so by providing specific n
ames for your methods. The required method name is the annotation name, with the first character decapitalized: setupRender(), beginRender(), etc. As with annotated render phase methods, Tapestry is flexible about visibility, return type and parameters.</p><p>Using this mechanism, the earlier example can be rewritten as:</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;
@@ -272,35 +252,8 @@ public class Count
}
}
</pre>
-</div></div>
-
-<p>This style is a trade off: on the gain side, the code is <em>even</em> simpler and shorter, and the method names will, by design, be more consistent from one class to the next. The down side is that the names are very generic, and may in some cases, be less descriptive than using annotated methods (<code>initializeValue()</code> and <code>next()</code> are, to some eyes, more descriptive).</p>
-
-<p>You can, of course, mix and match, using specifically named render phase methods in some cases, and annotated render phase methods in other cases.</p>
-
-<h2 id="ComponentRendering-RenderingComponents">Rendering Components</h2>
-
-<p>Instead of returning true or false, a render phase method may return a component. The component may have been injected via the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation, or may have been passed to the owning component as a parameter.</p>
-
-<p>In any case, returning a component will queue that component to be rendered <strong>before</strong> the active component continues rendering.</p>
-
-<p>The component to render may even be from a completely different page of the application.</p>
-
-<p>Recursive rendering of components is not allowed.</p>
-
-<p>This technique allows the rendering of Tapestry pages to be <em>highly</em> dynamic.</p>
-
-<p>Returning a component instance does <strong>not</strong> short circuit method invocation (as described below), the way returning a boolean would. It is possible that multiple methods may return components (this is not advised – insanity may ensue).</p>
-
-<h2 id="ComponentRendering-AdditionalReturnTypes">Additional Return Types</h2>
-
-<p>Render phase methods may also return <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Blocks</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Renderable.html">Renderables</a> or <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/RenderCommand.html">RenderCommands</a>.</p>
-
-<p>The following component returns a Renderable in the BeginRender phase and skips the BeforeRenderTemplate phase:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
-public class OutputValueComponent
+</div></div><p>This style is a trade off: on the gain side, the code is <em>even</em> simpler and shorter, and the method names will, by design, be more consistent from one class to the next. The down side is that the names are very generic, and may in some cases, be less descriptive than using annotated methods (<code>initializeValue()</code> and <code>next()</code> are, to some eyes, more descriptive).</p><p>You can, of course, mix and match, using specifically named render phase methods in some cases, and annotated render phase methods in other cases.</p><h2 id="ComponentRendering-RenderingComponents">Rendering Components</h2><p>Instead of returning true or false, a render phase method may return a component. The component may have been injected via the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation, or may have been passed to the owning component as a parameter.</p>
<p>In any case, returning a component will queue that component to be rendered <strong>before</strong> the active component continues rendering.</p><p>The component to render may even be from a completely different page of the application.</p><p>Recursive rendering of components is not allowed.</p><p>This technique allows the rendering of Tapestry pages to be <em>highly</em> dynamic.</p><p>Returning a component instance does <strong>not</strong> short circuit method invocation (as described below), the way returning a boolean would. It is possible that multiple methods may return components (this is not advised – insanity may ensue).</p><h2 id="ComponentRendering-AdditionalReturnTypes">Additional Return Types</h2><p>Render phase methods may also return <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Blocks</a>, <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apach
e/tapestry5/Renderable.html">Renderables</a> or <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/RenderCommand.html">RenderCommands</a>.</p><p>The following component returns a Renderable in the BeginRender phase and skips the BeforeRenderTemplate phase:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class OutputValueComponent
{
@Parameter
private String value;
@@ -317,58 +270,8 @@ public class OutputValueComponent
}
}
</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 shape="rect" 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 methods execute before the mixin subclass' render phase methods.</p>
-
-<p>Exception: Mixins whose class is annotated with @<a shape="rect" 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 shape="rect" 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>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 shape="rect" 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">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 shape="rect" href="configuration.html">production mode</a>.</p>
-
-<p>To turn on rendering comments for all requests, set the <a shape="rect" 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
+</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 shape="rect" 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 pare
nt class methods execute before the mixin subclass' render phase methods.</p><p>Exception: Mixins whose class is annotated with @<a shape="rect" 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 shape="rect" 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. Th
e 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 shape="rect" 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><h
3 id="ComponentRendering-WithinaSingleClass">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 onl
y available when not running in <a shape="rect" href="configuration.html">production mode</a>.</p><p>To turn on rendering comments for all requests, set the <a shape="rect" 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>
</div>
Modified: websites/production/tapestry/content/component-templates.html
==============================================================================
--- websites/production/tapestry/content/component-templates.html (original)
+++ websites/production/tapestry/content/component-templates.html Sun Jul 26 21:19:56 2015
@@ -159,7 +159,7 @@
</div>
</li></ul>
-</div><p>Under Tapestry, a <strong>component template</strong> is a file that contains the markup for a component.</p><p>Component templates are <em>well formed XML documents</em>. That means that every open tag must have a matching close tag, every attribute must be quoted, and so forth.</p><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>At runtime, Tapestry parses the documents and <em>only</em> checks for wellformedness. Even when the document has a DTD or schema, there are no validity checks.</p></div></div><p>For the most part, these templates are standard HTML/XHTML; Tapestry extensions to ordinary markup are provided in the form of a Tapestry namespace:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>A template for
a page</b></div><div class="codeContent panelContent pdl">
+</div><p>Under Tapestry, a <strong>component template</strong> is a file that contains the markup for a component.</p><p>Component templates are <em>well formed XML documents</em>. That means that every open tag must have a matching close tag, every attribute must be quoted, and so forth.</p><p><em>Note: At runtime, Tapestry parses the documents and only checks for wellformedness. Even when the document has a DTD or schema, there are no validity checks.</em></p><p>For the most part, these templates are standard HTML/XHTML; Tapestry extensions to ordinary markup are provided in the form of a Tapestry namespace:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>A template for a page</b></div><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<h1>Bonjour from HelloWorld component.</h1>
</html>
Modified: websites/production/tapestry/content/content-type-and-markup.html
==============================================================================
--- websites/production/tapestry/content/content-type-and-markup.html (original)
+++ websites/production/tapestry/content/content-type-and-markup.html Sun Jul 26 21:19:56 2015
@@ -57,30 +57,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h2 id="ContentTypeandMarkup-ContentTypeandMarkupOutput">Content Type and Markup Output</h2>
-
-<p>Tapestry reads <a shape="rect" href="component-templates.html">well-formed XML template files</a> and renders its output as XML, with minor caveats:</p>
-
-<ul><li>The <?xml?> XML declaration is omitted.</li><li>Most element render with an open and close tag, even if empty.</li><li>Certain elements will be abbreviated to just the open tag, if empty:
- <ul><li>br</li><li>hr</li><li>img</li></ul>
- </li><li><![CDATA[]> sections are <strong>not</strong> used</li></ul>
-
-
-<p>This is all to ensure that the markup stream, while (almost) well formed, is still properly understood by browsers expecting ordinary HTML. In fact, Tapestry may decide to render a purely XML document; it depends on the content type of the response. </p>
-
-<p>When Tapestry renders a page, the output content type and charset is obtained from meta data on the page itself. Meta data is specified using the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Meta.html">@Meta</a> annotation.</p>
-
-<h3 id="ContentTypeandMarkup-ContentType">Content Type</h3>
-
-<p>The response content type is obtained via meta-data key <code>tapestry.response-content-type</code>. This value defaults to "text/html", which triggers specialized XML rendering.</p>
-
-<p>A page may declare its content type using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/ContentType.html">ContentType</a> class annotation. Content types other than "text/html" will render as well-formed XML documents, including the XML declaration, and more standard behavior for empty elements.</p>
-
-<h3 id="ContentTypeandMarkup-CharacterSet">Character Set</h3>
-
-<p>The character set (aka character encoding) used when writing output and when parsing requests is normally "utf-8". UTF-8 is a version of Unicode where individual characters are encoded as one or more bytes. Most western language characters (that is, typical ASCII characters) are encoded in a single byte. Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded as two or more bytes.</p>
-
-<p>All pages use the same encoding, which can be set using the <code>tapestry.charset</code> <a shape="rect" href="configuration.html">configuration setting</a>.</p></div>
+<div id="ConfluenceContent"><p>Tapestry reads <a shape="rect" href="component-templates.html">well-formed XML template files</a> and renders its output as XML, with minor caveats:</p><ul><li>The <?xml?> XML declaration is omitted.</li><li>Most element render with an open and close tag, even if empty.</li><li>Certain elements will be abbreviated to just the open tag, if empty:<ul><li>br</li><li>hr</li><li>img</li></ul></li><li><![CDATA[]> sections are <strong>not</strong> used</li></ul><p>This is all to ensure that the markup stream, while (almost) well formed, is still properly understood by browsers expecting ordinary HTML. In fact, Tapestry may decide to render a purely XML document; it depends on the content type of the response.</p><p>When Tapestry renders a page, the output content type and charset is obtained from meta data on the page itself. Meta data is specified using the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org
/apache/tapestry5/annotations/Meta.html">@Meta</a> annotation.</p><h3 id="ContentTypeandMarkup-ContentType">Content Type</h3><p>The response content type is obtained via meta-data key <code>tapestry.response-content-type</code>. This value defaults to "text/html", which triggers specialized XML rendering.</p><p>A page may declare its content type using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/ContentType.html">ContentType</a> class annotation. Content types other than "text/html" will render as well-formed XML documents, including the XML declaration, and more standard behavior for empty elements.</p><h3 id="ContentTypeandMarkup-CharacterSet">Character Set</h3><p>The character set (aka character encoding) used when writing output and when parsing requests is normally "utf-8". UTF-8 is a version of Unicode where individual characters are encoded as one or more bytes. Most western language characters (
that is, typical ASCII characters) are encoded in a single byte. Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded as two or more bytes.</p><p>All pages use the same encoding, which can be set using the <code>tapestry.charset</code> <a shape="rect" href="configuration.html">configuration setting</a>.</p></div>
</div>
<div class="clearer"></div>