You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2017/09/16 02:22:41 UTC
svn commit: r1018228 [12/41] - in /websites/production/tapestry/content: ./
cache/
Modified: websites/production/tapestry/content/configuration.html
==============================================================================
--- websites/production/tapestry/content/configuration.html (original)
+++ websites/production/tapestry/content/configuration.html Sat Sep 16 02:22:40 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,84 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><div class="aui-label" style="float:right" title="Related Articles">
-
-
-
-
-
-
-
-
-<h3>Related Articles</h3>
-
-<ul class="content-by-label"><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
-
- <div class="details">
- <a href="application-module-class-cheat-sheet.html">Application Module Class Cheat Sheet</a>
-
-
- </div>
- </li><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
-
- <div class="details">
- <a href="ioc-cookbook-service-configurations.html">IoC cookbook - Service Configurations</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="symbols.html">Symbols</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="tapestry-ioc-configuration.html">Tapestry IoC Configuration</a>
-
-
- </div>
- </li><li>
- <div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
-
- <div class="details">
- <a href="response-compression.html">Response Compression</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="configuration.html">Configuration</a>
-
-
- </div>
- </li></ul>
-</div>
-
-
-<h1 id="Configuration-ConfiguringTapestry">Configuring Tapestry</h1><p>This page discusses all the ways in which Tapestry can be configured. Tapestry applications are configured almost entirely using Java, with very little XML at all.</p><p><strong>Contents</strong></p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1499639540986 {padding: 0px;}
-div.rbtoc1499639540986 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1499639540986 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style></p><div class="toc-macro rbtoc1499639540986">
-<ul class="toc-indentation"><li><a href="#Configuration-XMLconfiguration(web.xml)">XML configuration (web.xml)</a></li><li><a href="#Configuration-YourApplication'sModuleClass">Your Application's Module Class</a></li><li><a href="#Configuration-ConfigurationSymbolNames">Configuration Symbol Names</a></li><li><a href="#Configuration-SettingComponentParameterDefaults">Setting Component Parameter Defaults</a></li><li><a href="#Configuration-ConfiguringIgnoredPaths">Configuring Ignored Paths</a></li><li><a href="#Configuration-ConfiguringContentTypeMapping">Configuring Content Type Mapping</a></li><li><a href="#Configuration-SettingExecutionModes">Setting Execution Modes</a></li></ul>
-</div><h2 id="Configuration-XMLconfiguration(web.xml)">XML configuration (web.xml)</h2><p>Tapestry runs on top of the standard Java Servlet API. To the servlet container, such as Tomcat, Tapestry appears as a <em>servlet filter</em>. This gives Tapestry great flexibility in matching URLs without requiring lots of XML configuration.</p><p>Although most configuration is done with Java, a small but necessary amount of configuration occurs inside the servlet deployment descriptor, WEB-INF/web.xml. Most of the configuration is boilerplate, nearly the same for all applications.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>web.xml (partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><!DOCTYPE web-app
+ <div id="ConfluenceContent"><parameter ac:name="style">float:right</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="class">aui-label</parameter><rich-text-body><parameter ac:name="showLabels">false</parameter><parameter ac:name="showSpace">false</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="cql">label = "configuration" and space = currentSpace()</parameter></rich-text-body><h1 id="Configuration-ConfiguringTapestry">Configuring Tapestry</h1><p>This page discusses all the ways in which Tapestry can be configured. Tapestry applications are configured almost entirely using Java, with very little XML at all.</p><p><strong>Contents</strong></p><p><parameter ac:name="maxLevel">2</parameter><parameter ac:name="minLevel">2</parameter></p><h2 id="Configuration-XMLconfiguration(web.xml)">XML configuration (web.xml)</h2><p>Tapestry runs on top of the standard Java Servlet API. To the servlet container,
such as Tomcat, Tapestry appears as a <em>servlet filter</em>. This gives Tapestry great flexibility in matching URLs without requiring lots of XML configuration.</p><p>Although most configuration is done with Java, a small but necessary amount of configuration occurs inside the servlet deployment descriptor, WEB-INF/web.xml. Most of the configuration is boilerplate, nearly the same for all applications.</p><parameter ac:name="language">xml</parameter><parameter ac:name="title">web.xml (partial)</parameter><plain-text-body><!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
@@ -172,14 +85,13 @@ div.rbtoc1499639540986 li {margin-left:
<url-pattern>/*</url-pattern>
</filter-mapping>
</web-app>
-</pre>
-</div></div><p></p><div class="navmenu" style="float:right; width:30%; background:#eee; margin:3px; padding:3px">
-<p><font color="#539126"><strong>Tapestry Requests vs. Container Requests</strong></font></p>
+</plain-text-body><p><plain-text-body>{float:right|width=30%|background=#eee}
+{color:#539126}*Tapestry Requests vs. Container Requests*{color}
-<p>The Tapestry filter matches all the requests that apply to Tapestry, and passes the rest off to the servlet container. In situations where there would be a naming conflict, actual files inside the web application take precedence over Tapestry pages.</p>
+The Tapestry filter matches all the requests that apply to Tapestry, and passes the rest off to the servlet container. In situations where there would be a naming conflict, actual files inside the web application take precedence over Tapestry pages.
-<p>Tapestry recognizes the <em>root URL</em>, where the servlet path is simply "/", and renders the application page "Index", if it exists.</p></div>The application-specific part, the <code>tapestry.app-package</code> context parameter, provides your application's root package name. Tapestry uses this to locate your page and component classes. It expects page classes in the <code>pages</code> sub-package and components in the <code>components</code> sub-package. In the example above, page classes will be stored in the <code>org.example.myapp.pages</code> package (or in sub-packages below). Likewise, component classes will be stored in the <code>org.example.myapp.components</code> package.<p>By convention, the filter name (<code>filter-name</code>) is almost always "app", but you can use any name you want. Tapestry uses this to determine what <em>module class</em> name to look for (see below).</p><h2 id="Configuration-YourApplication'sModuleClass">Your Application's Module Class</h2>
<p>Main Article: <a href="tapestry-ioc-configuration.html">Tapestry IoC Configuration</a></p><p>Most other configuration occurs inside your application's module class. The application module class will often define new services, provide overrides of services, or make contributions to service configurations.</p><p>Tapestry looks for your application module class in the services package (under the root package) of your application. It capitalizes the <filter-name> and appends "Module". In the previous example, because the filter name was "app" and the application's root package name is "org.example.myapp", the module class would be org.example.myapp.services.AppModule.</p><p>If such a class exists, it is added to the IoC Registry. It is not an error for your application to not have a module class, though any non-trivial application will have one.</p><p>Your application module class (usually AppModule.java) will typically override some of Tapestry's default, or "factory", symbol
s, by contributing overrides to the ApplicationDefaults service configuration. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class AppModule
+Tapestry recognizes the _root URL_, where the servlet path is simply "/", and renders the application page "Index", if it exists.
+{float}</plain-text-body>The application-specific part, the <code>tapestry.app-package</code> context parameter, provides your application's root package name. Tapestry uses this to locate your page and component classes. It expects page classes in the <code>pages</code> sub-package and components in the <code>components</code> sub-package. In the example above, page classes will be stored in the <code>org.example.myapp.pages</code> package (or in sub-packages below). Likewise, component classes will be stored in the <code>org.example.myapp.components</code> package.</p><p>By convention, the filter name (<code>filter-name</code>) is almost always "app", but you can use any name you want. Tapestry uses this to determine what <em>module class</em> name to look for (see below).</p><h2 id="Configuration-YourApplication'sModuleClass">Your Application's Module Class</h2><p>Main Article: <a href="tapestry-ioc-configuration.html">Tapestry IoC Configuration</a></p><p>Most other configuratio
n occurs inside your application's module class. The application module class will often define new services, provide overrides of services, or make contributions to service configurations.</p><p>Tapestry looks for your application module class in the services package (under the root package) of your application. It capitalizes the <filter-name> and appends "Module". In the previous example, because the filter name was "app" and the application's root package name is "org.example.myapp", the module class would be org.example.myapp.services.AppModule.</p><p>If such a class exists, it is added to the IoC Registry. It is not an error for your application to not have a module class, though any non-trivial application will have one.</p><p>Your application module class (usually AppModule.java) will typically override some of Tapestry's default, or "factory", symbols, by contributing overrides to the ApplicationDefaults service configuration. For example:</p><parameter ac:name="langu
age">java</parameter><parameter ac:name="title">AppModule.java</parameter><plain-text-body>public class AppModule
{
public static void contributeApplicationDefaults(MappedConfiguration<String,String> configuration)
{
@@ -187,8 +99,7 @@ div.rbtoc1499639540986 li {margin-left:
configuration.add(SymbolConstants.FILE_CHECK_INTERVAL, "10 m");
}
}
-</pre>
-</div></div><h2 id="Configuration-ConfigurationSymbolNames">Configuration Symbol Names</h2><p>Main Article: <a href="symbols.html">Symbols</a></p><p>Many of Tapestry's built-in services (some of which are not even public) are configured via symbols. These symbols can be overridden by contributing to the ApplicationDefaults service configuration, or by placing a <context-param> element into the application's web.xml, or on the command line by defining JVM System Properties with the -D command line option.</p><p>These symbols are always defined in terms of strings, and those strings are coerced to the appropriate type (a number, a boolean, etc.). Of special note are <em>time intervals</em>, which are specified in a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html">particular format</a>.</p><p>Most of these symbols have a constant defined in the <a class="external-link" href="http://tapestry.apache.org/cu
rrent/apidocs/org/apache/tapestry5/SymbolConstants.html">SymbolConstants</a> class, while others are in the <a href="https://cwiki.apache.org/confluence/tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCSymbols.html">IOCSymbols</a> class. Those are noted in parentheses below. Use the symbol name (tapestry.*) for JVM System Properties with the -D option, and use the constant (in parentheses) from within your Java classes (e.g. AppModule.java).</p><h3 id="Configuration-tapestry.app-catalog(SymbolConstants.APPLICATION_CATALOG)">tapestry.app-catalog (SymbolConstants.APPLICATION_CATALOG)</h3><p>The location of the global application message catalog, the default is context:WEB-INF/<em>app-name</em>.properties.</p><h3 id="Configuration-tapestry.application-version(SymbolConstants.APPLICATION_VERSION)">tapestry.application-version (SymbolConstants.APPLICATION_VERSION)</h3><p>The version of the application, which is incorporated into URLs for context and classpath assets. Asse
ts may be <a href="response-compression.html">compressed</a>, and will have far-future expiration headers; they will be aggressively cached by the client web browser. You should change the application version on each new deployment of the application (that is, any time assets in the context change), to force clients to re-download changed versions of files. If you do not specify an application version, a <em>random</em> one will be assigned on every deployment (which is good for development but very bad for production).</p><h3 id="Configuration-tapestry.application-folder(SymbolConstants.APPLICATION_FOLDER)">tapestry.application-folder (SymbolConstants.APPLICATION_FOLDER)</h3>
+</plain-text-body><h2 id="Configuration-ConfigurationSymbolNames">Configuration Symbol Names</h2><p>Main Article: <a href="symbols.html">Symbols</a></p><p>Many of Tapestry's built-in services (some of which are not even public) are configured via symbols. These symbols can be overridden by contributing to the ApplicationDefaults service configuration, or by placing a <context-param> element into the application's web.xml, or on the command line by defining JVM System Properties with the -D command line option.</p><p>These symbols are always defined in terms of strings, and those strings are coerced to the appropriate type (a number, a boolean, etc.). Of special note are <em>time intervals</em>, which are specified in a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html">particular format</a>.</p><p>Most of these symbols have a constant defined in the <a class="external-link" href="http://tapestry.apache.
org/current/apidocs/org/apache/tapestry5/SymbolConstants.html">SymbolConstants</a> class, while others are in the <a href="https://cwiki.apache.org/confluence/tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCSymbols.html">IOCSymbols</a> class. Those are noted in parentheses below. Use the symbol name (tapestry.*) for JVM System Properties with the -D option, and use the constant (in parentheses) from within your Java classes (e.g. AppModule.java).</p><h3 id="Configuration-tapestry.app-catalog(SymbolConstants.APPLICATION_CATALOG)">tapestry.app-catalog (SymbolConstants.APPLICATION_CATALOG)</h3><p>The location of the global application message catalog, the default is context:WEB-INF/<em>app-name</em>.properties.</p><h3 id="Configuration-tapestry.application-version(SymbolConstants.APPLICATION_VERSION)">tapestry.application-version (SymbolConstants.APPLICATION_VERSION)</h3><p>The version of the application, which is incorporated into URLs for context and classpath assets
. Assets may be <a href="response-compression.html">compressed</a>, and will have far-future expiration headers; they will be aggressively cached by the client web browser. You should change the application version on each new deployment of the application (that is, any time assets in the context change), to force clients to re-download changed versions of files. If you do not specify an application version, a <em>random</em> one will be assigned on every deployment (which is good for development but very bad for production).</p><h3 id="Configuration-tapestry.application-folder(SymbolConstants.APPLICATION_FOLDER)">tapestry.application-folder (SymbolConstants.APPLICATION_FOLDER)</h3>
<div class="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.3</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
</div></div>
@@ -352,7 +263,7 @@ div.rbtoc1499639540986 li {margin-left:
<div class="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.4</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
</div></div>
<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div><p>If true (the default), then Tapestry will use a lock when reading/updating HttpSession attributes, to avoid simultaneous access by multiple threads when using AJAX. See <a class="external-link" href="https://issues.apache.org/jira/browse/TAP5-2049">TAP5-2049</a>. Set to false to deactivate the session locking logic.</p><p>Prior to version 5.4 session locking was not performed.</p><h3 id="Configuration-tapestry.start-page-name(SymbolConstants.START_PAGE_NAME)">tapestry.start-page-name (SymbolConstants.START_PAGE_NAME)</h3><p>The logical name of the start page, the page that is rendered for the <em>root URL</em>. This is normally "start". This functionality is vestigial: it has been superseded by the use of Index pages.</p><p><span class="confluence-anchor-link" id="Configuration-supported-locales"></span></p><h3 id="Configuration-tapestry.strict-css-url-rewriting(SymbolConstants.STRICT_CSS_URL_REWRITING)">tapestry.strict-css-url-rewriting (SymbolConstants.STRIC
T_CSS_URL_REWRITING)</h3><p>Controls whether to throw an exception (true) or log a warning (false) when Tapestry encounters a URL reference to a non-existing file within a CSS file. The default is false.</p><h3 id="Configuration-tapestry.supported-locales(SymbolConstants.SUPPORTED_LOCALES)">tapestry.supported-locales (SymbolConstants.SUPPORTED_LOCALES)</h3><p>A comma-separated list of supported locales. Incoming requests as "narrowed" to one of these locales, based on closest match. If no match can be found, the first locale in the list is treated as the default.</p><p>The default is (currently) "en,it,es,zh_CN,pt_PT,de,ru,hr,fi_FI,sv_SE,fr_FR,da,pt_BR,ja,el". As the community contributes new localizations of the necessary messages files, this list will expand. Note that the Tapestry quickstart archetype overrides the factory default, forcing the application to be localized only for "en".</p><h3 id="Configuration-tapestry.suppress-redirect-from-action-requests(SymbolConstants.SUPPRE
SS_REDIRECT_FROM_ACTION_REQUESTS)">tapestry.suppress-redirect-from-action-requests (SymbolConstants.SUPPRESS_REDIRECT_FROM_ACTION_REQUESTS)</h3>
+<p> </p></div><p>If true (the default), then Tapestry will use a lock when reading/updating HttpSession attributes, to avoid simultaneous access by multiple threads when using AJAX. See <a class="external-link" href="https://issues.apache.org/jira/browse/TAP5-2049">TAP5-2049</a>. Set to false to deactivate the session locking logic.</p><p>Prior to version 5.4 session locking was not performed.</p><h3 id="Configuration-tapestry.start-page-name(SymbolConstants.START_PAGE_NAME)">tapestry.start-page-name (SymbolConstants.START_PAGE_NAME)</h3><p>The logical name of the start page, the page that is rendered for the <em>root URL</em>. This is normally "start". This functionality is vestigial: it has been superseded by the use of Index pages.</p><p><parameter ac:name="">supported-locales</parameter></p><h3 id="Configuration-tapestry.strict-css-url-rewriting(SymbolConstants.STRICT_CSS_URL_REWRITING)">tapestry.strict-css-url-rewriting (SymbolConstants.STRICT_CSS_URL_REWRITING)</h3><p>Co
ntrols whether to throw an exception (true) or log a warning (false) when Tapestry encounters a URL reference to a non-existing file within a CSS file. The default is false.</p><h3 id="Configuration-tapestry.supported-locales(SymbolConstants.SUPPORTED_LOCALES)">tapestry.supported-locales (SymbolConstants.SUPPORTED_LOCALES)</h3><p>A comma-separated list of supported locales. Incoming requests as "narrowed" to one of these locales, based on closest match. If no match can be found, the first locale in the list is treated as the default.</p><p>The default is (currently) "en,it,es,zh_CN,pt_PT,de,ru,hr,fi_FI,sv_SE,fr_FR,da,pt_BR,ja,el". As the community contributes new localizations of the necessary messages files, this list will expand. Note that the Tapestry quickstart archetype overrides the factory default, forcing the application to be localized only for "en".</p><h3 id="Configuration-tapestry.suppress-redirect-from-action-requests(SymbolConstants.SUPPRESS_REDIRECT_FROM_ACTION_REQUES
TS)">tapestry.suppress-redirect-from-action-requests (SymbolConstants.SUPPRESS_REDIRECT_FROM_ACTION_REQUESTS)</h3>
<div class="confluence-information-macro confluence-information-macro-warning"><p class="title">Deprecated since 5.2</p><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
</div></div>
@@ -374,17 +285,12 @@ div.rbtoc1499639540986 li {margin-left:
configuration.add(ComponentParameterConstants.GRID_ROWS_PER_PAGE, "15");
</pre>
</div></div>
-</div><p>See the complete list of such constants at <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentParameterConstants.html">ComponentParameterConstants</a>.</p><h2 id="Configuration-ConfiguringIgnoredPaths">Configuring Ignored Paths</h2><p>You may sometimes need to use Tapestry in concert with other servlets. This can cause problems, since Tapestry (being a servlet filter) may see URLs intended for another servlet and attempt to process them.</p><p>The Servlet API does not provide Tapestry with any clues about what other servlets are available in the web application. Instead, you must configure Tapestry to ignore paths intended for other servlets.</p><p>The IgnoredPathsFilter service is the method for this kind of configuration. Its configuration is an unordered collection of regular expression patterns. A request whose path matches any of these patterns is <strong>not</strong> processed by Tapestry.</p><p>For example, say yo
u are using <a class="external-link" href="http://getahead.org/dwr/" rel="nofollow">Direct Web Remoting</a>. You'll likely have the servlet path /dwr mapped to the Direct Web Remoting servlet.</p><p>You contribution would look like:</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 static void contributeIgnoredPathsFilter(Configuration<String> configuration)
+</div><p>See the complete list of such constants at <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentParameterConstants.html">ComponentParameterConstants</a>.</p><h2 id="Configuration-ConfiguringIgnoredPaths">Configuring Ignored Paths</h2><p>You may sometimes need to use Tapestry in concert with other servlets. This can cause problems, since Tapestry (being a servlet filter) may see URLs intended for another servlet and attempt to process them.</p><p>The Servlet API does not provide Tapestry with any clues about what other servlets are available in the web application. Instead, you must configure Tapestry to ignore paths intended for other servlets.</p><p>The IgnoredPathsFilter service is the method for this kind of configuration. Its configuration is an unordered collection of regular expression patterns. A request whose path matches any of these patterns is <strong>not</strong> processed by Tapestry.</p><p>For example, say yo
u are using <a class="external-link" href="http://getahead.org/dwr/" rel="nofollow">Direct Web Remoting</a>. You'll likely have the servlet path /dwr mapped to the Direct Web Remoting servlet.</p><p>You contribution would look like:</p><parameter ac:name="language">java</parameter><plain-text-body> public static void contributeIgnoredPathsFilter(Configuration<String> configuration)
{
configuration.add("/dwr/.*");
}
-</pre>
-</div></div><p>The regular expression matches any path that begins with "/dwr/".</p><p>The regular expressions provided in the configuration are always compiled with case insensitivity enabled.</p><p>Also note that actual files in your web application (images, stylesheets, etc.) are always ignored by Tapestry.</p><h2 id="Configuration-ConfiguringContentTypeMapping">Configuring Content Type Mapping</h2><p>The mapping from file type (by extension) to content type is typically done as part of your servlet-containers configuration. Alternately, you may contribute to the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/ResourceStreamer.html">ResourceStreamer</a> service's configuration. This is a mapped configuration; it maps file extensions (such as "css" or "js") to content types ("text/css" or "text/javascript") respectively.</p><h2 id="Configuration-SettingExecutionModes">Setting Execution Modes</h2><p>Starting with Tap
estry 5.2.4, we can specify an <em>execution mode</em> by loading specific Tapestry Modules through a JVM System property. All modules declared in this way will be loaded after the AppModule of your application. This feature is very useful for defining a different environment for Production and Development modes, for example.</p><p>This JVM System property, named tapestry.execution-mode, is a comma-separated list of mode names. You can declare this property in a number of different ways:</p><p>1. Add the parameter to your JVM command line:</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;">-Dtapestry.execution-mode=uat jetty:run
-</pre>
-</div></div><p>2. Add the parameter to the Jetty plugin:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><plugin>
+</plain-text-body><p>The regular expression matches any path that begins with "/dwr/".</p><p>The regular expressions provided in the configuration are always compiled with case insensitivity enabled.</p><p>Also note that actual files in your web application (images, stylesheets, etc.) are always ignored by Tapestry.</p><h2 id="Configuration-ConfiguringContentTypeMapping">Configuring Content Type Mapping</h2><p>The mapping from file type (by extension) to content type is typically done as part of your servlet-containers configuration. Alternately, you may contribute to the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/ResourceStreamer.html">ResourceStreamer</a> service's configuration. This is a mapped configuration; it maps file extensions (such as "css" or "js") to content types ("text/css" or "text/javascript") respectively.</p><h2 id="Configuration-SettingExecutionModes">Setting Execution Modes</h2><p>Starting wi
th Tapestry 5.2.4, we can specify an <em>execution mode</em> by loading specific Tapestry Modules through a JVM System property. All modules declared in this way will be loaded after the AppModule of your application. This feature is very useful for defining a different environment for Production and Development modes, for example.</p><p>This JVM System property, named tapestry.execution-mode, is a comma-separated list of mode names. You can declare this property in a number of different ways:</p><p>1. Add the parameter to your JVM command line:</p><plain-text-body>-Dtapestry.execution-mode=uat jetty:run
+</plain-text-body><p>2. Add the parameter to the Jetty plugin:</p><parameter ac:name="language">xml</parameter><parameter ac:name="title">pom.xml</parameter><plain-text-body><plugin>
<groupId>org.mortbay.jetty</groupId>
<artifactId>maven-jetty-plugin</artifactId>
<version>6.1.16</version>
@@ -400,9 +306,7 @@ configuration.add(ComponentParameterCons
</systemProperties>
</configuration>
</plugin>
-</pre>
-</div></div><p>3. Add the parameter to the Surefire plugin for your test:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><plugin>
+</plain-text-body><p>3. Add the parameter to the Surefire plugin for your test:</p><parameter ac:name="language">xml</parameter><parameter ac:name="title">pom.xml</parameter><plain-text-body><plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.8.1</version>
@@ -412,9 +316,7 @@ configuration.add(ComponentParameterCons
</systemPropertyVariables>
</configuration>
</plugin>
-</pre>
-</div></div><p>For each mode declared in your JVM System Property, TapestryFilter checks for a parameter in your web.xml, named tapestry.TheModeName-modules, with TheModeName being the name of the desired mode. Its value will be a comma-separated list of modules.</p><p>If the tapestry.execution-mode is not declared, Tapestry will automatically look for the tapestry.production-modules parameter, because “production” is the default tapestry.execution-mode value.</p><p>The example below defines two different execution modes in your web.xml file: production (the default value) and uat (for "user acceptance testing"). For each mode, we list the modules we want to load. If we use JVM System property declared in the example above, the UatModeModule module will be loaded.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>web.xml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><context-param>
+</plain-text-body><p>For each mode declared in your JVM System Property, TapestryFilter checks for a parameter in your web.xml, named tapestry.TheModeName-modules, with TheModeName being the name of the desired mode. Its value will be a comma-separated list of modules.</p><p>If the tapestry.execution-mode is not declared, Tapestry will automatically look for the tapestry.production-modules parameter, because “production” is the default tapestry.execution-mode value.</p><p>The example below defines two different execution modes in your web.xml file: production (the default value) and uat (for "user acceptance testing"). For each mode, we list the modules we want to load. If we use JVM System property declared in the example above, the UatModeModule module will be loaded.</p><parameter ac:name="language">xml</parameter><parameter ac:name="title">web.xml</parameter><plain-text-body><context-param>
<param-name>tapestry.production-modules</param-name>
<param-value>com.example.myapp.services.ProductionModeModule</param-value>
</context-param>
@@ -427,24 +329,18 @@ configuration.add(ComponentParameterCons
<param-name>tapestry.integration-modules</param-name>
<param-value>com.example.myapp.services.IntegrationModeModule</param-value>
</context-param>
-</pre>
-</div></div><p>Execution mode itself may be a comma separated list:</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;">-Dtapestry.execution-mode=uat,integration jetty:run
-</pre>
-</div></div><p><span style="color: rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Segregating Applications Into Folders</span></p><p>In many cases where Tapestry is being adopted into an existing web application (possibly written in Tapestry 4 or some other framework), it is nice to segregate the Tapestry application into its own folder, to avoid conflicts with the existing application or servlets.</p>
+</plain-text-body><p>Execution mode itself may be a comma separated list:</p><plain-text-body>-Dtapestry.execution-mode=uat,integration jetty:run
+</plain-text-body><p><span style="color: rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Segregating Applications Into Folders</span></p><p>In many cases where Tapestry is being adopted into an existing web application (possibly written in Tapestry 4 or some other framework), it is nice to segregate the Tapestry application into its own folder, to avoid conflicts with the existing application or servlets.</p>
<div class="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.3</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
</div></div>
<div class="error"><span class="error">Unknown macro: {div}</span>
<p>Support for application folders was added in release 5.3.</p>
-</div><p>Setting this up is in two parts:</p><ul><li>Modifying the configuration of the <code><url-pattern></code> for the Tapestry filter to match the specified folder.</li><li>Identifying the folder name using a Tapestry symbol value contribution.</li></ul><p>So, if you wanted to run the Tapestry application inside folder <code>t5app</code>, you would modify your <code>web.xml</code> indicate the use of the folder:</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;"> <filter-mapping>
+</div><p>Setting this up is in two parts:</p><ul><li>Modifying the configuration of the <code><url-pattern></code> for the Tapestry filter to match the specified folder.</li><li>Identifying the folder name using a Tapestry symbol value contribution.</li></ul><p>So, if you wanted to run the Tapestry application inside folder <code>t5app</code>, you would modify your <code>web.xml</code> indicate the use of the folder:</p><parameter ac:name="language">xml</parameter><plain-text-body> <filter-mapping>
<filter-name>app</filter-name>
<url-pattern>/t5app/*</url-pattern>
</filter-mapping>
-</pre>
-</div></div><p>... and in your AppModule, you would inform Tapestry about the mapping change:</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 AppModule
+</plain-text-body><p>... and in your AppModule, you would inform Tapestry about the mapping change:</p><parameter ac:name="language">java</parameter><plain-text-body>public class AppModule
{
@Contribute(SymbolProvider.class)
@ApplicationDefaults
@@ -453,8 +349,7 @@ configuration.add(ComponentParameterCons
configuration.add(SymbolConstants.APPLICATION_FOLDER, "t5app")
}
}
-</pre>
-</div></div><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>This extra mapping is unfortunately necessary, because the Servlet API does not provide a way for a servlet filter, such as the one used by Tapestry, to know about its mapping.</p></div></div><p>This changes the servlet container to <em>only</em> forward requests inside the <code>t5app</code> folder to Tapestry; requests for other folders (or the root folder) will not be passed to Tapestry at all. The symbol contribution informs Tapestry to change the URLs it generates to include the necessary folder name; it also affects the logic in Tapestry that recognizes and handles requests.</p><p>In addition, if you choose to place page template files in the context, rather than on the classpath (as with component templates), then you will place those tem
plate files inside the <code>t5app</code> folder.</p><p>At this time, it is still not possible to run multiple Tapestry 5 applications within the same web application.</p></div>
+</plain-text-body><rich-text-body><p>This extra mapping is unfortunately necessary, because the Servlet API does not provide a way for a servlet filter, such as the one used by Tapestry, to know about its mapping.</p></rich-text-body><p>This changes the servlet container to <em>only</em> forward requests inside the <code>t5app</code> folder to Tapestry; requests for other folders (or the root folder) will not be passed to Tapestry at all. The symbol contribution informs Tapestry to change the URLs it generates to include the necessary folder name; it also affects the logic in Tapestry that recognizes and handles requests.</p><p>In addition, if you choose to place page template files in the context, rather than on the classpath (as with component templates), then you will place those template files inside the <code>t5app</code> folder.</p><p>At this time, it is still not possible to run multiple Tapestry 5 applications within the same web application.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/confluence-site-setup.html
==============================================================================
--- websites/production/tapestry/content/confluence-site-setup.html (original)
+++ websites/production/tapestry/content/confluence-site-setup.html Sat Sep 16 02:22:40 2017
@@ -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">Confluence Site Setup</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">Confluence Site Setup</h1></div>
+
+</div>
<div class="clearer"></div>
</div>
@@ -54,43 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>This document describes our web site setup: what is where and how it works.</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="building-tapestry-from-source.html">Building Tapestry from Source</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="version-numbers.html">Version Numbers</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="developer-bible.html">Developer Bible</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="release-process.html">Release Process</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="developer-information.html">Developer Information</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="confluence-site-setup.html">Confluence Site Setup</a>
- </div> </li></ul></div><h1 id="ConfluenceSiteSetup-Overview">Overview</h1><p>Most of the web site and documentation (with the notable exception of the Javadoc API pages) are kept in Confluence.</p><p>Since the Confluence instance at <a class="external-link" href="https://cwiki.apache.org/confluence/">https://cwiki.apache.org/confluence/</a> isn't capable of handling a lot of incoming requests, all wiki spaces are statically exported. The SiteExporter program is responsible for that. Once a page in Confluence changes, that page gets re-exported automatically.</p><h2 id="ConfluenceSiteSetup-HowSiteExporterworks">How SiteExporter works</h2><p><em>For more details see the <a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/README">SiteExporter README</a>.</em></p><p>SiteExporter is a command-line Java program that is run hourly (currently at 19 minutes after the hour) from Apache's BuildBot. It makes a web service call to Confluence (to its R
SS feed, actually) to get a list of pages that have changed since the last run, and the HTML-formatted export of those pages. For each, it post-processes the file (described below). Finally, SiteExporter commits all changed HTML files into Tapestry's part of the Apache Subversion repository, which (nearly instantly) makes it available to the public at <a class="external-link" href="http://tapestry.apache.org">http://tapestry.apache.org</a>, and commit emails are sent to Tapestry's "commits" mailing list.</p><p>Attachments (to Confluence pages) are exported in roughly the same way.</p><p>The time between saving a change in Confluence and seeing the result on the public site is at most 1 hour, depending on when you do it. If you save a change at 18 minutes after the hour you'll see the change in about a minute. If you publish it at 20 minutes after the hour then you'll have to wait almost an hour.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" ro
wspan="1" class="confluenceTd"><p>HTML files in SVN</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/infra/websites/production/tapestry">https://svn.apache.org/repos/infra/websites/production/tapestry</a></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Cache File</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache">https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache</a></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>SiteExporter source</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk">https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk</a></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p
>Velocity template</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm">https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm</a></td></tr></tbody></table></div><h3 id="ConfluenceSiteSetup-Post-processingHTMLPages">Post-processing HTML Pages</h3><p>HTML pages exported from Confluence are post-processed in several ways before being committed to SVN. Here are just a few of the things going on:</p><ul><li>Tagsoup is used to clean up the HTML.</li><li>The breadcrumb links are updated.</li><li>Empty paragraph (<p>) tags are removed from the top of the page.</li><li>{code} macro output (code examples) are detected, and SyntaxHighlighter JavaScript links are added to the page when needed.</li><li>{include} tags (when one Confluence page includes another) are detected, causing the <em>including</em> page to be regenerated autoamtically.</
li><li>{children} tags are also detected and handled</li></ul><h2 id="ConfluenceSiteSetup-ManualIntervention">Manual Intervention</h2><p>You can cause the <em>whole site</em> to be republished by deleting the main.pageCache file (above) in the subversion repo. This is usually only needed after changing the template.</p><h2 id="ConfluenceSiteSetup-ChangingSiteExporteritself">Changing SiteExporter itself</h2><p>Currently the SiteExporter source code is an unmodified copy of a program of the same name written by Dan Kulp for the Apache CXF project and also used by Camel, Geronimo, and Struts (and possibly others). It can be customized, but proceed with caution, because any customizations will make it harder to pull in future changes from the original CXF SiteExporter code. The CXF SiteExporter is likely to change as Confluence versions change.</p><p>To pick up changes to the original CXF SiteExporter code, just compare <a class="external-link" href="https://svn.apache.org/repos/asf/ta
pestry/tapestry-site/trunk/src/main/java/org/apache/cxf/cwiki">the Tapestry source code</a> with <a class="external-link" href="http://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/">the CXF source code</a>.</p><hr><h1 id="ConfluenceSiteSetup-WikiFormattingGuidelines">Wiki Formatting Guidelines</h1><ul><li>Precede annotation names with '@'. If the annotation name is hyperlinked, put the '@' character <em>outside</em> of the link: @[AnnotationType|http://...AnnotationType.html]</li><li>The first reference to a type on a page should be a link to <a class="external-link" href="http://tapestry.apache.org/current/apidocs/">http://tapestry.apache.org/current/apidocs/</a>... (or the component reference)</li><li>Treat the page title as if it were an h0. element, and put top level sections within the page as h1.</li><li>Page names as headings should have All Words Captialized.</li><li>For other headings, only the first word of multi-word headings should be capitalized
, e.g. "h2. Naming conventions" (following Wikipedia)</li><li>Use <code>code</code> font for method and property names: <code>myProperty</code>, <code>someMethod()</code>.</li><li>Use the default font for Class names (qualified or not).</li><li>Use the default font for path names.</li><li>Use {code} for listings, not {noformat}.</li><li>Use {noformat} for console output.</li><li>Images and diagrams should be small-sized thumbnails, centered, with no border.</li><li>Use the <a href="since-and-deprecated-user-macros.html">Since and Deprecated</a> macros to mark new or deprecated features.</li><li><em>Proposed: Each page should include explicit links to its child pages. Don't rely on the "Child Pages" links at the bottom, which don't carry over to the exported site.</em></li><li><em>Proposed: In pages other than the User Guide pages, subsections that briefly discuss topics that are more fully covered in the User Guide should lead with a "Main Article: [Foo]" line, where Foo is the nam
e of the page in the User Guide. Example: the "Template Localization" section of <a href="component-templates.html">Component Templates</a></em></li><li><em>Proposed: User Guide pages should generally start with a right-floated "Related Articles" box that provides links to related content in the FAQ, Cookbook, Cheat Sheets, etc. <a href="component-classes.html">Example</a></em></li><li><em>Proposed: The lead paragraph should generally lead with the title word or phrase in bold (following Wikipedia)</em></li></ul><h1 id="ConfluenceSiteSetup-Websitestructure">Website structure</h1><p>The <a href="index.html">Index</a> page includes the <a href="banner.html">Banner</a> and <a href="key-features.html">Key Features</a> pages as well as the blog posts. Most other pages are just plain pages and may or may not include other parts. In addition the <a href="navigation.html">Navigation</a>, <a href="small-banner.html">Small Banner</a> and <a href="footer.html">Footer</a> pages exist.</
p><p>Our SiteExporter template (described above) glues everything together. It adds the contents of the <a href="navigation.html">Navigation</a> and <a href="footer.html">Footer</a> pages in the appropriate places and on all pages except the <a href="index.html">Index</a> page. It also adds the contents of the <a href="small-banner.html">Small Banner</a> page as well as the breadcrumbs navigation.</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>HLS: I've noticed that pages with footnotes that are combined with the {include} macro do not render correctly ... the footnote numbers and anchors reset back to 1 for each included page. Perhaps there's a way to fix that with the template?</p></div></div><h1 id="ConfluenceSiteSetup-Updatingthetemplate">Updating the template</h1><p>You must be a Tapestry commi
tter or otherwise have write access to the subversion repository (see link above).</p><p>To edit the template:</p><ol><li>check out the SiteExporter source project (see link above)</li><li>find and edit the template.vm file</li><li>commit your changes</li></ol></div>
+ <div id="ConfluenceContent"><p>This document describes our web site setup: what is where and how it works.</p><parameter ac:name="style">float:right</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="class">aui-label</parameter><rich-text-body><parameter ac:name="showLabels">false</parameter><parameter ac:name="showSpace">false</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="cql">label = "tapestry-dev" and space = currentSpace()</parameter></rich-text-body><h1 id="ConfluenceSiteSetup-Overview">Overview</h1><p>Most of the web site and documentation (with the notable exception of the Javadoc API pages) are kept in Confluence.</p><p>Since the Confluence instance at <a class="external-link" href="https://cwiki.apache.org/confluence/">https://cwiki.apache.org/confluence/</a> isn't capable of handling a lot of incoming requests, all wiki spaces are statically exported. The SiteExporter program is res
ponsible for that. Once a page in Confluence changes, that page gets re-exported automatically.</p><h2 id="ConfluenceSiteSetup-HowSiteExporterworks">How SiteExporter works</h2><p><em>For more details see the <a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/README">SiteExporter README</a>.</em></p><p>SiteExporter is a command-line Java program that is run hourly (currently at 19 minutes after the hour) from Apache's BuildBot. It makes a web service call to Confluence (to its RSS feed, actually) to get a list of pages that have changed since the last run, and the HTML-formatted export of those pages. For each, it post-processes the file (described below). Finally, SiteExporter commits all changed HTML files into Tapestry's part of the Apache Subversion repository, which (nearly instantly) makes it available to the public at <a class="external-link" href="http://tapestry.apache.org">http://tapestry.apache.org</a>, and commit emails are sent
to Tapestry's "commits" mailing list.</p><p>Attachments (to Confluence pages) are exported in roughly the same way.</p><p>The time between saving a change in Confluence and seeing the result on the public site is at most 1 hour, depending on when you do it. If you save a change at 18 minutes after the hour you'll see the change in about a minute. If you publish it at 20 minutes after the hour then you'll have to wait almost an hour.</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>HTML files in SVN</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/infra/websites/production/tapestry">https://svn.apache.org/repos/infra/websites/production/tapestry</a></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Cache File</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/infr
a/websites/production/tapestry/content/cache/main.pageCache">https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache</a></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>SiteExporter source</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk">https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk</a></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>Velocity template</p></td><td colspan="1" rowspan="1" class="confluenceTd"><a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm">https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm</a></td></tr></tbody></table></div><h3 id="ConfluenceSiteSetup-Post-processingHTMLPages">Post-processing HTML Pages</h3><p>HTML pages exported from Confluence are post-processed in several ways bef
ore being committed to SVN. Here are just a few of the things going on:</p><ul><li>Tagsoup is used to clean up the HTML.</li><li>The breadcrumb links are updated.</li><li>Empty paragraph (<p>) tags are removed from the top of the page.</li><li>{code} macro output (code examples) are detected, and SyntaxHighlighter JavaScript links are added to the page when needed.</li><li>{include} tags (when one Confluence page includes another) are detected, causing the <em>including</em> page to be regenerated autoamtically.</li><li>{children} tags are also detected and handled</li></ul><h2 id="ConfluenceSiteSetup-ManualIntervention">Manual Intervention</h2><p>You can cause the <em>whole site</em> to be republished by deleting the main.pageCache file (above) in the subversion repo. This is usually only needed after changing the template.</p><h2 id="ConfluenceSiteSetup-ChangingSiteExporteritself">Changing SiteExporter itself</h2><p>Currently the SiteExporter source code is an unmodified cop
y of a program of the same name written by Dan Kulp for the Apache CXF project and also used by Camel, Geronimo, and Struts (and possibly others). It can be customized, but proceed with caution, because any customizations will make it harder to pull in future changes from the original CXF SiteExporter code. The CXF SiteExporter is likely to change as Confluence versions change.</p><p>To pick up changes to the original CXF SiteExporter code, just compare <a class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/src/main/java/org/apache/cxf/cwiki">the Tapestry source code</a> with <a class="external-link" href="http://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/">the CXF source code</a>.</p><hr><h1 id="ConfluenceSiteSetup-WikiFormattingGuidelines">Wiki Formatting Guidelines</h1><ul><li>Precede annotation names with '@'. If the annotation name is hyperlinked, put the '@' character <em>outside</em> of the link: @[AnnotationTyp
e|http://...AnnotationType.html]</li><li>The first reference to a type on a page should be a link to <a class="external-link" href="http://tapestry.apache.org/current/apidocs/">http://tapestry.apache.org/current/apidocs/</a>... (or the component reference)</li><li>Treat the page title as if it were an h0. element, and put top level sections within the page as h1.</li><li>Page names as headings should have All Words Captialized.</li><li>For other headings, only the first word of multi-word headings should be capitalized, e.g. "h2. Naming conventions" (following Wikipedia)</li><li>Use <code>code</code> font for method and property names: <code>myProperty</code>, <code>someMethod()</code>.</li><li>Use the default font for Class names (qualified or not).</li><li>Use the default font for path names.</li><li>Use {code} for listings, not {noformat}.</li><li>Use {noformat} for console output.</li><li>Images and diagrams should be small-sized thumbnails, centered, with no border.</li><li>Us
e the <a href="since-and-deprecated-user-macros.html">Since and Deprecated</a> macros to mark new or deprecated features.</li><li><em>Proposed: Each page should include explicit links to its child pages. Don't rely on the "Child Pages" links at the bottom, which don't carry over to the exported site.</em></li><li><em>Proposed: In pages other than the User Guide pages, subsections that briefly discuss topics that are more fully covered in the User Guide should lead with a "Main Article: [Foo]" line, where Foo is the name of the page in the User Guide. Example: the "Template Localization" section of <a href="component-templates.html">Component Templates</a></em></li><li><em>Proposed: User Guide pages should generally start with a right-floated "Related Articles" box that provides links to related content in the FAQ, Cookbook, Cheat Sheets, etc. <a href="component-classes.html">Example</a></em></li><li><em>Proposed: The lead paragraph should generally lead with the title word or phr
ase in bold (following Wikipedia)</em></li></ul><h1 id="ConfluenceSiteSetup-Websitestructure">Website structure</h1><p>The <a href="index.html">Index</a> page includes the <a href="banner.html">Banner</a> and <a href="key-features.html">Key Features</a> pages as well as the blog posts. Most other pages are just plain pages and may or may not include other parts. In addition the <a href="navigation.html">Navigation</a>, <a href="small-banner.html">Small Banner</a> and <a href="footer.html">Footer</a> pages exist.</p><p>Our SiteExporter template (described above) glues everything together. It adds the contents of the <a href="navigation.html">Navigation</a> and <a href="footer.html">Footer</a> pages in the appropriate places and on all pages except the <a href="index.html">Index</a> page. It also adds the contents of the <a href="small-banner.html">Small Banner</a> page as well as the breadcrumbs navigation.</p><rich-text-body><p>HLS: I've noticed that pages with footnotes t
hat are combined with the {include} macro do not render correctly ... the footnote numbers and anchors reset back to 1 for each included page. Perhaps there's a way to fix that with the template?</p></rich-text-body><h1 id="ConfluenceSiteSetup-Updatingthetemplate">Updating the template</h1><p>You must be a Tapestry committer or otherwise have write access to the subversion repository (see link above).</p><p>To edit the template:</p><ol><li>check out the SiteExporter source project (see link above)</li><li>find and edit the template.vm file</li><li>commit your changes</li></ol></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/creating-the-skeleton-application.html
==============================================================================
--- websites/production/tapestry/content/creating-the-skeleton-application.html (original)
+++ websites/production/tapestry/content/creating-the-skeleton-application.html Sat Sep 16 02:22:40 2017
@@ -27,14 +27,6 @@
</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/shBrushXml.js' type='text/javascript'></script>
- <script>
- SyntaxHighlighter.defaults['toolbar'] = false;
- SyntaxHighlighter.all();
- </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -75,8 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>First, let's create an empty application. Tapestry provides a Maven <strong>archetype</strong> (a project template) to make this easy.</p><p>For the tutorial, we're using a fresh install of Eclipse and an empty workspace at <code>/users/joeuser/workspace</code>. You may need to adjust a few things for other operating systems or local paths.</p><h2 id="CreatingTheSkeletonApplication-UsingtheQuickstartArchetype">Using the Quickstart Archetype</h2><p>From Eclipse, we'll use a Maven archetype to create a skeleton Tapestry project.</p><h3 id="CreatingTheSkeletonApplication-MavenBehindaFirewall">Maven Behind a Firewall</h3><p>If you are behind a firewall/proxy, before performing any Maven downloads, you may need to configure your proxy settings in your Maven settings.xml file (typically in the .m2 subdirectory of your home directory, ~/.m2 or C:\users\joeuser\.m2). Here is an example (but check with your network administrator for the names an
d numbers you should use here).</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>settings.xml</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;"><settings>
+ <div id="ConfluenceContent"><p>First, let's create an empty application. Tapestry provides a Maven <strong>archetype</strong> (a project template) to make this easy.</p><p>For the tutorial, we're using a fresh install of Eclipse and an empty workspace at <code>/users/joeuser/workspace</code>. You may need to adjust a few things for other operating systems or local paths.</p><h2 id="CreatingTheSkeletonApplication-UsingtheQuickstartArchetype">Using the Quickstart Archetype</h2><p>From Eclipse, we'll use a Maven archetype to create a skeleton Tapestry project.</p><h3 id="CreatingTheSkeletonApplication-MavenBehindaFirewall">Maven Behind a Firewall</h3><p>If you are behind a firewall/proxy, before performing any Maven downloads, you may need to configure your proxy settings in your Maven settings.xml file (typically in the .m2 subdirectory of your home directory, ~/.m2 or C:\users\joeuser\.m2). Here is an example (but check with your network administrator for the names an
d numbers you should use here).</p><parameter ac:name="language">xml</parameter><parameter ac:name="title">settings.xml</parameter><plain-text-body><settings>
<proxies>
<proxy>
<active>true</active>
@@ -90,11 +81,7 @@
</proxies>
<localRepository>C:/Users/joeuser/.m2/repository</localRepository>
</settings>
-</pre>
-</div></div><p>Of course, adjust the <code>localRepository</code> element to match the correct path for your computer.</p><h3 id="CreatingTheSkeletonApplication-CreateProject">Create Project</h3><p>Okay, let's get started creating our new project.</p><p>In Eclipse, go to <strong>File > New ></strong> <strong>Project... > Maven > Maven Project</strong></p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/select-a-wizard.png"></span></p><p>Then click <strong>Next</strong>, <strong>Next</strong> (again), and then on the <strong>Select an Archetype</strong> page click the <strong>Configure</strong> button on the Catalog line. The <strong>Archetype</strong> preferences dialog should appear. Click the <strong>Add Remote Catalog...</strong> button, as shown below:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.dat
a/add-archetype-catalog.png"></span></p><p>As shown above, enter <span class="nolink"><span class="nolink">"http://tapestry.apache.org"</span></span> in the Catalog File field, and "Apache Tapestry" in the Description field.</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>If you want to try an unreleased (alpha or beta) version of Tapestry, use <span class="nolink">the <strong>https://repository.apache.org/content/repositories/staging</strong></span> archetype catalog file instead.</p></div></div><p>Click <strong>OK</strong>, then<strong> OK</strong> again.</p><p>On the Select an Archetype dialog (shown below), select the newly-added Apache Tapestry catalog, then select the "quickstart" artifact from the list and click <strong>Next</strong>.</p><p><span class="confluence-embedded-file-wrapper"><img cl
ass="confluence-embedded-image" src="creating-the-skeleton-application.data/select-archetype.png"></span></p><p><em><strong>Note:</strong> Screenshots in this tutorial may show different (either newer or older) versions of Tapestry than you may see.</em></p><p>Fill in the Group Id, Artifact Id, Version and Package  as follows:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/specify-archetype-parameters.png"></span></p><p>then click Finish.</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>The first time you use Maven, project creation may take a while as Maven downloads a large number of JAR dependencies for Maven, Jetty and Tapestry. These downloaded files are cached locally and will not need to be downloaded a
gain, but you do have to be patient on first use.</p></div></div><p>After Maven finishes, you'll see a new directory, <code>tutorial1, in your Package Explorer view in Eclipse.</code></p><h2 id="CreatingTheSkeletonApplication-RunningtheApplicationusingJetty">Running the Application using Jetty</h2><p>One of the first things you can do is use Maven to run Jetty directly.</p><p>Right-click on the <code>tutorial1</code> project in your Package Explorer view and select <strong>Run As > Maven Build... ></strong>, enter a Goal of <strong>"jetty:run"</strong>. This creates a "Run Configuration" named "tutorial1" that we'll use throughout this tutorial to start the app:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/run-configuration.png"></span></p><p>Tapestry runs best with a couple of additional options; click the "JRE" tab and enter the following VM Arguments:</p><pre></pre><p>-XX:MaxPermSize=
256M</p><p>-Xmx600m</p><p>-Dtapestry.execution-mode=development</p>
-
-
-<p><code><em>(If you're using JDK 1.8 then you should omit the MaxPermSize argument.)</em></code></p><p><code>Here's how it looks:<br clear="none"></code></p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/run-configuration-jre.png"></span></p><p>Finally, click <strong>Run</strong>.</p><p>Again, the first time, there's a dizzying number of downloads, but before you know it, the Jetty servlet container is up and running.</p><p>Once Jetty is initialized (which only takes a few seconds after the first time), you'll see the following in your console:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/console-startup.png"></span></p><p><em>Note the red square icon above. Later on you'll use that icon to stop Jetty before restarting the app.</em></p><p>You can now open a web browser to <a class="external-link" href="http
://localhost:8080/tutorial1/" rel="nofollow">http://localhost:8080/tutorial1/</a> to see the running application:</p><p> </p><p><span class="confluence-embedded-file-wrapper image-left-wrapper"><img class="confluence-embedded-image confluence-content-image-border image-left" src="creating-the-skeleton-application.data/startpage.png"></span></p><p> </p><div style="clear: both"></div><p style="text-align: left;"><strong><em>NOTE: Your screen may look very different depending on the version of Tapestry you are using!</em></strong></p><p style="text-align: left;">The date and time in the middle of the page shows that this is a live application.</p><p>This is a complete little web app; it doesn't do much, but it demonstrate how to create a number of pages sharing a common layout, and demonstrates some simple navigation and link handling. You can see that it has several different pages that share a common layout. (<span style="line-height: 1.4285715;"><em>Layout</em> is a loose
term meaning common look and feel and navigation across many or all of the pages of an application. Often an application will include a Layout component to provide that commonness.)</span></p><p><span style="line-height: 1.4285715;">Next: <a href="exploring-the-project.html">Exploring the Project</a></span></p><p><span style="line-height: 1.4285715;"><br clear="none"></span></p></div>
+</plain-text-body><p>Of course, adjust the <code>localRepository</code> element to match the correct path for your computer.</p><h3 id="CreatingTheSkeletonApplication-CreateProject">Create Project</h3><p>Okay, let's get started creating our new project.</p><p>In Eclipse, go to <strong>File > New ></strong> <strong>Project... > Maven > Maven Project</strong></p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/select-a-wizard.png"></span></p><p>Then click <strong>Next</strong>, <strong>Next</strong> (again), and then on the <strong>Select an Archetype</strong> page click the <strong>Configure</strong> button on the Catalog line. The <strong>Archetype</strong> preferences dialog should appear. Click the <strong>Add Remote Catalog...</strong> button, as shown below:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-applicati
on.data/add-archetype-catalog.png"></span></p><p>As shown above, enter <span class="nolink"><span class="nolink">"http://tapestry.apache.org"</span></span> in the Catalog File field, and "Apache Tapestry" in the Description field.</p><rich-text-body><p>If you want to try an unreleased (alpha or beta) version of Tapestry, use <span class="nolink">the <strong>https://repository.apache.org/content/repositories/staging</strong></span> archetype catalog file instead.</p></rich-text-body><p>Click <strong>OK</strong>, then<strong> OK</strong> again.</p><p>On the Select an Archetype dialog (shown below), select the newly-added Apache Tapestry catalog, then select the "quickstart" artifact from the list and click <strong>Next</strong>.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/select-archetype.png"></span></p><p><em><strong>Note:</strong> Screenshots in this tutorial may show different (either newer
or older) versions of Tapestry than you may see.</em></p><p>Fill in the Group Id, Artifact Id, Version and Package  as follows:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/specify-archetype-parameters.png"></span></p><p>then click Finish.</p><rich-text-body><p>The first time you use Maven, project creation may take a while as Maven downloads a large number of JAR dependencies for Maven, Jetty and Tapestry. These downloaded files are cached locally and will not need to be downloaded again, but you do have to be patient on first use.</p></rich-text-body><p>After Maven finishes, you'll see a new directory, <code>tutorial1, in your Package Explorer view in Eclipse.</code></p><h2 id="CreatingTheSkeletonApplication-RunningtheApplicationusingJetty">Running the Application using Jetty</h2><p>One of the first things you can do is use Maven to run Jetty directly.</p><p>Right-click on the <code>tu
torial1</code> project in your Package Explorer view and select <strong>Run As > Maven Build... ></strong>, enter a Goal of <strong>"jetty:run"</strong>. This creates a "Run Configuration" named "tutorial1" that we'll use throughout this tutorial to start the app:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/run-configuration.png"></span></p><p>Tapestry runs best with a couple of additional options; click the "JRE" tab and enter the following VM Arguments:</p><rich-text-body><p>-XX:MaxPermSize=256M</p><p>-Xmx600m</p><p>-Dtapestry.execution-mode=development</p></rich-text-body><p><code><em>(If you're using JDK 1.8 then you should omit the MaxPermSize argument.)</em></code></p><p><code>Here's how it looks:<br clear="none"></code></p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/run-configuration-jre.png"
></span></p><p>Finally, click <strong>Run</strong>.</p><p>Again, the first time, there's a dizzying number of downloads, but before you know it, the Jetty servlet container is up and running.</p><p>Once Jetty is initialized (which only takes a few seconds after the first time), you'll see the following in your console:</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="creating-the-skeleton-application.data/console-startup.png"></span></p><p><em>Note the red square icon above. Later on you'll use that icon to stop Jetty before restarting the app.</em></p><p>You can now open a web browser to <a class="external-link" href="http://localhost:8080/tutorial1/" rel="nofollow">http://localhost:8080/tutorial1/</a> to see the running application:</p><p> </p><p><span class="confluence-embedded-file-wrapper image-left-wrapper"><img class="confluence-embedded-image confluence-content-image-border image-left" src="creating-the-skeleton-applicati
on.data/startpage.png"></span></p><p> </p><parameter ac:name="atlassian-macro-output-type">BLOCK</parameter><plain-text-body><div style="clear: both"></div></plain-text-body><p style="text-align: left;"><strong><em>NOTE: Your screen may look very different depending on the version of Tapestry you are using!</em></strong></p><p style="text-align: left;">The date and time in the middle of the page shows that this is a live application.</p><p>This is a complete little web app; it doesn't do much, but it demonstrate how to create a number of pages sharing a common layout, and demonstrates some simple navigation and link handling. You can see that it has several different pages that share a common layout. (<span style="line-height: 1.4285715;"><em>Layout</em> is a loose term meaning common look and feel and navigation across many or all of the pages of an application. Often an application will include a Layout component to provide that commonness.)</span></p><p><span sty
le="line-height: 1.4285715;">Next: <a href="exploring-the-project.html">Exploring the Project</a></span></p><p><span style="line-height: 1.4285715;"><br clear="none"></span></p></div>
</div>
<div class="clearer"></div>