Modified: websites/production/tapestry/content/content-type-and-markup.html ============================================================================== --- websites/production/tapestry/content/content-type-and-markup.html (original) +++ websites/production/tapestry/content/content-type-and-markup.html Sat Feb 3 16:21:22 2018 @@ -36,13 +36,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">Content Type and Markup</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">Content Type and Markup</h1></div> + +</div> <div class="clearer"></div> </div> @@ -54,7 +67,7 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p>Tapestry reads <a href="component-templates.html">well-formed XML template files</a> and renders its output as XML, with minor caveats:</p><ul><li>The <?xml?> XML declaration is omitted.</li><li>Most elements render with an open and close tag, even if empty.</li><li>Certain elements will be abbreviated to just the open tag, if empty:<ul><li>br</li><li>hr</li><li>img</li></ul></li><li><![CDATA[]> sections are <strong>not</strong> used</li></ul><p>This is all to ensure that the markup stream, while (almost) well formed, is still properly understood by browsers expecting ordinary HTML. In fact, Tapestry may decide to render a purely XML document; it depends on the content type of the response.</p><p>When Tapestry renders a page, the output content type and charset is obtained from meta data on the page itself. Meta data is specified using the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache /tapestry5/annotations/Meta.html">@Meta</a> annotation.</p><h3 id="ContentTypeandMarkup-ContentType">Content Type</h3><p>The response content type is obtained via meta-data key <code>tapestry.response-content-type</code>. This value defaults to "text/html", which triggers specialized XML rendering.</p><p>A page may declare its content type using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/ContentType.html";>ContentType</a> class annotation. Content types other than "text/html" will render as well-formed XML documents, including the XML declaration, and more standard behavior for empty elements.</p><h3 id="ContentTypeandMarkup-CharacterSet">Character Set</h3><p>The character set (aka character encoding) used when writing output and when parsing requests is normally "utf-8". UTF-8 is a version of Unicode where individual characters are encoded as one or more bytes. Most western language characters (that is, typical AS CII characters) are encoded in a single byte. Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded as two or more bytes.</p><p>All pages use the same encoding, which can be set using the <code>tapestry.charset</code> <a href="configuration.html">configuration setting</a>.</p></div> + <div id="ConfluenceContent"><p>Tapestry reads <a href="content-type-and-markup.html">well-formed XML template files</a> and renders its output as XML, with minor caveats:</p><ul><li>The <?xml?> XML declaration is omitted.</li><li>Most elements render with an open and close tag, even if empty.</li><li>Certain elements will be abbreviated to just the open tag, if empty:<ul><li>br</li><li>hr</li><li>img</li></ul></li><li><![CDATA[]> sections are <strong>not</strong> used</li></ul><p>This is all to ensure that the markup stream, while (almost) well formed, is still properly understood by browsers expecting ordinary HTML. In fact, Tapestry may decide to render a purely XML document; it depends on the content type of the response.</p><p>When Tapestry renders a page, the output content type and charset is obtained from meta data on the page itself. Meta data is specified using the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/ap ache/tapestry5/annotations/Meta.html">@Meta</a> annotation.</p><h3 id="ContentTypeandMarkup-ContentType">Content Type</h3><p>The response content type is obtained via meta-data key <code>tapestry.response-content-type</code>. This value defaults to "text/html", which triggers specialized XML rendering.</p><p>A page may declare its content type using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/ContentType.html";>ContentType</a> class annotation. Content types other than "text/html" will render as well-formed XML documents, including the XML declaration, and more standard behavior for empty elements.</p><h3 id="ContentTypeandMarkup-CharacterSet">Character Set</h3><p>The character set (aka character encoding) used when writing output and when parsing requests is normally "utf-8". UTF-8 is a version of Unicode where individual characters are encoded as one or more bytes. Most western language characters (that is, typica l ASCII characters) are encoded in a single byte. Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded as two or more bytes.</p><p>All pages use the same encoding, which can be set using the <code>tapestry.charset</code> <a href="content-type-and-markup.html">configuration setting</a>.</p></div> </div> <div class="clearer"></div>
Modified: websites/production/tapestry/content/css.html ============================================================================== --- websites/production/tapestry/content/css.html (original) +++ websites/production/tapestry/content/css.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">CSS</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">CSS</h1></div> + +</div> <div class="clearer"></div> </div> @@ -63,31 +76,58 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p>Most web applications delegate to <strong>Cascading Style Sheets</strong> (CSS) the stylistic details of the page – fonts, colors, margins, borders and alignment. This helps the remaining HTML to remain simple and semantic, which usually makes it easier to read and maintain.</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="layout-component.html">Layout Component</a> - </div> </li><li> - <div> - <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> - </div> - <div class="details"> - <a href="css.html">CSS</a> - </div> </li><li> - <div> - <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> - </div> - <div class="details"> - <a href="legacy-javascript.html">Legacy JavaScript</a> - </div> </li><li> - <div> - <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> - </div> - <div class="details"> - <a href="assets.html">Assets</a> - </div> </li></ul></div><p>Tapestry includes sophisticated support for CSS in the form of annotation-based linking, far-future expire headers, automatic duplicate removal, and other features provided for <a href="assets.html">assets</a>.</p><h2 id="CSS-Defaultstylesheet">Default style sheet</h2><p>Tapestry includes a built-in style sheet, tapestry.css, in all HTML documents (documents that have an outer <html> element and a nested <head> element), as part of the "core" JavaScript stack. For Tapestry 5.4 and later, the core JavaScript stack also includes the CSS for <a class="external-link" href="http://getbootstrap.com/"; rel="nofollow">Bootstrap 3.1.1</a>.</p><h2 id="CSS-AddingyourownCSS">Adding your own CSS</h2><p>A page or component (for example, a <a href="layout-component.html">layout component</a>) that is rendering the <head> tag can add a style sheet directly in the markup.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> + <div id="ConfluenceContent"><p>Most web applications delegate to <strong>Cascading Style Sheets</strong> (CSS) the stylistic details of the page – fonts, colors, margins, borders and alignment. This helps the remaining HTML to remain simple and semantic, which usually makes it easier to read and maintain.</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="layout-component.html">Layout Component</a> + + + </div> + </li><li> + <div> + <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div> + + <div class="details"> + <a href="css.html">CSS</a> + + + </div> + </li><li> + <div> + <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div> + + <div class="details"> + <a href="legacy-javascript.html">Legacy JavaScript</a> + + + </div> + </li><li> + <div> + <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div> + + <div class="details"> + <a href="assets.html">Assets</a> + + + </div> + </li></ul> +</div> + + +<p>Tapestry includes sophisticated support for CSS in the form of annotation-based linking, far-future expire headers, automatic duplicate removal, and other features provided for <a href="css.html">assets</a>.</p><h2 id="CSS-Defaultstylesheet">Default style sheet</h2><p>Tapestry includes a built-in style sheet, tapestry.css, in all HTML documents (documents that have an outer <html> element and a nested <head> element), as part of the "core" JavaScript stack. For Tapestry 5.4 and later, the core JavaScript stack also includes the CSS for <a class="external-link" href="http://getbootstrap.com/"; rel="nofollow">Bootstrap 3.1.1</a>.</p><h2 id="CSS-AddingyourownCSS">Adding your own CSS</h2><p>A page or component (for example, a <a href="css.html">layout component</a>) that is rendering the <head> tag can add a style sheet directly in the markup.</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;"><head> <link href="/css/site.css" rel="stylesheet" type="text/css"/> . . . @@ -97,14 +137,14 @@ <link href="${context:css/site.css}" rel="stylesheet" type="text/css"/> . . . </pre> -</div></div><p>The "context:" prefix means that the remainder of the expansion is a path to a context asset, a resource in the web application root (<code>src/main/webapp</code> in your workspace). By contrast, the "asset:" prefix tells Tapestry to look in the class path. See <a href="assets.html">Assets</a>.</p><h2 id="CSS-Usingthe@Importannotation">Using the @Import annotation</h2><p>Another approach to adding a style sheet is to include an @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html";>Import</a> annotation (starting with Tapestry 5.2) on your component class:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>The "context:" prefix means that the remainder of the expansion is a path to a context asset, a resource in the web application root (<code>src/main/webapp</code> in your workspace). By contrast, the "asset:" prefix tells Tapestry to look in the class path. See <a href="css.html">CSS</a>.</p><h2 id="CSS-Usingthe@Importannotation">Using the @Import annotation</h2><p>Another approach to adding a style sheet is to include an @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html";>Import</a> annotation (starting with Tapestry 5.2) on your component class:</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;">@Import(stylesheet="context:css/site.css") public class MyComponent { } </pre> -</div></div><p>(For Tapestry 5.0 and 5.1, use the deprecated <a class="external-link" href="http://tapestry.apache.org/5.2/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html";>@IncludeStyleSheet</a> annotation instead.)</p><p>As with <a href="legacy-javascript.html">included JavaScript libraries</a>, each style sheet will only be added once, regardless of the number of components that include it via the annotation.</p><h2 id="CSS-ConditionallyloadingIE-onlystylesheets">Conditionally loading IE-only style sheets</h2><p>For Tapestry 5.2 and later, if you need to load a different style sheet for Internet Explorer browsers, or for certain versions of IE browsers, you can use Tapestry's built-in support for IE conditional comments. Just add something like the following to your page or component (or layout) class:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>(For Tapestry 5.0 and 5.1, use the deprecated <a class="external-link" href="http://tapestry.apache.org/5.2/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html";>@IncludeStyleSheet</a> annotation instead.)</p><p>As with <a href="css.html">included JavaScript libraries</a>, each style sheet will only be added once, regardless of the number of components that include it via the annotation.</p><h2 id="CSS-ConditionallyloadingIE-onlystylesheets">Conditionally loading IE-only style sheets</h2><p>For Tapestry 5.2 and later, if you need to load a different style sheet for Internet Explorer browsers, or for certain versions of IE browsers, you can use Tapestry's built-in support for IE conditional comments. Just add something like the following to your page or component (or layout) class:</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;">@Environmental private JavaScriptSupport javaScriptSupport; @@ -129,7 +169,7 @@ public static void deactiveDefaultCSS(Or configuration.override("InjectDefaultStyleheet", null); } </pre> -</div></div><p>Note: In Tapestry 5.3 and later, the misspelled "InjectDefaultStyleheet" is corrected to "InjectDefaultStylesheet".</p><p>In Tapestry 5.4, the "core" JavaScript has a configuration into which you may inject overrides.</p><h2 id="CSS-OverridingBootstrap(Tapestry5.4andlater)">Overriding Bootstrap (Tapestry 5.4 and later)</h2><p>The SymbolConstants.BOOTSTRAP_ROOT ("tapestry.bootstrap-root") symbol tells Tapestry where the Bootstrap css file is. You can override that symbol (see <a href="configuration.html">Configuration</a>) to have it point to your own version of Bootstrap (or even to an empty file if you want to eliminate Bootstrap entirely).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent pdl"> +</div></div><p>Note: In Tapestry 5.3 and later, the misspelled "InjectDefaultStyleheet" is corrected to "InjectDefaultStylesheet".</p><p>In Tapestry 5.4, the "core" JavaScript has a configuration into which you may inject overrides.</p><h2 id="CSS-OverridingBootstrap(Tapestry5.4andlater)">Overriding Bootstrap (Tapestry 5.4 and later)</h2><p>The SymbolConstants.BOOTSTRAP_ROOT ("tapestry.bootstrap-root") symbol tells Tapestry where the Bootstrap css file is. You can override that symbol (see <a href="css.html">CSS</a>) to have it point to your own version of Bootstrap (or even to an empty file if you want to eliminate Bootstrap entirely).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">configuration.add(SymbolConstants.BOOTSTRAP_ROOT, "classpath:/META-INF/assets");</pre> </div></div><p>For the above, your bootstrap.css file would be in your app's META-INF/assets/css folder.</p><p> </p></div> </div> Modified: websites/production/tapestry/content/development-dashboard.html ============================================================================== --- websites/production/tapestry/content/development-dashboard.html (original) +++ websites/production/tapestry/content/development-dashboard.html Sat Feb 3 16:21:22 2018 @@ -36,13 +36,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">Development Dashboard</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">Development Dashboard</h1></div> + +</div> <div class="clearer"></div> </div> @@ -54,7 +67,7 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p>The <strong>development dashboard</strong> is a built-in Tapestry page that can help identify and resolve problems in your application.</p><p>The dashboard is typically only available to requests from localhost (the page is whitelist access only, see <a href="security.html">Security</a>).</p><p><span style="line-height: 1.4285715;">Some features of the dashboard are only available in development mode.</span></p><p>The dashboard is available via the URI "core/t5dashboard", or can be accessed by the <a class="external-link" href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/components/DevTool.html";>DevTool</a> component's dropdown menu.</p><p><span style="line-height: 1.4285715;"> </span></p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-content-image-border image-center" width="500" src="development-dashb oard.data/Tapestry_5_Dashboard_-_pages.png"></span></p><p>By default, there are three tabs (this is extensible).</p><h2 id="DevelopmentDashboard-Pages">Pages</h2><p>The pages tab shows what pages are currently loaded into the application. Tapestry only loads a page when it is first needed.</p><p>It is possible to clear out Tapestry's caches, forcing a reload. You can also run a garbage collection (GC).</p><p>It is possible to load any individual page, or attempt to load all pages. This can be a good way to see if all pages (and templates) are error free ... loading all will catch quite a few potential errors.</p><h2 id="DevelopmentDashboard-Services">Services</h2><p>When using Tapestry there will often be a large number of services defined in the registry; a mix of the built-in services provided by the framework and your own.</p><p>Services are usually only instantiated once they are needed.</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded -manual-size"><img class="confluence-embedded-image confluence-content-image-border image-center" width="500" src="development-dashboard.data/Tapestry_5_Dashboard.png"></span></p><p>Services may be builtin, defined, virtual or real.</p><p><strong>Builtin</strong> only applies to a few special services that are part of Tapestry IoC.</p><p><strong>Defined</strong> services are defined in some module, but have not yet been referenced in any way.</p><p><strong>Virtual</strong> services have been referenced and have gotten as far as creating a service proxy.</p><p><strong>Real</strong> services have had methods invoked, this forces the <em>realization</em> of the service which includes instantiating the service, injecting dependencies, and decorating with any applicable interceptors.</p><h2 id="DevelopmentDashboard-ComponentLibraries">Component Libraries</h2><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embed ded-image confluence-content-image-border image-center" width="500" src="development-dashboard.data/Tapestry_5_Dashboard_-_libs.png"></span></p><p>This page gives a summary of all component libraries used in the current application.</p></div> + <div id="ConfluenceContent"><p>The <strong>development dashboard</strong> is a built-in Tapestry page that can help identify and resolve problems in your application.</p><p>The dashboard is typically only available to requests from localhost (the page is whitelist access only, see <a href="development-dashboard.html">Development Dashboard</a>).</p><p><span>Some features of the dashboard are only available in development mode.</span></p><p>The dashboard is available via the URI "core/t5dashboard", or can be accessed by the <a class="external-link" href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/components/DevTool.html";>DevTool</a> component's dropdown menu.</p><p><span> <span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image image-center" width="500" src="development-dashboard.data/Tapestry_5_Dashboard_-_pages.png"></span></span></p><p>By default, there a re three tabs (this is extensible).</p><h2 id="DevelopmentDashboard-Pages">Pages</h2><p>The pages tab shows what pages are currently loaded into the application. Tapestry only loads a page when it is first needed.</p><p>It is possible to clear out Tapestry's caches, forcing a reload. You can also run a garbage collection (GC).</p><p>It is possible to load any individual page, or attempt to load all pages. This can be a good way to see if all pages (and templates) are error free ... loading all will catch quite a few potential errors.</p><h2 id="DevelopmentDashboard-Services">Services</h2><p>When using Tapestry there will often be a large number of services defined in the registry; a mix of the built-in services provided by the framework and your own.</p><p>Services are usually only instantiated once they are needed.</p><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image image-center" width="500" src="development-dashboard.data/Tapestry_5_Dashboard.png"></span></p><p> </p><p>Services may be builtin, defined, virtual or real.</p><p><strong>Builtin</strong> only applies to a few special services that are part of Tapestry IoC.</p><p><strong>Defined</strong> services are defined in some module, but have not yet been referenced in any way.</p><p><strong>Virtual</strong> services have been referenced and have gotten as far as creating a service proxy.</p><p><strong>Real</strong> services have had methods invoked, this forces the <em>realization</em> of the service which includes instantiating the service, injecting dependencies, and decorating with any applicable interceptors.</p><h2 id="DevelopmentDashboard-ComponentLibraries">Component Libraries</h2><p><span class="confluence-embedded-file-wrapper image-center-wrapper confluence-embedded-manual-size"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border image-center" width="500" src="https://cwiki-test.apache.org/confluence/download/attachments/22872137/Tapestry_5_Dashboard_-_libs.png?version=1&modificationDate=1428090505000&api=v2"; data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872137/Tapestry_5_Dashboard_-_libs.png?version=1&modificationDate=1428090505000&api=v2";></span></p><p>This page gives a summary of all component libraries used in the current application.</p></div> </div> <div class="clearer"></div> Modified: websites/production/tapestry/content/dom.html ============================================================================== --- websites/production/tapestry/content/dom.html (original) +++ websites/production/tapestry/content/dom.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,13 +77,14 @@ </div> <div id="content"> - <div id="ConfluenceContent"><h1 id="DOM-DocumentObjectModel">Document Object Model</h1><p>Tapestry 5 takes a very different approach to markup generation than most other frameworks. Components render out a Document Object Model (DOM). This is a tree of nodes representing elements, attributes and text within a document.</p><p>Once all rendering is complete, the DOM tree is streamed to the client.</p><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter</a> interface allows the majority of component code to treat the generation of output as a stream. In reality, MarkupWriter is more like a cursor into the DOM tree, and the DOM may ultimately be operated upon in a random access manner (rather than the serial (or buffered) approach used in Tapestry 4).</p><plain-text-body>{float:right|width=30%} -{info:title=A Note For Tapestry 4 Users} -In Tapestry 4, markup generation was based on generating a character stream. At the lowest level, the fact that the output was in a markup format such as HTML, XHTML or WML was not known. Higher levels, such as the IMarkupWriter interface (and its implementations) provide the concept of markup generation: elements, attributes, start tags and end tags. This technique breaks down when two elements are peers, and not in a parent/child relationship. For example, the rendering of a FieldLabel component is affected by its companion TextField component. Handling these cases in Tapestry 4 required a number of kludges and special cases. -{info} -{float}</plain-text-body><h1 id="DOM-DOMClasses">DOM Classes</h1><p>The implementation of this DOM is part of Tapestry, despite the fact that several third-party alternatives exist. This represents a desire to limit dependencies for the framework, but also the Tapestry DOM is streamlined for initial creation, and a limited amount of subsequent modification. Most DOM implementations are more sophisticated than needed for Tapestry, with greater support for querying (often using XPath) and manipulation.</p><p>Once the Document object is created, you don't directly create new DOM objects; instead, each DOM object includes methods that create new sub-objects. This primarily applies to the Element class, which can be a container of text, comments and other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html";>Document Object</a> represents the an entire document, which is to say, an entire response to be sent to the client.</p><p>Documents will have a single root element. The newRootElement() method is used to create the root element for the document.</p><p>The Document class also has methods for setting and getting the DTD, adding comments and text, and finding an element based on a path of element names.</p><h2 id="DOM-Element">Element</h2><p>An <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html";>Element Object</a> represents an element of the document. Elements may have attributes, and they may themselves contain other elements, as well as text and comments.</p><p>The Element class has methods for searching, traversing and manipulating the DOM after it is built.</p><h1 id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A powerful feature of Tapestry 5 is the ability to manipulate the structure and ordering of the DOM after it has been rendered. For example, this can be u sed to alter the output of a component that may otherwise be outside of your control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on Node (and Element, which is a subclass of Node) allow an existing node to be moved relative to an Element. Nodes may be moved before or after the Element, or may be moved inside an Element at the top (the first child) or the bottom (the last child).</p><p>Element's <code>attribute</code> method adds a new attribute name/value pair to the Element. If an existing attribute with the specified name already exists, then then the new value is ignored. This has implications when different pieces of code try to add attributes to an Element ... the first to add an attribute will "win". Conversely, the <code>forceAttributes</code> method can be used to update or remove an attribute.</p><p>In addition, the children of an Element may be removed or a Node (and all of its children) removed entirely.</p><p>Finally, an Element may "pop": the Elemen t is removed and replaced with its children.</p><h1 id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter interface</a> allows the structure of the document to be built while maintaining a streaming metaphor.</p><h2 id="DOM-element()andend()methods">element() and end() methods</h2><p>Calls to element() create a new element within the tree, and may provide attributes for the new element as well. Calls to write(), writeln() and writef() write text nodes within the current element. <em>Every call to element() should be matched with a call to end()</em>, which is used to move the current node up one level.</p><parameter ac:name="">java</parameter><plain-text-body> writer.element("img", "src", "icon.png", "width", 20, "height", 20, alt, "*"); + <div id="ConfluenceContent"><h1 id="DOM-DocumentObjectModel">Document Object Model</h1><p>Tapestry 5 takes a very different approach to markup generation than most other frameworks. Components render out a Document Object Model (DOM). This is a tree of nodes representing elements, attributes and text within a document.</p><p>Once all rendering is complete, the DOM tree is streamed to the client.</p><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter</a> interface allows the majority of component code to treat the generation of output as a stream. In reality, MarkupWriter is more like a cursor into the DOM tree, and the DOM may ultimately be operated upon in a random access manner (rather than the serial (or buffered) approach used in Tapestry 4).</p><div class="navmenu" style="float:right; width:30%; background:white; margin:3px; padding:3px"> +<div class="confluence-information-macro confluence-information-macro-information"><p class="title">A Note For Tapestry 4 Users</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"> +<p>In Tapestry 4, markup generation was based on generating a character stream. At the lowest level, the fact that the output was in a markup format such as HTML, XHTML or WML was not known. Higher levels, such as the IMarkupWriter interface (and its implementations) provide the concept of markup generation: elements, attributes, start tags and end tags. This technique breaks down when two elements are peers, and not in a parent/child relationship. For example, the rendering of a FieldLabel component is affected by its companion TextField component. Handling these cases in Tapestry 4 required a number of kludges and special cases.</p></div></div></div><h1 id="DOM-DOMClasses">DOM Classes</h1><p>The implementation of this DOM is part of Tapestry, despite the fact that several third-party alternatives exist. This represents a desire to limit dependencies for the framework, but also the Tapestry DOM is streamlined for initial creation, and a limited amount of subsequent modification. Mo st DOM implementations are more sophisticated than needed for Tapestry, with greater support for querying (often using XPath) and manipulation.</p><p>Once the Document object is created, you don't directly create new DOM objects; instead, each DOM object includes methods that create new sub-objects. This primarily applies to the Element class, which can be a container of text, comments and other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html";>Document Object</a> represents the an entire document, which is to say, an entire response to be sent to the client.</p><p>Documents will have a single root element. The newRootElement() method is used to create the root element for the document.</p><p>The Document class also has methods for setting and getting the DTD, adding comments and text, and finding an element based on a path of element names.</p><h2 id="DOM-Element" >Element</h2><p>An <a class="external-link" >href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html";>Element > Object</a> represents an element of the document. Elements may have >attributes, and they may themselves contain other elements, as well as text >and comments.</p><p>The Element class has methods for searching, traversing >and manipulating the DOM after it is built.</p><h1 >id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A >powerful feature of Tapestry 5 is the ability to manipulate the structure and >ordering of the DOM after it has been rendered. For example, this can be used >to alter the output of a component that may otherwise be outside of your >control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on >Node (and Element, which is a subclass of Node) allow an existing node to be >moved relative to an Element. Nodes may be moved before or after the Element, >or may be moved inside an Element at the top (the firs t child) or the bottom (the last child).</p><p>Element's <code>attribute</code> method adds a new attribute name/value pair to the Element. If an existing attribute with the specified name already exists, then then the new value is ignored. This has implications when different pieces of code try to add attributes to an Element ... the first to add an attribute will "win". Conversely, the <code>forceAttributes</code> method can be used to update or remove an attribute.</p><p>In addition, the children of an Element may be removed or a Node (and all of its children) removed entirely.</p><p>Finally, an Element may "pop": the Element is removed and replaced with its children.</p><h1 id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html";>MarkupWriter interface</a> allows the structure of the document to be built while maintaining a streaming metaphor.</p><h2 id="DOM-element()andend()m ethods">element() and end() methods</h2><p>Calls to element() create a new element within the tree, and may provide attributes for the new element as well. Calls to write(), writeln() and writef() write text nodes within the current element. <em>Every call to element() should be matched with a call to end()</em>, which is used to move the current node up one level.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> writer.element("img", "src", "icon.png", "width", 20, "height", 20, alt, "*"); writer.end(); -</plain-text-body><p>Note that end() must be called here, even though the <img> element is empty (has no body). If the call to end() is omitted, then later elements created by calls to element() will be nested <em>inside</em> the <img> element, which is not desired.</p><p>Again, <strong>every call to element() must be matched with a call to end()</strong>:</p><parameter ac:name="">java</parameter><plain-text-body> writer.element("select", "name", "choice"); +</pre> +</div></div><p>Note that end() must be called here, even though the <img> element is empty (has no body). If the call to end() is omitted, then later elements created by calls to element() will be nested <em>inside</em> the <img> element, which is not desired.</p><p>Again, <strong>every call to element() must be matched with a call to end()</strong>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> writer.element("select", "name", "choice"); for (String name : optionsNames) { @@ -83,9 +94,12 @@ In Tapestry 4, markup generation was bas } writer.end(); -</plain-text-body><h2 id="DOM-attributes()">attributes()</h2><p>Adds additional name/value pairs to the current element.</p><p>When a value is null, no attribute is added.</p><p>When a new name conflicts with an existing name, the new value is ignored. This gives precedence to the first value specified for an attribute over any subsequent value.</p><h2 id="DOM-write()">write()</h2><p>The write() method writes text inside the current element. It scans the provided text for XML control characters ('<', '>', and '&') and converts them to their XML entity equivalents ('<', '>', and '&'). The result is correct, safe, HTML/XML output even when the content (which may come from a template, or from an external source such as a database) contains such problematic characters.</p><h2 id="DOM-writef()">writef()</h2><p>The writef() method formats an number of arguments. It uses a java.util.Formatter. It is a convenience for formatting that ultimately invokes write().</p><h2 id ="DOM-writeRaw()">writeRaw()</h2><p>The writeRaw() method writes unfiltered text into the DOM. When the DOM is rendered to markup, the provided string is written to the output stream exactly as-is. Care should be taken, as this can easily result invalid markup, or even markup that is not well formed.</p><h2 id="DOM-comment()">comment()</h2><p>Adds an XML comment. The comment delimiters will be supplied by Tapestry:</p><parameter ac:name="">java</parameter><plain-text-body> writer.comment("Start of JS Menu code"); +</pre> +</div></div><h2 id="DOM-attributes()">attributes()</h2><p>Adds additional name/value pairs to the current element.</p><p>When a value is null, no attribute is added.</p><p>When a new name conflicts with an existing name, the new value is ignored. This gives precedence to the first value specified for an attribute over any subsequent value.</p><h2 id="DOM-write()">write()</h2><p>The write() method writes text inside the current element. It scans the provided text for XML control characters ('<', '>', and '&') and converts them to their XML entity equivalents ('<', '>', and '&'). The result is correct, safe, HTML/XML output even when the content (which may come from a template, or from an external source such as a database) contains such problematic characters.</p><h2 id="DOM-writef()">writef()</h2><p>The writef() method formats an number of arguments. It uses a java.util.Formatter. It is a convenience for formatting that ultimately invokes write().</p><h2 id="DOM- writeRaw()">writeRaw()</h2><p>The writeRaw() method writes unfiltered text into the DOM. When the DOM is rendered to markup, the provided string is written to the output stream exactly as-is. Care should be taken, as this can easily result invalid markup, or even markup that is not well formed.</p><h2 id="DOM-comment()">comment()</h2><p>Adds an XML comment. The comment delimiters will be supplied by Tapestry:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> writer.comment("Start of JS Menu code"); -</plain-text-body></div> +</pre> +</div></div></div> </div> <div class="clearer"></div> Modified: websites/production/tapestry/content/environmental-services.html ============================================================================== --- websites/production/tapestry/content/environmental-services.html (original) +++ websites/production/tapestry/content/environmental-services.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,11 +77,11 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p><plain-text-body>{float:right|background=#eee|width=30%} -Environmental services represent yet another, distinct form of injection. + <div id="ConfluenceContent"><div class="navmenu" style="float:right; width:30%; background:#eee; margin:3px; padding:3px"> +<p>Environmental services represent yet another, distinct form of injection.</p> -Unlike service injection (injection via a service implementation's constructor) or normal component injection (directly into component fields, via the @Inject annotation) where the injected value is always the same, with environmental services, the injected value is very late bound and dynamic. -{float}</plain-text-body><strong>Environmental services</strong> provide a conduit of communication between two components (usually a component and the components it encloses). The first component pushes an object of a certain type into the <em>environment</em>, and then the second component can access that object merely by defining an annotated property of the same type.</p><p>An example of how this works is Tapestry's built-in <em>form support</em>. The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html";>Form</a> component creates an object of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/FormSupport.html";>FormSupport</a> and pushes it into the environment. Then, the enclosed form components can use that FormSupport object to participate in both the rendering of the Form and the Form's eventual submission. This is how control names and client-si de ids are determined, how fields register callbacks so that they can process their part of the submission, and how fields hook themselves to client-side validation.</p><h1 id="EnvironmentalServices-Usingthe@Environmentalannotation">Using the @Environmental annotation</h1><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html";>Environmental</a> annotation, when used in a component class, causes the associated field to be replaced at runtime with a read-only value obtained from an Environment service provided by an enclosing component.</p><p>A very common Environmental is <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>, used when generating <a href="legacy-javascript.html">client-side JavaScript</a>.</p><parameter ac:name="">java</parameter><plain-text-body> @Inject @Path("${tapestry.scripta culous}/dragdrop.js") +<p>Unlike service injection (injection via a service implementation's constructor) or normal component injection (directly into component fields, via the @Inject annotation) where the injected value is always the same, with environmental services, the injected value is very late bound and dynamic.</p></div><strong>Environmental services</strong> provide a conduit of communication between two components (usually a component and the components it encloses). The first component pushes an object of a certain type into the <em>environment</em>, and then the second component can access that object merely by defining an annotated property of the same type.<p>An example of how this works is Tapestry's built-in <em>form support</em>. The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html";>Form</a> component creates an object of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/t apestry5/services/FormSupport.html">FormSupport</a> and pushes it into the environment. Then, the enclosed form components can use that FormSupport object to participate in both the rendering of the Form and the Form's eventual submission. This is how control names and client-side ids are determined, how fields register callbacks so that they can process their part of the submission, and how fields hook themselves to client-side validation.</p><h1 id="EnvironmentalServices-Usingthe@Environmentalannotation">Using the @Environmental annotation</h1><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html";>Environmental</a> annotation, when used in a component class, causes the associated field to be replaced at runtime with a read-only value obtained from an Environment service provided by an enclosing component.</p><p>A very common Environmental is <a class="external-link" href="http://tapestry.apache.org/c urrent/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html">JavaScriptSupport</a>, used when generating <a href="environmental-services.html">client-side JavaScript</a>.</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 @Path("${tapestry.scriptaculous}/dragdrop.js") private Asset dragDropLibrary; @Environmental @@ -82,7 +92,9 @@ Unlike service injection (injection via javaScriptSupport.importJavaScriptLibrary(dragDropLibrary); } -</plain-text-body><p>Environmental services are, by their nature, per-thread (and therefore per-request).</p><p>Accessing an environmental field causes a lookup, by type, against the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Environment.html";>Environment</a> service.</p><p>Normally, an environmental of the specified type must be available in the Environment, or an exception is thrown when accessing the field. However, if the value of the Environmental annotation's value is false, then the environmental value is optional.</p><h1 id="EnvironmentalServices-Placingavalueintheenvironment">Placing a value in the environment</h1><p>The Environment service has push() and pop() methods to put a value in the Environment, and discard it.</p><p>For example, say you were building a tab-based menu system and you needed to allow an outer TabGroup component to communicate with inner Tab components, to control various aspects of presenta tion.</p><p>The relevant information could be exposed as an interface, TabModel.</p><parameter ac:name="">java</parameter><plain-text-body>public class TabGroup +</pre> +</div></div><p>Environmental services are, by their nature, per-thread (and therefore per-request).</p><p>Accessing an environmental field causes a lookup, by type, against the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Environment.html";>Environment</a> service.</p><p>Normally, an environmental of the specified type must be available in the Environment, or an exception is thrown when accessing the field. However, if the value of the Environmental annotation's value is false, then the environmental value is optional.</p><h1 id="EnvironmentalServices-Placingavalueintheenvironment">Placing a value in the environment</h1><p>The Environment service has push() and pop() methods to put a value in the Environment, and discard it.</p><p>For example, say you were building a tab-based menu system and you needed to allow an outer TabGroup component to communicate with inner Tab components, to control various aspects of presentation.< /p><p>The relevant information could be exposed as an interface, TabModel.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class TabGroup { @Inject private Environment environment; @@ -108,11 +120,14 @@ public class Tab ... } } -</plain-text-body><p>Notice that when pushing a value into the Environment, you identify its type as well as the instance. Environment maintains a number of stacks, one for each type. Thus, pushing a TabModel into the environment won't disturb the RenderSupport or other environmentals already there.</p><p>What's important here is that the code that pushes a environmental onto a stack should also pop it off.</p><p>The enclosed class, Tab, has full access to whatever object was pushed onto the stack by the TabGroup.</p><p>The reason why Environment is a stack is so that a component can, when it makes sense, easily replace or intercept access to an Environmental.</p><h1 id="EnvironmentalServices-FundamentalEnvironmentals">Fundamental Environmentals</h1><p>Not all environmentals are pushed into the Environment by components.</p><p>A number of environmentals are initialized as part of page rendering, even before the first component starts to render. This initialization is accomplished wi th <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html";>MarkupRendererFilter</a> contributions to the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRenderer.html";>MarkupRenderer</a> service.</p><h1 id="EnvironmentalServices-AccessingEnvironmentalsinServices">Accessing Environmentals in Services</h1><p>The Environmental annotation only works inside components.</p><p>To access an Environmental inside a service implementation, you must inject the Environment service and obtain values from it using the peek() method.</p><p>If this is something that will occur frequently, it is possible to create a service implementation that is "backed" by the Environment. For example, RenderSupport is accessible as a normal injection, because a service is built for it in TapestryModule:</p><parameter ac:name="">java</parameter><plain-text-body> public RenderSu pport buildRenderSupport(EnvironmentalShadowBuilder builder) +</pre> +</div></div><p>Notice that when pushing a value into the Environment, you identify its type as well as the instance. Environment maintains a number of stacks, one for each type. Thus, pushing a TabModel into the environment won't disturb the RenderSupport or other environmentals already there.</p><p>What's important here is that the code that pushes a environmental onto a stack should also pop it off.</p><p>The enclosed class, Tab, has full access to whatever object was pushed onto the stack by the TabGroup.</p><p>The reason why Environment is a stack is so that a component can, when it makes sense, easily replace or intercept access to an Environmental.</p><h1 id="EnvironmentalServices-FundamentalEnvironmentals">Fundamental Environmentals</h1><p>Not all environmentals are pushed into the Environment by components.</p><p>A number of environmentals are initialized as part of page rendering, even before the first component starts to render. This initialization is accomplished with <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html";>MarkupRendererFilter</a> contributions to the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRenderer.html";>MarkupRenderer</a> service.</p><h1 id="EnvironmentalServices-AccessingEnvironmentalsinServices">Accessing Environmentals in Services</h1><p>The Environmental annotation only works inside components.</p><p>To access an Environmental inside a service implementation, you must inject the Environment service and obtain values from it using the peek() method.</p><p>If this is something that will occur frequently, it is possible to create a service implementation that is "backed" by the Environment. For example, RenderSupport is accessible as a normal injection, because a service is built for it in TapestryModule:</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 RenderSupport buildRenderSupport(EnvironmentalShadowBuilder builder) { return builder.build(RenderSupport.class); } -</plain-text-body><p>The EnvironmentShadowBuilder service creates a service implementation that delegates to the proper instance in the environment. The same technique can be used for your own services and environmentals.</p></div> +</pre> +</div></div><p>The EnvironmentShadowBuilder service creates a service implementation that delegates to the proper instance in the environment. The same technique can be used for your own services and environmentals.</p></div> </div> <div class="clearer"></div>
![http://tapestry.apache.org/images/tapestry_small.png"](http://tapestry.apache.org/images/tapestry_small.png"){kind=link}
![https://cwiki-test.apache.org/confluence/download/attachments/22872137/Tapestry_5_Dashboard_-_libs.png?version=1&modificationDate=1428090505000&api=v2"](https://cwiki-test.apache.org/confluence/download/attachments/22872137/Tapestry_5_Dashboard_-_libs.png?version=1&modificationDate=1428090505000&api=v2"){kind=link}