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>
