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/16 03:21:19 UTC
svn commit: r1025456 [3/3] - in /websites/production/tapestry/content:
assets.html cache/main.pageCache class-reloading.html
component-classes.html component-reference.html component-templates.html
project-layout.html
Modified: websites/production/tapestry/content/component-templates.html
==============================================================================
--- websites/production/tapestry/content/component-templates.html (original)
+++ websites/production/tapestry/content/component-templates.html Fri Feb 16 03:21:19 2018
@@ -176,7 +176,7 @@
<h1>Bonjour from HelloWorld component.</h1>
</html>
</pre>
-</div></div><div class="sectionMacro"><div class="sectionMacroRow"> </div></div><p>We'll cover the specific content of templates shortly, but first a few details about connecting a component to its template.</p><h2 id="ComponentTemplates-TemplateLocation">Template Location</h2><p>A component template shares the same name as its corresponding class file, but with a ".tml" ending (i.e., <strong>T</strong>apestry <strong>M</strong>arkup <strong>L</strong>anguage), and is stored in the same package as the corresponding component class.</p><p>Under a typical Maven directory structure, the Java class and template files for a <em>component</em> might be:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Java class:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/java/org/example/myapp/components/MyComponent.java</code></p></td></tr><tr><td colspan="1" rowspan="1" class="c
onfluenceTd"><p><strong>Template:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/resources/org/example/myapp/components/MyComponent.tml</code></p></td></tr></tbody></table></div><p>Likewise, the Java class and template files for a <em>page</em> might be:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Java class:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/java/org/example/myapp/pages/MyPage.java</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Template:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/resources/org/example/myapp/pages/MyPage.tml</code></p></td></tr></tbody></table></div><p>The template and the compiled class will be packaged together in the WEB-INF/classes folder of the application WAR.</p><p>For <em>pages</em> (but not other components), a
second location will be searched: in the web application context. The location is based on the logical name of the page, in the previous example, the template would be <code>MyPage.tml</code> in the root folder of the web application.</p><p>A template on the classpath takes precedence over a file in the web application context.</p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Allowing pages to store their template in the web context is a feature that may go away at some point. It was included as a way for HTML designers to edit template directly and live preview the template directly, without executing the Tapestry application. This comes with a large number of limitations and leads to a false sense of security that a template that previews correctly will render properly (this is not always the case).</p>
</div></div><h2 id="ComponentTemplates-TemplateLocalization">Template Localization</h2><p>Main Article: <a href="localization.html">Localization</a></p><p>Templates are handled in much the same way as individual files of a component's message catalog: the effective locale is inserted into the name of the file. Thus a German users will see the content generated from <code>MyPage_de.tml</code> and French users will see content generated from <code>MyPage_fr.tml</code>. When no specific localization is available, the default location (<code>MyPage.tml</code>) is used.</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>It is necessary to <a href="component-templates.html">enable support for a locale</a> before Tapestry will attempt to localize to that locale. This requires configuration in your application
module (usually AppModule.java); if you are using the Tapestry Quickstart archetype, only locale "en" will be enabled by default.</p></div></div><p><span class="confluence-anchor-link" id="ComponentTemplates-doctypes"></span></p><h2 id="ComponentTemplates-TemplateDoctypes">Template Doctypes</h2><p>As mentioned above, component templates are well-formed XML documents. This means that if you want to use any <a class="external-link" href="http://www.w3.org/TR/html401/sgml/entities.html" rel="nofollow">Named HTML entities</a> (such as &amp; &lt; &gt; &copy;), you must use an <a class="external-link" href="http://www.w3.org/QA/2002/04/valid-dtd-list.html" rel="nofollow">HTML or XHTML doctype</a> in your template <em>(starting in 5.3, this is more-or-less automatic, see notes below)</em>. If you choose to use (X)HTML doctypes in your templates, they will be passed on to the client in the resultant (X)HTML. Note that if your pages are composed of multiple components, eac
h with a template, and each template contains a doctype declaration, only the first doctype encountered by the template parser will be passed on to the client.</p><p>It should also be noted that even though <strong>X</strong>HTML DTDs are valid XML DTDs, HTML DTDs aren't. This means that HTML doctypes cannot be used by XML parsers. Tapestry works around this limitation internally by using XHTML DTDs to parse templates that use HTML DTDs. This internal mapping is possible because XHTML 1.0 is nothing more than "a reformulation of the three HTML 4 document types as applications of XML 1.0," <a class="external-link" href="http://www.w3.org/TR/xhtml1/#xhtml" rel="nofollow">as per the W3C</a>. Don't worry though – the original HTML 4 doctype will still be emitted to the client!</p><p>The following are the most common (X)HTML doctypes:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><div class="sectionMacro"><div class="sectionMacroRow"> </div></div><p>We'll cover the specific content of templates shortly, but first a few details about connecting a component to its template.</p><h2 id="ComponentTemplates-TemplateLocation">Template Location</h2><p>A component template shares the same name as its corresponding class file, but with a ".tml" ending (i.e., <strong>T</strong>apestry <strong>M</strong>arkup <strong>L</strong>anguage), and is stored in the same package as the corresponding component class.</p><p>Under a typical Maven directory structure, the Java class and template files for a <em>component</em> might be:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Java class:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/java/org/example/myapp/components/MyComponent.java</code></p></td></tr><tr><td colspan="1" rowspan="1" class="c
onfluenceTd"><p><strong>Template:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/resources/org/example/myapp/components/MyComponent.tml</code></p></td></tr></tbody></table></div><p>Likewise, the Java class and template files for a <em>page</em> might be:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Java class:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/java/org/example/myapp/pages/MyPage.java</code></p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong>Template:</strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p><code>src/main/resources/org/example/myapp/pages/MyPage.tml</code></p></td></tr></tbody></table></div><p>The template and the compiled class will be packaged together in the WEB-INF/classes folder of the application WAR.</p><p>For <em>pages</em> (but not other components), a
second location will be searched: in the web application context. The location is based on the logical name of the page, in the previous example, the template would be <code>MyPage.tml</code> in the root folder of the web application.</p><p>A template on the classpath takes precedence over a file in the web application context.</p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Allowing pages to store their template in the web context is a feature that may go away at some point. It was included as a way for HTML designers to edit template directly and live preview the template directly, without executing the Tapestry application. This comes with a large number of limitations and leads to a false sense of security that a template that previews correctly will render properly (this is not always the case).</p>
</div></div><h2 id="ComponentTemplates-TemplateLocalization">Template Localization</h2><p>Main Article: <a href="localization.html">Localization</a></p><p>Templates are handled in much the same way as individual files of a component's message catalog: the effective locale is inserted into the name of the file. Thus a German users will see the content generated from <code>MyPage_de.tml</code> and French users will see content generated from <code>MyPage_fr.tml</code>. When no specific localization is available, the default location (<code>MyPage.tml</code>) is used.</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>It is necessary to <a href="configuration.html">enable support for a locale</a></p><p>before Tapestry will attempt to localize to that locale. This requires configuration in your application
module (usually AppModule.java); if you are using the Tapestry Quickstart archetype, only locale "en" will be enabled by default.</p></div></div><p><span class="confluence-anchor-link" id="ComponentTemplates-doctypes"></span></p><h2 id="ComponentTemplates-TemplateDoctypes">Template Doctypes</h2><p>As mentioned above, component templates are well-formed XML documents. This means that if you want to use any <a class="external-link" href="http://www.w3.org/TR/html401/sgml/entities.html" rel="nofollow">Named HTML entities</a> (such as &amp; &lt; &gt; &copy;), you must use an <a class="external-link" href="http://www.w3.org/QA/2002/04/valid-dtd-list.html" rel="nofollow">HTML or XHTML doctype</a> in your template <em>(starting in 5.3, this is more-or-less automatic, see notes below)</em>. If you choose to use (X)HTML doctypes in your templates, they will be passed on to the client in the resultant (X)HTML. Note that if your pages are composed of multiple components, eac
h with a template, and each template contains a doctype declaration, only the first doctype encountered by the template parser will be passed on to the client.</p><p>It should also be noted that even though <strong>X</strong>HTML DTDs are valid XML DTDs, HTML DTDs aren't. This means that HTML doctypes cannot be used by XML parsers. Tapestry works around this limitation internally by using XHTML DTDs to parse templates that use HTML DTDs. This internal mapping is possible because XHTML 1.0 is nothing more than "a reformulation of the three HTML 4 document types as applications of XML 1.0," <a class="external-link" href="http://www.w3.org/TR/xhtml1/#xhtml" rel="nofollow">as per the W3C</a>. Don't worry though – the original HTML 4 doctype will still be emitted to the client!</p><p>The following are the most common (X)HTML doctypes:</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;"><!DOCTYPE html>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
@@ -197,7 +197,7 @@
<div class="aui-message aui-message-info">
Added in 5.3
- Tapestry 5.3 introduced two significant improvements to template Doctypes. A template without a is parsed as if it had the HTML Doctype ({{}}). In fact, Tapestry creates an in-memory copy of the template that includes the doctype. A template with the HTML Doctype ({{}}) is parsed _as if_ it had the XHTML transitional Doctype. In fact, Tapestry creates an in-memory copy of the template that replaces the line. This applies as well to a template without any Doctype, in which case the XHTML transitional Doctype is inserted at the top. In either case, this means you can use arbitrary HTML entities, such as {{&copy;}} or {{&nbsp;}} without seeing the XML parsing errors that would occur in earlier releases.
+ Tapestry 5.3 introduced two significant improvements to template Doctypes. A template without a is parsed as if it had the HTML Doctype ({{}}). In fact, Tapestry creates an in-memory copy of the template that includes the doctype. A template with the HTML Doctype ({{}}) is parsed <em>as if</em> it had the XHTML transitional Doctype. In fact, Tapestry creates an in-memory copy of the template that replaces the line. This applies as well to a template without any Doctype, in which case the XHTML transitional Doctype is inserted at the top. In either case, this means you can use arbitrary HTML entities, such as {{&copy;}} or {{&nbsp;}} without seeing the XML parsing errors that would occur in earlier releases.
</div><h2 id="ComponentTemplates-TheTapestryNamespace">The Tapestry Namespace</h2><p>Component templates should include the Tapestry namespace, defining it in the root element of the template.</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_4.xsd">
<head>
@@ -208,7 +208,7 @@ Added in 5.3
</body>
</html>
</pre>
-</div></div><p>This defines the namespace using the standard prefix, "t:". The examples on this page all assume the use of the standard prefix.</p><p>For backwards compatibility, you may continue to use the old namespace URIs: <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">http://tapestry.apache.org/schema/tapestry_5_0_0.xsd</a> or <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a> or  <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_3.xsd">http://tapestry.apache.org/schema/tapestry_5_3.xsd</a></p><pre> </pre><p> However, the following elements added, as part of Tapestry 5.1, will not work with the 5_0_0.xsd:</p><ul><li>The <t:remove> Element</li><li><t:content></li><li><t:extension-point></li><li><t:extend></li><li><t:replace></li></ul><p>The 5_3.xsd fixes some minor bugs in t
he 5_1_0.xsd, but is functionally equivalent; 5_3.xsd and 5_4.xsd are identical.</p><h2 id="ComponentTemplates-TapestryElements">Tapestry Elements</h2><p>Tapestry elements are elements defined using the Tapestry namespace prefix (usually "t:").</p><p>All other elements in your templates should be in the default namespace, with no prefix (with the possible exception of any Library Namespaces (described <a href="component-templates.html">below</a>).</p><p>There are a certain number of Tapestry elements, listed below, that act as template directives; beyond that, any element in the Tapestry namespace will be a Tapestry component.</p><h3 id="ComponentTemplates-The<t:body>Element">The <t:body> Element</h3><p>In many cases, a component is designed to have its template integrate with, or "wrap around", the containing component.</p><p>The <t:body> element is used to identify where, within a component's template, its body (from the container's template) is to be rendered.<
/p><p>Components have control over if, and even how often, their body is rendered.</p><p>The following example is a <a href="component-templates.html">Layout component</a>, which adds basic HTML elements <em>around</em> the page-specific content:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This defines the namespace using the standard prefix, "t:". The examples on this page all assume the use of the standard prefix.</p><p>For backwards compatibility, you may continue to use the old namespace URIs: <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">http://tapestry.apache.org/schema/tapestry_5_0_0.xsd</a> or <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a> or  <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_3.xsd">http://tapestry.apache.org/schema/tapestry_5_3.xsd</a></p><pre> </pre><p> However, the following elements added, as part of Tapestry 5.1, will not work with the 5_0_0.xsd:</p><ul><li>The <t:remove> Element</li><li><t:content></li><li><t:extension-point></li><li><t:extend></li><li><t:replace></li></ul><p>The 5_3.xsd fixes some minor bugs in t
he 5_1_0.xsd, but is functionally equivalent; 5_3.xsd and 5_4.xsd are identical.</p><h2 id="ComponentTemplates-TapestryElements">Tapestry Elements</h2><p>Tapestry elements are elements defined using the Tapestry namespace prefix (usually "t:").</p><p>All other elements in your templates should be in the default namespace, with no prefix (with the possible exception of any Library Namespaces (described <a href="component-templates.html">below</a>).</p><p>There are a certain number of Tapestry elements, listed below, that act as template directives; beyond that, any element in the Tapestry namespace will be a Tapestry component.</p><h3 id="ComponentTemplates-The<t:body>Element">The <t:body> Element</h3><p>In many cases, a component is designed to have its template integrate with, or "wrap around", the containing component.</p><p>The <t:body> element is used to identify where, within a component's template, its body (from the container's template) is to be rendered.<
/p><p>Components have control over if, and even how often, their body is rendered.</p><p>The following example is a <a href="layout-component.html">Layout component</a>, which adds basic HTML elements <em>around</em> the page-specific content:</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">
<head>
<title>My Tapestry Application</title>
@@ -241,7 +241,7 @@ Added in 5.3
<td>${value}</td>
</t:container>
</pre>
-</div></div><p>This component only makes sense when used inside a <tr> element of its container's template.</p><p>Without the <t:container> element, there would be no way to create a valid XML document as the template, because XML documents must always have a single root element.</p><p></p><h3 id="ComponentTemplates-The<t:block>Element">The <t:block> Element</h3><p>A <t:block> is a container of a portion of the component template. A block does not normally render; any component or contents you put inside a block will not ordinarily be rendered. However, by injecting the block you have precise control over when and if the content renders.</p><p>A block may be anonymous, or it may have an id (specified with the id attribute). Only blocks with an id may be <a href="component-templates.html">injected</a> into the component.</p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-er
ror confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>A <t:block> must be in the Tapestry namespace, but the id attribute should not be. This is different from components in the template, where the t:id attribute that defines the component id <em>must</em> be in the Tapestry namespace.</p></div></div><p>Ids must be valid Java identifiers: start with a letter, and contain only letters, numbers and underscores.</p><h3 id="ComponentTemplates-The<t:parameter>Element">The <t:parameter> Element</h3><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>This element was deprecated starting in Tapestry 5.1 and <em>removed</em> in 5.3. Use <em><a href="component-templates.html">parameter namespaces</a></em> (below) instead.</p></div></div><p>A <parameter> el
ement is a special kind of block. It is placed inside the body of an embedded component. The block defined by the <parameter> is passed to the component. <parameter> includes a mandatory name attribute to identify which parameter of the component to bind.</p><h3 id="ComponentTemplates-The<t:content>Element">The <t:content> Element</h3><p><t:content> marks a portion of the template as the actual template <em>content</em>; any markup outside the <t:content> element is ignored. This is useful for eliminating portions of the template that exist to support WYSIWYG preview of the template.</p><p><t:content> elements may not nest.</p><p>Support for the <t:content> element was adding in Tapestry release 5.1. You must use the <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">http://tapestry.apache.org/schema/tapestry_5_1_0.xsd</a> or <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5
_3.xsd">http://tapestry.apache.org/schema/tapestry_5_3.xsd</a> namespace URI for content to be recognized (otherwise you will see an error about a missing "content" component).</p><h3 id="ComponentTemplates-<t:remove>"><t:remove></h3><p>Marks a portion of the template for removal; it is as if the remove element and everything inside it simply was not part of the template. This is used as a kind of server-side only comment (normal HTML/XML comments are included in a page render response), or to temporarily eliminate a portion of the template. As far as Tapestry is concerned, the contents of the <remove> element do not exist (including validating consistency between components defined or injected in the Java class and the template).</p><p>Support for the <t:remove> element was added in Tapestry release 5.1. You must use the <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">http://tapestry.apache.org/schema/tapestry_5_1_0.xsd<
/a> or <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_3.xsd">http://tapestry.apache.org/schema/tapestry_5_3.xsd</a> namespace URI for remove to be recognized (otherwise you will see an error about a missing "remove" component).</p><p><span class="confluence-anchor-link" id="ComponentTemplates-Expansions"></span></p><h2 id="ComponentTemplates-Expansions">Expansions</h2><p>Another option when rendering output is the use of <em>expansions</em>. Expansions are special strings that may be embedded in template bodies, and borrow some syntax from the <a class="external-link" href="http://ant.apache.org">Ant</a> build tool.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This component only makes sense when used inside a <tr> element of its container's template.</p><p>Without the <t:container> element, there would be no way to create a valid XML document as the template, because XML documents must always have a single root element.</p><p></p><h3 id="ComponentTemplates-The<t:block>Element">The <t:block> Element</h3><p>A <t:block> is a container of a portion of the component template. A block does not normally render; any component or contents you put inside a block will not ordinarily be rendered. However, by injecting the block you have precise control over when and if the content renders.</p><p>A block may be anonymous, or it may have an id (specified with the id attribute). Only blocks with an id may be <a href="component-templates.html">injected</a> into the component.</p><div class="confluence-information-macro confluence-information-macro-warning"><span class="aui-icon aui-icon-small aui-iconfont-er
ror confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>A <t:block> must be in the Tapestry namespace, but the id attribute should not be. This is different from components in the template, where the t:id attribute that defines the component id <em>must</em> be in the Tapestry namespace.</p></div></div><p>Ids must be valid Java identifiers: start with a letter, and contain only letters, numbers and underscores.</p><h3 id="ComponentTemplates-The<t:parameter>Element">The <t:parameter> Element</h3><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>This element was deprecated starting in Tapestry 5.1 and <em>removed</em> in 5.3. Use <em><a href="component-templates.html">parameter namespaces</a></em> (below) instead.</p></div></div><p>A <parameter> el
ement is a special kind of block. It is placed inside the body of an embedded component. The block defined by the <parameter> is passed to the component. <parameter> includes a mandatory name attribute to identify which parameter of the component to bind.</p><h3 id="ComponentTemplates-The<t:content>Element">The <t:content> Element</h3><p><t:content> marks a portion of the template as the actual template <em>content</em>; any markup outside the <t:content> element is ignored. This is useful for eliminating portions of the template that exist to support WYSIWYG preview of the template.</p><p><t:content> elements may not nest.</p><p>Support for the <t:content> element was adding in Tapestry release 5.1. You must use the <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_5.xsd">http://tapestry.apache.org/schema/tapestry_5_4.xsd</a> or (or ...5_3 or ...5_1_0.xsd) namespace URI for content to be recognized (otherwis
e you will see an error about a missing "content" component).</p><h3 id="ComponentTemplates-<t:remove>"><t:remove></h3><p>Marks a portion of the template for removal; it is as if the remove element and everything inside it simply was not part of the template. This is used as a kind of server-side only comment (normal HTML/XML comments are included in a page render response), or to temporarily eliminate a portion of the template. As far as Tapestry is concerned, the contents of the <remove> element do not exist (including validating consistency between components defined or injected in the Java class and the template).</p><p>Support for the <t:remove> element was added in Tapestry release 5.1. You must use the <a class="external-link" href="http://tapestry.apache.org/schema/tapestry_5_5.xsd">http://tapestry.apache.org/schema/tapestry_5_4.xsd</a> or (or ...5_3 or ...5_1_0.xsd) namespace URI for remove to be recognized (otherwise you will see an error about a m
issing "remove" component).</p><p><span class="confluence-anchor-link" id="ComponentTemplates-Expansions"></span></p><h2 id="ComponentTemplates-Expansions">Expansions</h2><p>Another option when rendering output is the use of <em>expansions</em>. Expansions are special strings that may be embedded in template bodies, and borrow some syntax from the <a class="external-link" href="http://ant.apache.org">Ant</a> build tool.</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;"> Welcome, ${userId}!
</pre>
</div></div><p>Here, <code>${userId</code>} is the expansion. In this example, the userId property of the component is extracted, converted to a string, and streamed into the output.</p><p>Expansions are allowed inside text, and inside attributes of ordinary elements, and component elements. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
@@ -283,7 +283,7 @@ Added in 5.3
</span>
</p>
</pre>
-</div></div><p>The t:type attribute above marks the span element as a component of type Count. When rendered, the span element will be <em>replaced</em> by the output of the Count component.</p><p>The id, type and mixins attributes must be placed in the Tapestry namespace (almost always as t:id, t:type, and t:mixins). Any additional attributes may be in either the Tapestry namespace or the default namespace. Placing an attribute in the Tapestry namespace is useful when the attribute is not defined for the element being instrumented.</p><p>An invisibly-instrumented component must still have a type, identified in one of two ways:</p><ul><li>via the t:type attribute in the containing template, as in the above example, or</li><li>within the containing component's Java class using the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation (and using the t:id attribute on the element in the templ
ate). The Component annotation is attached to a field; the type of the component is determined by either the type of the field or the type attribute of the Component annotation.</li></ul><p>In <em>most</em> cases, it is merely an aesthetic choice whether to use invisible instrumentation in your templates. However, in a very few cases the behavior of the component is influenced by your choice. For example, when your template includes the Loop component using the invisible instrumentation approach, the original tag (and its informal parameters) will render repeatedly around the body of the component. Thus, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>The t:type attribute above marks the span element as a component of type Count. When rendered, the span element will be <em>replaced</em> by the output of the Count component.</p><p>The id, type and mixins attributes must be placed in the Tapestry namespace (almost always as t:id, t:type, and t:mixins). Any additional attributes may be in either the Tapestry namespace or the default namespace. Placing an attribute in the Tapestry namespace is useful when the attribute is not defined for the element being instrumented.</p><p>An invisibly-instrumented component must still have a type, identified in one of two ways:</p><ul><li>via the t:type attribute in the containing template, as in the above example, or</li><li>within the containing component's Java class using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation (and using the t:id attribute on the element in the temp
late). The Component annotation is attached to a field; the type of the component is determined by either the type of the field or the type attribute of the Component annotation.</li></ul><p>In <em>most</em> cases, it is merely an aesthetic choice whether to use invisible instrumentation in your templates. However, in a very few cases the behavior of the component is influenced by your choice. For example, when your template includes the Loop component using the invisible instrumentation approach, the original tag (and its informal parameters) will render repeatedly around the body of the component. Thus, for example:</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;"> <table>
<tr t:type="loop" source="items" value="item" class="prop:rowClass">
<td>${item.id}</td>
@@ -304,7 +304,7 @@ Added in 5.3
</p:else>
</t:if>
</pre>
-</div></div><p>This example passes a block of the template (containing the ActionLink component and some text) to the If component as parameter <code>else</code>. In the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/If.html">If component's reference page</a> you'll see that <code>else</code> is parameter of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Block</a>.</p><p>Name-spaced parameter elements are not allowed to have any attributes. The element name itself is used to identify the parameter of the component to bind.</p><h2 id="ComponentTemplates-WhitespaceinTemplates">Whitespace in Templates</h2><p>Tapestry strips out unnecessary whitespace from templates as they are parsed. Inside any block of text, repeated whitespace is reduced to a single space character. Blocks of text that are entirely whitespace, such a line break and whitespace between
two tags, is eliminated entirely.</p><p>If you do a view source on the rendered output, you'll see that the bulk of the rendered page is one long unbroken line.</p><p>This approach has certain efficiency advantages on both the server (less processing to render the page) and on the client (fewer characters to parse). Tools such as <a class="external-link" href="http://www.getfirebug.com/" rel="nofollow">FireBug</a> and <a class="external-link" href="http://code.google.com/chrome/devtools/" rel="nofollow">Chrome Developer Tools</a> are useful for allowing you to view the rendered HTML on the client properly.</p><p>In rare cases, the whitespace in a template <em>is</em> significant. Perhaps you are creating a <pre> (preformatted) block of text, or the whitespace interacts with your stylesheet to some desired effect.</p><p>You may use the standard XML attribute <code>xml:space</code> to indicate to Tapestry whether whitespace should be compressed (<code>xml:space="default"</code
>) or preserved (<code>xml:space="preserve"</code>). Such attributes are stripped out by the template parser; they do not appear in the rendered output.</p><p>The xml: namespace prefix is built into all XML documents, there is no special configuration (as there is with the Tapestry namespace).</p><p>For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This example passes a block of the template (containing the ActionLink component and some text) to the If component as parameter <code>else</code>. In the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/If.html">If component's reference page</a> you'll see that <code>else</code> is parameter of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Block</a>.</p><p>Name-spaced parameter elements are not allowed to have any attributes. The element name itself is used to identify the parameter of the component to bind.</p><h2 id="ComponentTemplates-WhitespaceinTemplates">Whitespace in Templates</h2><p>Tapestry strips out unnecessary whitespace from templates as they are parsed. Inside any block of text, repeated whitespace is reduced to a single space character. Blocks of text that are entirely whitespace, such a line break and whitespace between
two tags, is eliminated entirely.</p><p>If you do a view source on the rendered output, you'll see that the bulk of the rendered page is one long unbroken line.</p><p>This approach has certain efficiency advantages on both the server (less processing to render the page) and on the client (fewer characters to parse). Tools such as <a class="external-link" href="https://developer.mozilla.org/en-US/docs/Tools" rel="nofollow">Firefox Developer Tools</a> and <a class="external-link" href="http://code.google.com/chrome/devtools/" rel="nofollow">Chrome Developer Tools</a> are useful for allowing you to view the rendered HTML on the client properly.</p><p>In rare cases, the whitespace in a template <em>is</em> significant. Perhaps you are creating a <pre> (preformatted) block of text, or the whitespace interacts with your stylesheet to some desired effect.</p><p>You may use the standard XML attribute <code>xml:space</code> to indicate to Tapestry whether whitespace should be compres
sed (<code>xml:space="default"</code>) or preserved (<code>xml:space="preserve"</code>). Such attributes are stripped out by the template parser; they do not appear in the rendered output.</p><p>The xml: namespace prefix is built into all XML documents, there is no special configuration (as there is with the Tapestry namespace).</p><p>For example:</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;"> <ul class="navmenu" xml:space="preserve">
<li t:type="loop" t:source="pages" t:value="var:page">
<t:pagelink page="var:page">${var:page}</t:pagelink>
Modified: websites/production/tapestry/content/project-layout.html
==============================================================================
--- websites/production/tapestry/content/project-layout.html (original)
+++ websites/production/tapestry/content/project-layout.html Fri Feb 16 03:21:19 2018
@@ -67,38 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h1 id="ProjectLayout-ProjectLayout">Project Layout</h1>
-
-<p>This is the <em>suggested</em> layout for your Tapestry project; it is the layout of folders and files created by the <a href="getting-started.html">Tapestry Quickstart Archetype</a>. If you are creating your own build using Ant, you may use whatever conventions work for you ... as long as everything gets packaged up into the right place in the target WAR.</p>
-
-<p>Parts of this project layout mimics the format of an <em>exploded WAR</em> (a WAR file unpackaged onto the file system). This will often enable you to run your application directly from your workspace, without any special build or packaging process, while developing. Each of the major IDEs has plugins to allow you to accomplish this task ... and it's one of the factors (combined with <a href="class-reloading.html">live class reloading</a>) that makes working with Tapestry a breeze.</p>
-
-<p>Below is a sample project, whose root package is <code>com.example.myapp</code>:</p>
-
-
-<p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="project-layout.data/projectlayout.png"></span></p>
-
-<h2 id="ProjectLayout-Mainsourcefiles-src/main/java">Main source files - src/main/java</h2>
-
-<p>Main Java source files, the files that will be compiled into the WAR file, are in <code>src/main/java</code>. This is <em>only</em> Java source files. You can see the <code>Index.java</code> source file inside the <code>pages</code> subpackage, and the <code>Layout.java</code> source file inside the <code>components</code> subpackage. The package names demonstrated here are required, dictated by the rules for <a href="project-layout.html">component classes</a>.</p>
-
-<p>Compiled Java classes will ultimately be packaged in the WAR inside the <code>WEB-INF/classes</code> folder.</p>
-
-<h2 id="ProjectLayout-ClasspathResources-src/main/resources">Classpath Resources - src/main/resources</h2>
-
-<p>Resource files are under <code>src/main/resources</code>. This includes the <a href="localization.html">message catalog</a> for the Index page (<code>Index.properties</code>), as well as the message catalog and <a href="component-templates.html">component template</a> for the Layout component (<code>Layout.tml</code>). These files will also be packaged into the <code>WEB-INF/classes</code> folder of the WAR.</p>
-
-<p>Component templates will always be stored in the resources folder. Templates for pages may be packaged in the WAR proper instead.</p>
-
-<h2 id="ProjectLayout-ContextResources-src/main/webapp">Context Resources - src/main/webapp</h2>
-
-<p>The WAR is built primarily from the <code>src/main/webapp</code> folder; this is where ordinary files are stored (such as images and stylesheets). Page templates may also be stored here (<code>Index.tml</code>). The file <code>src/main/webapp/WEB-INF/web.xml</code> is the servlet container deployment descriptor, which has a very specific <a href="configuration.html">configuration</a> for Tapestry.</p>
-
-<p>The build tool (usually Maven) will be responsible for putting compiled classes and resources into the <code>WEB-INF/classes</code> folder of the WAR, and for putting the Tapestry library, and its dependencies (as well as any additional libraries defined by your application) into the <code>WEB-INF/lib</code> folder.</p>
-
-<h2 id="ProjectLayout-Testing-src/test">Testing - src/test</h2>
-
-<p>The folders <code>src/test/java</code> and <code>src/test/resources</code> are used when compiling and executing tests. Files in these folders are <em>not</em> packaged into the final WAR.</p></div>
+ <div id="ConfluenceContent"><h1 id="ProjectLayout-ProjectLayout">Project Layout</h1><p>This is the <em>suggested</em> layout for your Tapestry project; it is the layout of folders and files created by the <a href="getting-started.html">Tapestry Quickstart Archetype</a>. If you are creating your own build using Ant, you may use whatever conventions work for you ... as long as everything gets packaged up into the right place in the target WAR.</p><p>Parts of this project layout mimics the format of an <em>exploded WAR</em> (a WAR file unpackaged onto the file system). This will often enable you to run your application directly from your workspace, without any special build or packaging process, while developing. Each of the major IDEs has plugins to allow you to accomplish this task ... and it's one of the factors (combined with <a href="class-reloading.html">live class reloading</a>) that makes working with Tapestry a breeze.</p><p>Below is a sample project, whose r
oot package is <code>com.example.myapp</code>:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="project-layout.data/projectlayout.png"></span></p><h2 id="ProjectLayout-Mainsourcefiles-src/main/java">Main source files - src/main/java</h2><p>Main Java source files, the files that will be compiled into the WAR file, are in <code>src/main/java</code>. This is <em>only</em> Java source files. You can see the <code>Index.java</code> source file inside the <code>pages</code> subpackage, and the <code>Layout.java</code> source file inside the <code>components</code> subpackage. The package names demonstrated here are required, dictated by the rules for <a href="component-classes.html">component classes</a></p><p>.</p><p>Compiled Java classes will ultimately be packaged in the WAR inside the <code>WEB-INF/classes</code> folder.</p><h2 id="ProjectLayout-ClasspathResources-src/main/resources">Classpath Resources - src/main/resources</h2><p>Resou
rce files are under <code>src/main/resources</code>. This includes the <a href="localization.html">message catalog</a> for the Index page (<code>Index.properties</code>), as well as the message catalog and <a href="component-templates.html">component template</a> for the Layout component (<code>Layout.tml</code>). These files will also be packaged into the <code>WEB-INF/classes</code> folder of the WAR.</p><p>Component templates will always be stored in the resources folder. Templates for pages may be packaged in the WAR proper instead.</p><h2 id="ProjectLayout-ContextResources-src/main/webapp">Context Resources - src/main/webapp</h2><p>The WAR is built primarily from the <code>src/main/webapp</code> folder; this is where ordinary files are stored (such as images and stylesheets). Page templates may also be stored here (<code>Index.tml</code>). The file <code>src/main/webapp/WEB-INF/web.xml</code> is the servlet container deployment descriptor, which has a very specific <a href="
configuration.html">configuration</a> for Tapestry.</p><p>The build tool (usually Maven) will be responsible for putting compiled classes and resources into the <code>WEB-INF/classes</code> folder of the WAR, and for putting the Tapestry library, and its dependencies (as well as any additional libraries defined by your application) into the <code>WEB-INF/lib</code> folder.</p><h2 id="ProjectLayout-Testing-src/test">Testing - src/test</h2><p>The folders <code>src/test/java</code> and <code>src/test/resources</code> are used when compiling and executing tests. Files in these folders are <em>not</em> packaged into the final WAR.</p></div>
</div>
<div class="clearer"></div>