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/03 16:21:23 UTC
svn commit: r1024781 [8/11] - in /websites/production/tapestry/content: ./
cache/
Modified: websites/production/tapestry/content/integration-testing.html
==============================================================================
--- websites/production/tapestry/content/integration-testing.html (original)
+++ websites/production/tapestry/content/integration-testing.html Sat Feb 3 16:21:22 2018
@@ -45,13 +45,26 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/">Security</a></li><li><a class="external-link" href="http://www.apache.org/">Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></div></div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/">Security</a></li><li><a class="external-link" href="http://www.apache.org/">Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></div>
+
+</div>
<div id="top">
- <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html">
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png" data-image-src="http://tapestry.apache.org/images/tapestry_small.png"></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Integration Testing</h1></div></div>
+ <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
+<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html">
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form>
+
+</div>
+
+
+<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png" data-image-src="http://tapestry.apache.org/images/tapestry_small.png"></span></a></p></div>
+
+
+<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Integration Testing</h1></div>
+
+</div>
<div class="clearer"></div>
</div>
@@ -63,19 +76,40 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Integration testing</strong> involves the testing of larger segments of your Tapestry module or web application, typically including the user interface.</p><div class="aui-label" style="float:right" title="Related Articles"><h3>Related Articles</h3><ul class="content-by-label"><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span>
- </div>
- <div class="details">
- <a href="integration-testing.html">Integration Testing</a>
- </div> </li><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span>
- </div>
- <div class="details">
- <a href="unit-testing-pages-or-components.html">Unit testing pages or components</a>
- </div> </li></ul></div><p>The Tapestry Test Utilities is a small library to make it easier to build integration test suites around <a class="external-link" href="http://www.openqa.org/selenium/" rel="nofollow">Selenium</a> version 2.14.0.</p><p>The strategy is to start, in-process, a Selenimum Server (which, in turn, starts and manages a web browser), a Jetty instance (for the web browser to talk to), and a Selenium client (which talks to the server).</p><p>The client is able to request URLs, fill in form data, click links, and make assertions about output and behavior.</p><h1 id="IntegrationTesting-Usage">Usage</h1><p>The core part of this library is a base class for you to extend your tests classes : <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/SeleniumTestCase.html">SeleniumTestCase</a>.</p><p>This class is responsible for starting an instance of Jetty to server your web application, as well as a copy of Selenium Server.
It also implements the <a class="external-link" href="http://release.openqa.org/selenium-remote-control/0.9.0/doc/java/" rel="nofollow">Selenium</a> interface.</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>Before Tapestry 5.2, your class should extend <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/AbstractIntegrationTestSuite.html">AbstractIntegrationTestSuite</a></p></div></div><p>Here's an example from one of the Tapestry modules:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Your Integration Test Class : SinglePersistenceUnitIntegrationTest.java</b></div><div class="codeContent panelContent pdl">
+ <div id="ConfluenceContent"><p><strong>Integration testing</strong> involves the testing of larger segments of your Tapestry module or web application, typically including the user interface.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="integration-testing.html">Integration Testing</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="unit-testing-pages-or-components.html">Unit testing pages or components</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>The Tapestry Test Utilities is a small library to make it easier to build integration test suites around <a class="external-link" href="http://www.openqa.org/selenium/" rel="nofollow">Selenium</a> version 2.14.0.</p><p>The strategy is to start, in-process, a Selenimum Server (which, in turn, starts and manages a web browser), a Jetty instance (for the web browser to talk to), and a Selenium client (which talks to the server).</p><p>The client is able to request URLs, fill in form data, click links, and make assertions about output and behavior.</p><h1 id="IntegrationTesting-Usage">Usage</h1><p>The core part of this library is a base class for you to extend your tests classes : <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/SeleniumTestCase.html">SeleniumTestCase</a>.</p><p>This class is responsible for starting an instance of Jetty to server your web application, as well as a copy of Selenium Server. It also implements the <a
class="external-link" href="http://release.openqa.org/selenium-remote-control/0.9.0/doc/java/" rel="nofollow">Selenium</a> interface.</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>Before Tapestry 5.2, your class should extend <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/AbstractIntegrationTestSuite.html">AbstractIntegrationTestSuite</a></p></div></div><p>Here's an example from one of the Tapestry modules:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Your Integration Test Class : SinglePersistenceUnitIntegrationTest.java</b></div><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.apache.tapestry5.jpa.integration.app2;
import org.apache.tapestry5.test.SeleniumTestCase;
Modified: websites/production/tapestry/content/layout-component.html
==============================================================================
--- websites/production/tapestry/content/layout-component.html (original)
+++ websites/production/tapestry/content/layout-component.html Sat Feb 3 16:21:22 2018
@@ -45,13 +45,26 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/">Security</a></li><li><a class="external-link" href="http://www.apache.org/">Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></div></div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/">Security</a></li><li><a class="external-link" href="http://www.apache.org/">Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></div>
+
+</div>
<div id="top">
- <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html">
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png" data-image-src="http://tapestry.apache.org/images/tapestry_small.png"></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Layout Component</h1></div></div>
+ <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
+<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html">
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form>
+
+</div>
+
+
+<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png" data-image-src="http://tapestry.apache.org/images/tapestry_small.png"></span></a></p></div>
+
+
+<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Layout Component</h1></div>
+
+</div>
<div class="clearer"></div>
</div>
@@ -63,43 +76,76 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><div class="aui-label" style="float:right" title="Related Articles"><h3>Related Articles</h3><ul class="content-by-label"><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span>
- </div>
- <div class="details">
- <a href="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 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 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 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 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 href="component-cheat-sheet.html">Component Cheat Sheet</a>
- </div> </li></ul></div><p>You'll see frequent reference to a <strong>Layout Component</strong> in Tapestry documentation, but you won't find such a component in the <a href="component-reference.html">component reference</a>. The Layout component is a component <em>that you create</em> to provide common elements across all of your pages.</p><p>In traditional servlet development, you may be familiar with the use of a JSP include to include a banner across the top of your page and a copyright message across the bottom. In Tapestry, you <em>could</em> implement those recurring page elements as components (a banner component, a copyright component, etc.) and then add those components to every page.</p><p>But there's an even better way. Just create a layout component that provides the overall structure and recurring content for your pages:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Layout.tml (a
template for a Layout component)</b></div><div class="codeContent panelContent pdl">
+ <div id="ConfluenceContent"><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="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 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 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 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 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 href="component-cheat-sheet.html">Component Cheat Sheet</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>You'll see frequent reference to a <strong>Layout Component</strong> in Tapestry documentation, but you won't find such a component in the <a href="layout-component.html">component reference</a>. The Layout component is a component <em>that you create</em> to provide common elements across all of your pages.</p><p>In traditional servlet development, you may be familiar with the use of a JSP include to include a banner across the top of your page and a copyright message across the bottom. In Tapestry, you <em>could</em> implement those recurring page elements as components (a banner component, a copyright component, etc.) and then add those components to every page.</p><p>But there's an even better way. Just create a layout component that provides the overall structure and recurring content for your pages:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Layout.tml (a template for a Layout compo
nent)</b></div><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<head>
<title>My Nifty Web Application</title>
@@ -127,13 +173,13 @@
</p>
</html>
</pre>
-</div></div><p>Note the "t:type="layout" part. That says, in effect, "wrap the layout component around my <em>content</em>".</p><p>The magic is in the <t:body/> element of the layout template; this will be replaced by each page's <em>content</em>, whatever that is.</p><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Remember that if your layout component includes a link to a resource such as an image or a stylesheet, you must use an <em>absolute</em> URL. The same component will be used for pages in many different folders, or with many different activation contexts, so relative URLs won't work. The best approach is to use the <a href="assets.html">context binding prefix</a>.</p></div></div><p>To keep our Welcome.tml page template relatively preview-able, we are using an <html> element and the
t:type attribute to specify that it is a component. At render time, the page's <html> tag will be removed, and replaced with the content from the Layout.tml template (which conveniently starts with an <html> element). The <t:body> element in Layout.tml will be replaced with the page-specific content here: the <h1> and <p> tags.</p><p>Any page in the application that follows this pattern, using the Layout component, will have the same look and feel.</p><p>Layout is a regular component like other, with an ordinary component template. Like all component templates, it will be stored on the classpath (typically under src/main/resources).</p><p>Components must always have a Java class. But in this trivial example, the Layout component doesn't need any logic:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Layout.java</b></div><div class="codeContent panelContent pdl">
+</div></div><p>Note the "t:type="layout" part. That says, in effect, "wrap the layout component around my <em>content</em>".</p><p>The magic is in the <t:body/> element of the layout template; this will be replaced by each page's <em>content</em>, whatever that is.</p><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Remember that if your layout component includes a link to a resource such as an image or a stylesheet, you must use an <em>absolute</em> URL. The same component will be used for pages in many different folders, or with many different activation contexts, so relative URLs won't work. The best approach is to use the <a href="layout-component.html">context binding prefix</a>.</p></div></div><p>To keep our Welcome.tml page template relatively preview-able, we are using an <html> eleme
nt and the t:type attribute to specify that it is a component. At render time, the page's <html> tag will be removed, and replaced with the content from the Layout.tml template (which conveniently starts with an <html> element). The <t:body> element in Layout.tml will be replaced with the page-specific content here: the <h1> and <p> tags.</p><p>Any page in the application that follows this pattern, using the Layout component, will have the same look and feel.</p><p>Layout is a regular component like other, with an ordinary component template. Like all component templates, it will be stored on the classpath (typically under src/main/resources).</p><p>Components must always have a Java class. But in this trivial example, the Layout component doesn't need any logic:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Layout.java</b></div><div class="codeContent panelContent
pdl">
<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Import(stylesheet="context:css/site.css")
public class Layout
{
}
</pre>
-</div></div><p>We use the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html">Import</a> annotation (in 5.2 or later), as opposed to directly adding the <link> element to the template, for significant performance benefits <a href="assets.html">described elsewhere</a>. (For 5.0 and 5.1, use the deprecated @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html">IncludeStyleSheet</a> annotation instead.)</p><p>You may find that your application has more than one look and feel: perhaps user registration pages have one look, while administrative pages have another. This can be accomplished by having multiple layout components (using any names you choose) and using those different layout types for different pages.</p><h2 id="LayoutComponent-NestedLayouts">Nested Layouts</h2><p>Layouts are really just ordinary components, so they can be n
ested to any level needed. You can have, for example, a "CommonLayout" component that provides the peripheral elements for all your pages, and then a more specialized "AdminLayout" component that provides the layout only for the administrative pages, and make the AdminLayout component wrap itself in the CommonLayout component. So then the administrative pages would start with <code><html t:type="adminLayout" ...></code> and the other pages (and the AdminLayout component itself) would start with <code><html t:type="commonLayout" ...></code>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AdminLayout.tml</b></div><div class="codeContent panelContent pdl">
+</div></div><p>We use the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html">Import</a> annotation (in 5.2 or later), as opposed to directly adding the <link> element to the template, for significant performance benefits <a href="layout-component.html">described elsewhere</a>. (For 5.0 and 5.1, use the deprecated @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html">IncludeStyleSheet</a> annotation instead.)</p><p>You may find that your application has more than one look and feel: perhaps user registration pages have one look, while administrative pages have another. This can be accomplished by having multiple layout components (using any names you choose) and using those different layout types for different pages.</p><h2 id="LayoutComponent-NestedLayouts">Nested Layouts</h2><p>Layouts are really just ordinary components, so the
y can be nested to any level needed. You can have, for example, a "CommonLayout" component that provides the peripheral elements for all your pages, and then a more specialized "AdminLayout" component that provides the layout only for the administrative pages, and make the AdminLayout component wrap itself in the CommonLayout component. So then the administrative pages would start with <code><html t:type="adminLayout" ...></code> and the other pages (and the AdminLayout component itself) would start with <code><html t:type="commonLayout" ...></code>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AdminLayout.tml</b></div><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><html t:type="commonLayout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<h1>Administrative Functions</h1>
@@ -198,7 +244,7 @@ public class Layout
</html>
</pre>
-</div></div><p>The <p:style> element (and its contents) are passed to the layout component as a <code>style</code> parameter (a block parameter, in this case, so you must have the <code>xmlns:p="tapestry:parameter"</code> namespace declared, as above).</p><p>The rendered HTML would look like the following (whitespace aside, and assuming UserList.java has a backgroundImage property whose value is the string "http://www.example.com/fuzzy.gif"):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>The rendered HTML</b></div><div class="codeContent panelContent pdl">
+</div></div><p>The <p:style> element (and its contents) are passed to the layout component as a <code>style</code> parameter (a block parameter, in this case, so you must have the <code>xmlns:p="tapestry:parameter"</code> namespace declared, as above).</p><p>The rendered HTML would look like the following (whitespace aside, and assuming UserList.java has a backgroundImage property whose value is the string "<a class="external-link" href="http://www.example.com/fuzzy.gif" rel="nofollow">http://www.example.com/fuzzy.gif</a>"):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>The rendered HTML</b></div><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><!DOCTYPE html>
<html>
<head>
Modified: websites/production/tapestry/content/localization.html
==============================================================================
--- websites/production/tapestry/content/localization.html (original)
+++ websites/production/tapestry/content/localization.html Sat Feb 3 16:21:22 2018
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css' rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js' type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,32 +77,94 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p> </p><p><strong>Localization</strong> (aka L10n) is all about getting the right text to the user, in the right language.</p><parameter ac:name="style">float:right</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="class">aui-label</parameter><rich-text-body><parameter ac:name="showLabels">false</parameter><parameter ac:name="showSpace">false</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="cql">label in ("component-templates","localization") and space = currentSpace()</parameter></rich-text-body><p>Localization support is well integrated into Tapestry. Tapestry allows you to easily separate the text you present to your users from the rest of your application ... pull it out of your Java code and even out of your component templates. You can then translate your messages into other languages and let Tapestry put everything together.</p><h2 id="Localization-Compon
entMessageCatalogs">Component Message Catalogs</h2><p>Each component class may have a component message catalog. A component message catalog is a set of files with the extension ".properties". These property files are the same format used by java.util.ResourceBundle, just lines of <code>key=value</code>. These files are stored on the classpath, in the same package folder as the page or component's compiled Java class.</p><p>So for a class named <code>org.example.myapp.pages.MyPage</code>, you would have a main properties file as <code>org/example/myapp/pages/MyPage.properties</code>.</p><p>If you have a translations of these values, you provide additional properties file, adding an <a class="external-link" href="http://www.loc.gov/standards/iso639-2/englangn.html" rel="nofollow">ISO language code</a> before the extension. Thus, if you have a French translation, you could create a file <code>MyPage_fr.properties</code>.</p><p>Any values in the more language specific file will <em>ov
erride</em> values from the main properties file. If you had an even more specific localization for just French as spoken in France, you could create <code>MyPage_fr_FR.properties</code> (that's a language code plus a country code, and you can even go further and add variants ... but its unlikely that you'll ever need to go beyond just language codes in practice).</p><p>The messages in the catalog are accessed by keys. Tapestry ignores the case of the keys when accessing messages in the catalog.</p><h3 id="Localization-ComponentMessageCatalogInheritance">Component Message Catalog Inheritance</h3><p>If a component class is a subclass of another component class, then it inherits that base class' message catalog. Its own message catalog extends and overrides the values inherited from the base class.</p><p>In this way, you could have a base component class that contained common messages, and extend or override those messages in subclasses (just as you would extend or override the method
s of the base component class). This, of course, works for as many levels of inheritance as you care to support.</p><h2 id="Localization-Application-wideMessageCatalog">Application-wide Message Catalog</h2><p>If the file <code>WEB-INF/</code><em>AppName</em><code>.properties</code> exists in the context, it will be used as an application-wide message catalog. The <em>AppName</em> is derived from the name of the filter inside the web.xml file; this is most often just "app", thus <code>WEB-INF/app.properties</code>. The search for the file is case sensitive. The properties files may be localized.</p><p>Individual pages and components can override the values defined in the message catalog.<plain-text-body>{float:right|width=45%}
-{note:title=Avoid BOMs}
-Make sure that your properties files don't contain [byte order marks (BOM)|http://en.wikipedia.org/wiki/Byte_order_mark], because Java -- and thus Tapestry -- doesn't support BOM in properties files (see http://bugs.sun.com/view_bug.do?bug_id=4508058). Some editors write them out when saving a file in UTF-8, so watch out.
-{note}
-{float}</plain-text-body></p><h2 id="Localization-PropertiesFileCharset">Properties File Charset</h2><p>Tapestry uses the <code>UTF-8</code> character set (charset) when reading the properties files in a message catalog. This means that you don't have to use the Java <code>native2ascii</code> tool.</p><h2 id="Localization-LocalizedComponentTemplates">Localized Component Templates</h2><p>The same lookup mechanism applies to component templates. Tapestry will search for a localized version of each component template and use the closest match. Thus you could have <code>MyPage_fr.html</code> for French users, and <code>MyPage.html</code> for all other users.</p><h2 id="Localization-AccessingLocalizedMessages">Accessing Localized Messages</h2><p>The above discusses what files to create and where to store them, but doesn't address how to make use of that information.</p><p>Messages can be accessed in one of two ways:</p><ul><li>Using the "message:" <a href="component-parameters.html">bin
ding expression</a> in a component template</li><li>By injecting the component's Messages object<br clear="none"> In the first case, you may use the message: binding prefix with component parameters, or with template expansions:</li></ul><parameter ac:name="">java</parameter><plain-text-body><t:layout title="message:page-title">
+ <div id="ConfluenceContent"><p> </p><p><strong>Localization</strong> (aka L10n) is all about getting the right text to the user, in the right language.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="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 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 href="localization.html">Localization</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="component-parameters.html">Component Parameters</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>Localization support is well integrated into Tapestry. Tapestry allows you to easily separate the text you present to your users from the rest of your application ... pull it out of your Java code and even out of your component templates. You can then translate your messages into other languages and let Tapestry put everything together.</p><h2 id="Localization-ComponentMessageCatalogs">Component Message Catalogs</h2><p>Each component class may have a component message catalog. A component message catalog is a set of files with the extension ".properties". These property files are the same format used by java.util.ResourceBundle, just lines of <code>key=value</code>. These files are stored on the classpath, in the same package folder as the page or component's compiled Java class.</p><p>So for a class named <code>org.example.myapp.pages.MyPage</code>, you would have a main properties file as <code>org/example/myapp/pages/MyPage.properties</code>.</p><p>If you have a translations o
f these values, you provide additional properties file, adding an <a class="external-link" href="http://www.loc.gov/standards/iso639-2/englangn.html" rel="nofollow">ISO language code</a> before the extension. Thus, if you have a French translation, you could create a file <code>MyPage_fr.properties</code>.</p><p>Any values in the more language specific file will <em>override</em> values from the main properties file. If you had an even more specific localization for just French as spoken in France, you could create <code>MyPage_fr_FR.properties</code> (that's a language code plus a country code, and you can even go further and add variants ... but its unlikely that you'll ever need to go beyond just language codes in practice).</p><p>The messages in the catalog are accessed by keys. Tapestry ignores the case of the keys when accessing messages in the catalog.</p><h3 id="Localization-ComponentMessageCatalogInheritance">Component Message Catalog Inheritance</h3><p>If a component clas
s is a subclass of another component class, then it inherits that base class' message catalog. Its own message catalog extends and overrides the values inherited from the base class.</p><p>In this way, you could have a base component class that contained common messages, and extend or override those messages in subclasses (just as you would extend or override the methods of the base component class). This, of course, works for as many levels of inheritance as you care to support.</p><h2 id="Localization-Application-wideMessageCatalog">Application-wide Message Catalog</h2><p>If the file <code>WEB-INF/</code><em>AppName</em><code>.properties</code> exists in the context, it will be used as an application-wide message catalog. The <em>AppName</em> is derived from the name of the filter inside the web.xml file; this is most often just "app", thus <code>WEB-INF/app.properties</code>. The search for the file is case sensitive. The properties files may be localized.</p><p>Individual pages
and components can override the values defined in the message catalog.</p><div class="navmenu" style="float:right; width:45%; background:white; margin:3px; padding:3px">
+<div class="confluence-information-macro confluence-information-macro-note"><p class="title">Avoid BOMs</p><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
+<p>Make sure that your properties files don't contain <a class="external-link" href="http://en.wikipedia.org/wiki/Byte_order_mark" rel="nofollow">byte order marks (BOM)</a>, because Java – and thus Tapestry – doesn't support BOM in properties files (see <a class="external-link" href="http://bugs.sun.com/view_bug.do?bug_id=4508058" rel="nofollow">http://bugs.sun.com/view_bug.do?bug_id=4508058</a>). Some editors write them out when saving a file in UTF-8, so watch out.</p></div></div></div><h2 id="Localization-PropertiesFileCharset">Properties File Charset</h2><p>Tapestry uses the <code>UTF-8</code> character set (charset) when reading the properties files in a message catalog. This means that you don't have to use the Java <code>native2ascii</code> tool.</p><h2 id="Localization-LocalizedComponentTemplates">Localized Component Templates</h2><p>The same lookup mechanism applies to component templates. Tapestry will search for a localized version of each component template
and use the closest match. Thus you could have <code>MyPage_fr.html</code> for French users, and <code>MyPage.html</code> for all other users.</p><h2 id="Localization-AccessingLocalizedMessages">Accessing Localized Messages</h2><p>The above discusses what files to create and where to store them, but doesn't address how to make use of that information.</p><p>Messages can be accessed in one of two ways:</p><ul><li>Using the "message:" <a href="localization.html">binding expression</a> in a component template</li><li>By injecting the component's Messages object<br clear="none"> In the first case, you may use the message: binding prefix with component parameters, or with template expansions:</li></ul><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"><t:layout title="message:page-title">
${message:greeting}, ${user.name}!
. . .
</t:layout>
-</plain-text-body><p>Here, the <code>page-title</code> message is extracted from the catalog and passed to the Border component's title parameter.</p><p>In addition, the <code>greeting</code> message is extracted and written into the response as part of the template.</p><p>As usual, "prop:" is the default binding prefix, thus <code>user.name</code> is a property path, not a message key.</p><p>You would extend this with a set of properties files:</p><parameter ac:name="">java</parameter><plain-text-body>page-title=Your Account
+</pre>
+</div></div><p>Here, the <code>page-title</code> message is extracted from the catalog and passed to the Border component's title parameter.</p><p>In addition, the <code>greeting</code> message is extracted and written into the response as part of the template.</p><p>As usual, "prop:" is the default binding prefix, thus <code><a class="external-link" href="http://user.name" rel="nofollow">user.name</a></code> is a property path, not a message key.</p><p>You would extend this with a set of properties files:</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;">page-title=Your Account
greeting=Welcome back
-</plain-text-body><p>Or, perhaps, a French version:</p><parameter ac:name="">java</parameter><plain-text-body>page-title=Votre Compte
+</pre>
+</div></div><p>Or, perhaps, a French version:</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;">page-title=Votre Compte
greeting=Bienvenue en arriere
-</plain-text-body><p>Programatically, you may inject your component message catalog into your class, as an instance of the Messages interface:</p><parameter ac:name="">java</parameter><plain-text-body> @Inject
+</pre>
+</div></div><p>Programatically, you may inject your component message catalog into your class, as an instance of the Messages interface:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Inject
private Messages messages;
-</plain-text-body><p>You could then <code>get()</code> messages, or <code>format()</code> them:</p><parameter ac:name="">java</parameter><plain-text-body> public String getCartSummary()
+</pre>
+</div></div><p>You could then <code>get()</code> messages, or <code>format()</code> them:</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 String getCartSummary()
{
if (items.isEmpty())
return messages.get("no-items");
return messages.format("item-summary", _items.size());
}
-</plain-text-body><p>The format() option works using a <code>java.util.Formatter</code>, with all the printf-style loveliness you've come to expect:</p><parameter ac:name="">java</parameter><plain-text-body>no-items=Your shopping cart is empty.
+</pre>
+</div></div><p>The format() option works using a <code>java.util.Formatter</code>, with all the printf-style loveliness you've come to expect:</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;">no-items=Your shopping cart is empty.
item-summary=You have %d items in your cart.
-</plain-text-body><p>As easy as conditionals are to use inside a Tapestry template, sometimes it's even easier to do it in Java code.</p><h2 id="Localization-MissingKeys">Missing Keys</h2><p>If you reference a key that is not in the message catalog, Tapestry does not throw an exception (because that would make initially developing an application very frustrating). When a key can not be located, a "placeholder" message is generated, such as "[[missing key: key-not-found]]".</p><h2 id="Localization-Reloading">Reloading</h2><p>If you change a property file in a message catalog, you'll see the change immediately, just as with component classes and component templates (provided you're not running in <a href="configuration.html">production mode</a>).</p><h2 id="Localization-AssetLocalization">Asset Localization</h2><p>When <a href="injection.html">injecting assets</a>, the injected asset will be localized as well. A search for the closest match for the active locale is made, and the fin
al Asset will reflect that.</p><h2 id="Localization-LocaleSelection">Locale Selection</h2><p>The locale for each request is determined from the HTTP request headers. The request locale reflects the environment of the web browser and possibly even the keyboard selection of the user on the client. It can be highly specific, for example, identifying British English (as en_GB) vs. American English (en).</p><p>Tapestry "narrows" the raw request locale, as specified in the request, to a known quantity. It uses the <a href="configuration.html">configuration symbol</a> <code>tapestry.supported-locales</code> to choose the effective locale for each request. This value is a comma-separated list of locale names. Tapestry searches the list for the best match for the request locale; for example, a request locale of "fr_FR" would match "fr" but not "de". If no match is found, then the first locale name in the list is used as the effective locale (that is, the first locale is used as the default
for non-matching requests). Thus a site that primarily caters to French speakers would want to list "fr" as the first locale in the list.</p><h2 id="Localization-ChangingtheLocale">Changing the Locale</h2><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PersistentLocale.html">PersistentLocale service</a> can be used to programmatically override the locale. Note: You should be careful to only set the persistent locale to a supported locale.</p><parameter ac:name="">java</parameter><parameter ac:name="title">Toggle between English and German</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>As easy as conditionals are to use inside a Tapestry template, sometimes it's even easier to do it in Java code.</p><h2 id="Localization-MissingKeys">Missing Keys</h2><p>If you reference a key that is not in the message catalog, Tapestry does not throw an exception (because that would make initially developing an application very frustrating). When a key can not be located, a "placeholder" message is generated, such as "[[missing key: key-not-found]]".</p><h2 id="Localization-Reloading">Reloading</h2><p>If you change a property file in a message catalog, you'll see the change immediately, just as with component classes and component templates (provided you're not running in <a href="localization.html">production mode</a>).</p><h2 id="Localization-AssetLocalization">Asset Localization</h2><p>When <a href="localization.html">injecting assets</a>, the injected asset will be localized as well. A search for the closest match for the active locale is made, and the final A
sset will reflect that.</p><h2 id="Localization-LocaleSelection">Locale Selection</h2><p>The locale for each request is determined from the HTTP request headers. The request locale reflects the environment of the web browser and possibly even the keyboard selection of the user on the client. It can be highly specific, for example, identifying British English (as en_GB) vs. American English (en).</p><p>Tapestry "narrows" the raw request locale, as specified in the request, to a known quantity. It uses the <a href="localization.html">configuration symbol</a> <code>tapestry.supported-locales</code> to choose the effective locale for each request. This value is a comma-separated list of locale names. Tapestry searches the list for the best match for the request locale; for example, a request locale of "fr_FR" would match "fr" but not "de". If no match is found, then the first locale name in the list is used as the effective locale (that is, the first locale is used as the default for n
on-matching requests). Thus a site that primarily caters to French speakers would want to list "fr" as the first locale in the list.</p><h2 id="Localization-ChangingtheLocale">Changing the Locale</h2><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PersistentLocale.html">PersistentLocale service</a> can be used to programmatically override the locale. Note: You should be careful to only set the persistent locale to a supported locale.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Toggle between English and German</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Inject
private PersistentLocale persistentLocale;
void onActionFromLocaleToggle() {
@@ -106,8 +178,9 @@ void onActionFromLocaleToggle() {
public String getDisplayLanguage() {
return persistentLocale.get().getDisplayLanguage();
}
-</plain-text-body><p>Once a persistent locale is set, you will see the locale name as the first virtual folder in page render and component event requests URLs. In this way, a persistent locale will, in fact, persist from request to request, or in a user's bookmarks.</p><p>You will see the new locale take effect on the next request. If it is changed in a component event request (which is typical), the new locale will be used in the subsequent page render request.</p><p>Note that the locale for a page is fixed (it can't change once the page instance is created). In addition, a page may only be attached to a request once. In other words, if code in your page changes the persistent locale, you won't see a change to the page's locale (or localized messages) <em>in that request</em>.</p><h2 id="Localization-Built-inLocales">Built-in Locales</h2><p>While your application can support any locale (and thus any language) that you want, Tapestry provides only a limited set of translations for
its own built-in messages. As of Tapestry 5.3, the following locales have translations provided:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>en (English)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>el (Greek)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>it (Italian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>pl (Polish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span><span>sv (Swedish)</span></span></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>bg (Bulgarian)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>es (Spanish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>ja (Japanese)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>pt (Portuguese)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>
<span>vi (Vietnamese)</span></span></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>cs (Czech)<sup>1</sup></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>fi (Finnish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>mk (Macedonian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>ru (Russian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>zh (Chinese)</span></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><span>da (Danish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>fr (French)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>nl (Dutch)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd">sl (Slovenian)<sup>2</sup></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><span>de (German)</span></p></td><td colspa
n="1" rowspan="1" class="confluenceTd"><p><span>hr (Croatian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>no (Norwegian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>sr (Serbian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr></tbody></table></div><p><sup>1 </sup><span style="line-height: 1.4285715;">as of Tapestry 5.3.8</span></p><p><span style="line-height: 1.4285715;"> </span><sup>2 </sup><span>as of Tapestry 5.4</span></p><h3 id="Localization-ProvidingtranslationsforTapestrybuilt-inmessages">Providing translations for Tapestry built-in messages</h3><p>Fortunately, Tapestry uses all the same mechanisms for its own locale support as it provides for your application. So, to support other locales, just translate the built-in message catalog (property) files yourself:</p><p> </p><parameter ac:name="atlassian-macro-output-type">BLOCK</parameter><plain-text-body><style typ
e="text/css">table.sectionMacro { width: auto; }</style>
-</plain-text-body><parameter ac:name="width">auto</parameter><rich-text-body><rich-text-body><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Tapestry 5.4 and later</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=tapestry-core/src/main/resources/org/apache/tapestry5">core.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=tapestry-kaptcha/src/main/resources/org/apache/tapestry5/kaptcha">tapestry-kaptcha.properties</a></p></td></tr></tbody></table></div></rich-text-body><rich-text-body><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Tapestry 5.3.x</p></th></tr><tr><td colspan="1" rowspan="1" class="con
fluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/BeanEditForm.properties?view=markup">BeanEditForm.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/DateField.properties?view=markup">DateField.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/Errors.properties?view=markup">Errors.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry
-core/src/main/resources/org/apache/tapestry5/corelib/components/GridColumns.properties?view=markup">GridColumns.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/GridPager.properties?view=markup">GridPager.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/Palette.properties?view=markup">Palette.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/internal/ValidationMessages.properties?view=markup">ValidationMessage
s.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-kaptcha/src/main/resources/org/apache/tapestry5/kaptcha/tapestry-kaptcha.properties?view=markup">tapestry-kaptcha.properties</a></p></td></tr></tbody></table></div></rich-text-body></rich-text-body><p>To have Tapestry use these new files, just put them in the corresponding package-named directory within your own app (for example, src/main/resources/org/apache/tapestry5/core.properties).</p><p>Finally, please open a new feature request <a class="external-link" href="https://issues.apache.org/jira/browse/TAP5">here</a> and attach the translated files so that they can be included in the next release of Tapestry.</p><rich-text-body><p>Please note that a patch is always preferred over an archive of properties files.</p></rich-text-body></div>
+</pre>
+</div></div><p>Once a persistent locale is set, you will see the locale name as the first virtual folder in page render and component event requests URLs. In this way, a persistent locale will, in fact, persist from request to request, or in a user's bookmarks.</p><p>You will see the new locale take effect on the next request. If it is changed in a component event request (which is typical), the new locale will be used in the subsequent page render request.</p><p>Note that the locale for a page is fixed (it can't change once the page instance is created). In addition, a page may only be attached to a request once. In other words, if code in your page changes the persistent locale, you won't see a change to the page's locale (or localized messages) <em>in that request</em>.</p><h2 id="Localization-Built-inLocales">Built-in Locales</h2><p>While your application can support any locale (and thus any language) that you want, Tapestry provides only a limited set of translations for its ow
n built-in messages. As of Tapestry 5.3, the following locales have translations provided:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>en (English)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>el (Greek)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>it (Italian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>pl (Polish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span><span>sv (Swedish)</span></span></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>bg (Bulgarian)</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>es (Spanish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>ja (Japanese)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>pt (Portuguese)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span><span>
vi (Vietnamese)</span></span></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>cs (Czech)<sup>1</sup></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>fi (Finnish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>mk (Macedonian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>ru (Russian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>zh (Chinese)</span></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><span>da (Danish)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>fr (French)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>nl (Dutch)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd">sl (Slovenian)<sup>2</sup></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><span>de (German)</span></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><span>hr (Croatian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>no (Norwegian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><span>sr (Serbian)</span></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> </p></td></tr></tbody></table></div><p><sup>1 </sup><span>as of Tapestry 5.3.8</span></p><p><span> </span><sup>2 </sup><span>as of Tapestry 5.4</span></p><h3 id="Localization-ProvidingtranslationsforTapestrybuilt-inmessages">Providing translations for Tapestry built-in messages</h3><p>Fortunately, Tapestry uses all the same mechanisms for its own locale support as it provides for your application. So, to support other locales, just translate the built-in message catalog (property) files yourself:</p><p> </p><style type="text/css">table.sectionMacro { width: auto; }</style>
+<div class="sectionColumnWrapper"><div class="sectionMacro"><div class="sectionMacroRow"><div class="columnMacro"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Tapestry 5.4 and later</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=tapestry-core/src/main/resources/org/apache/tapestry5">core.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=tree;f=tapestry-kaptcha/src/main/resources/org/apache/tapestry5/kaptcha">tapestry-kaptcha.properties</a></p></td></tr></tbody></table></div></div><div class="columnMacro"><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Tapestry 5.3.x</p></th></tr><tr><td colspan="1" row
span="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/BeanEditForm.properties?view=markup">BeanEditForm.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/DateField.properties?view=markup">DateField.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/Errors.properties?view=markup">Errors.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/br
anches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/GridColumns.properties?view=markup">GridColumns.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/GridPager.properties?view=markup">GridPager.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/corelib/components/Palette.properties?view=markup">Palette.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-core/src/main/resources/org/apache/tapestry5/internal/ValidationMessages.properties?view=markup
">ValidationMessages.properties</a></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://svn.apache.org/viewvc/tapestry/tapestry5/branches/5.3/tapestry-kaptcha/src/main/resources/org/apache/tapestry5/kaptcha/tapestry-kaptcha.properties?view=markup">tapestry-kaptcha.properties</a></p></td></tr></tbody></table></div></div></div></div></div><p>To have Tapestry use these new files, just put them in the corresponding package-named directory within your own app (for example, src/main/resources/org/apache/tapestry5/core.properties).</p><p>Finally, please open a new feature request <a class="external-link" href="https://issues.apache.org/jira/browse/TAP5">here</a> and attach the translated files so that they can be included in the next release of Tapestry.</p><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span
><div class="confluence-information-macro-body"><p>Please note that a patch is always preferred over an archive of properties files.</p></div></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/logging.html
==============================================================================
--- websites/production/tapestry/content/logging.html (original)
+++ websites/production/tapestry/content/logging.html Sat Feb 3 16:21:22 2018
@@ -44,13 +44,26 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/">Security</a></li><li><a class="external-link" href="http://www.apache.org/">Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></div></div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0">License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/">Security</a></li><li><a class="external-link" href="http://www.apache.org/">Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html">Thanks</a></li></ul></div>
+
+</div>
<div id="top">
- <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html">
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png" data-image-src="http://tapestry.apache.org/images/tapestry_small.png"></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Logging</h1></div></div>
+ <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
+<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html">
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form>
+
+</div>
+
+
+<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png" data-image-src="http://tapestry.apache.org/images/tapestry_small.png"></span></a></p></div>
+
+
+<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Logging</h1></div>
+
+</div>
<div class="clearer"></div>
</div>
@@ -62,19 +75,40 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Logging</strong> involves the automatic recording of progress as an application runs. Tapestry makes extensive use of <a class="external-link" href="http://www.slf4j.org/" rel="nofollow">SLF4J</a> to log details about the creation and operation of your page and component classes.</p><div class="aui-label" style="float:right" title="Related Articles"><h3>Related Articles</h3><ul class="content-by-label"><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span>
- </div>
- <div class="details">
- <a href="logging-in-tapestry.html">Logging in Tapestry</a>
- </div> </li><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span>
- </div>
- <div class="details">
- <a href="logging.html">Logging</a>
- </div> </li></ul></div><p>The default configuration for logging uses <a class="external-link" href="http://logging.apache.org/log4j/">Log4J</a> as the logging toolkit, though <a href="logging-in-tapestry.html">this can be changed</a>.</p><h1 id="Logging-ClasstoLogger">Class to Logger</h1><p>The logger name for a page or component matches the fully qualified class name. You can configure this in log4j.properties:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+ <div id="ConfluenceContent"><p><strong>Logging</strong> involves the automatic recording of progress as an application runs. Tapestry makes extensive use of <a class="external-link" href="http://www.slf4j.org/" rel="nofollow">SLF4J</a> to log details about the creation and operation of your page and component classes.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="logging-in-tapestry.html">Logging in Tapestry</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="logging.html">Logging</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>The default configuration for logging uses <a class="external-link" href="http://logging.apache.org/log4j/">Log4J</a> as the logging toolkit, though <a href="logging.html">this can be changed</a>.</p><h1 id="Logging-ClasstoLogger">Class to Logger</h1><p>The logger name for a page or component matches the fully qualified class name. You can configure this in log4j.properties:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>log4j.category.org.apache.tapestry5.integration.app1.pages.MerryChristmas=trace
</pre>
</div></div><h1 id="Logging-InjectingLoggers">Injecting Loggers</h1><p>You may mark a field of type <a class="external-link" href="http://www.slf4j.org/api/org/slf4j/Logger.html" rel="nofollow">Logger</a> with the @Inject annotation. The proper Logger for your page or component will be injected.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">