Author: buildbot
Date: Mon Feb 19 20:20:17 2018
New Revision: 1025622
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/about.html
websites/production/tapestry/content/building-tapestry-from-source.html
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/class-reloading.html
websites/production/tapestry/content/configuration.html
websites/production/tapestry/content/confluence-site-setup.html
websites/production/tapestry/content/creating-the-skeleton-application.html
websites/production/tapestry/content/documentation.html
websites/production/tapestry/content/exploring-the-project.html
websites/production/tapestry/content/getting-started.html
websites/production/tapestry/content/implementing-the-hi-lo-guessing-game.html
websites/production/tapestry/content/introduction.html
websites/production/tapestry/content/javascript-rewrite-in-54.html
websites/production/tapestry/content/release-notes-537.html
websites/production/tapestry/content/release-notes-538.html
websites/production/tapestry/content/release-notes-54.html
websites/production/tapestry/content/release-notes-542.html
websites/production/tapestry/content/release-notes-543.html
websites/production/tapestry/content/release-process.html
websites/production/tapestry/content/support.html
websites/production/tapestry/content/version-numbers.html
Modified: websites/production/tapestry/content/about.html
==============================================================================
--- websites/production/tapestry/content/about.html (original)
+++ websites/production/tapestry/content/about.html Mon Feb 19 20:20:17 2018
@@ -139,7 +139,7 @@
<h2 id="About-TrainingandSupport">Training and Support</h2>
-Apache Tapestry is an open source project and as such, supported by the
community. Even if you are looking for commercial support, your best bet for
support is to first subscribe to Apache Tapestry user mailing list and ask
there. Read more about how to <a href="support.html">get involved</a>.<h3
id="About-CommercialTrainingandSupport">Commercial Training and
Support</h3><p>Training on Tapestry and Support is available directly from the
source: the Tapestry project committers:</p><ul><li><a class="external-link"
href="http://www.arsmachina.com.br/services"; rel="nofollow">Thiago H. de Paula
Figueriredo</a>: Provides training and support on Tapestry and related
technologies including Spring and Hibernate</li></ul><h3
id="About-CommunitySupport">Community Support</h3><p>Like all Apache projects,
Tapestry uses mailing lists for most communication. You can subscribe by
sending e-mail to the addresses below. For each list, there are subscribe,
unsubscribe, and archive links. All Tapestr
y users are welcome to subscribe to any of these lists, however questions on
how to <em>use</em> Tapestry in your application are best sent to the
<em>user</em> mailing list.</p><p>Please note that the Nabble archives are set
to read-only and don't allow for posting or answering using Nabble's web
interface. You have to subscribe to the mailing list in order to post.</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><th colspan="1" rowspan="1"
class="confluenceTh"><p>Subscribe</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Unsubscribe</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Apache Archive</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Nabble Archive</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>MarkMail Archive</p></th></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Tapestry User List</p></th><td colspan="1"
rowspan="1" class=
"confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Subscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Unsubscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://mail-archives.apache.org/mod_mbox/tapestry-users/";>mail-archives.apache.org</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.1045711.n5.nabble.com/Tapestry-User-f2375125.html";
rel="nofollow">www.nabble.com</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.users";
rel="nofollow">tapestry.markmail.org</a></p></td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Tapestry Developer List</p></th><td
colspan="1" rowspan="1
" class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Subscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Unsubscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://mail-archives.apache.org/mod_mbox/tapestry-dev/";>mail-archives.apache.org</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.1045711.n5.nabble.com/Tapestry-Dev-f2438278.html";
rel="nofollow">www.nabble.com</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.dev";
rel="nofollow">tapestry.markmail.org</a></p></td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Tapestry Commits List</p></th><td
colspan="1" rowspan="1" c
lass="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Subscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Unsubscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://mail-archives.apache.org/mod_mbox/tapestry-commits/";>mail-archives.apache.org</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>-</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.commits";
rel="nofollow">tapestry.markmail.org</a></p></td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Search Multiple Lists</p></th><td
colspan="1" rowspan="1" class="confluenceTd"><p>-</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>-</p></td><td colspan="1" rowspa
n="1" class="confluenceTd"><p>-</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.1045711.n5.nabble.com/";
rel="nofollow">www.nabble.com</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=#query:+page:1+state:facets";
rel="nofollow">tapestry.markmail.org</a></p></td></tr></tbody></table></div></div>
+Apache Tapestry is an open source project and as such, supported by the
community. Even if you are looking for commercial support, your best bet for
support is to first subscribe to Apache Tapestry user mailing list and ask
there. Read more about how to <a href="community.html">get involved</a>.<h3
id="About-CommercialTrainingandSupport">Commercial Training and
Support</h3><p>Training on Tapestry and Support is available directly from the
source: the Tapestry project committers:</p><ul><li><a class="external-link"
href="http://www.arsmachina.com.br/services"; rel="nofollow">Thiago H. de Paula
Figueriredo</a>: Provides training and support on Tapestry and related
technologies including Spring and Hibernate</li></ul><h3
id="About-CommunitySupport">Community Support</h3><p>Like all Apache projects,
Tapestry uses mailing lists for most communication. You can subscribe by
sending e-mail to the addresses below. For each list, there are subscribe,
unsubscribe, and archive links. All Tapes
try users are welcome to subscribe to any of these lists, however questions on
how to <em>use</em> Tapestry in your application are best sent to the
<em>user</em> mailing list.</p><p>Please note that the Nabble archives are set
to read-only and don't allow for posting or answering using Nabble's web
interface. You have to subscribe to the mailing list in order to post.</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p> </p></td><th colspan="1" rowspan="1"
class="confluenceTh"><p>Subscribe</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Unsubscribe</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Apache Archive</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Nabble Archive</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>MarkMail Archive</p></th></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Tapestry User List</p></th><td colspan="1"
rowspan="1" clas
s="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Subscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Unsubscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://mail-archives.apache.org/mod_mbox/tapestry-users/";>mail-archives.apache.org</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.1045711.n5.nabble.com/Tapestry-User-f2375125.html";
rel="nofollow">www.nabble.com</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.users";
rel="nofollow">tapestry.markmail.org</a></p></td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Tapestry Developer List</p></th><td
colspan="1" rowspan=
"1" class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Subscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Unsubscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://mail-archives.apache.org/mod_mbox/tapestry-dev/";>mail-archives.apache.org</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.1045711.n5.nabble.com/Tapestry-Dev-f2438278.html";
rel="nofollow">www.nabble.com</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.dev";
rel="nofollow">tapestry.markmail.org</a></p></td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Tapestry Commits List</p></th><td
colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Subscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="mailto:[email protected]";
rel="nofollow">Unsubscribe</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://mail-archives.apache.org/mod_mbox/tapestry-commits/";>mail-archives.apache.org</a></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>-</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=list%3Aorg.apache.tapestry.commits";
rel="nofollow">tapestry.markmail.org</a></p></td></tr><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Search Multiple Lists</p></th><td
colspan="1" rowspan="1" class="confluenceTd"><p>-</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>-</p></td><td colspan="1" rows
pan="1" class="confluenceTd"><p>-</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.1045711.n5.nabble.com/";
rel="nofollow">www.nabble.com</a></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p><a class="external-link"
href="http://tapestry.markmail.org/search/?q=#query:+page:1+state:facets";
rel="nofollow">tapestry.markmail.org</a></p></td></tr></tbody></table></div></div>
</div>
<div class="clearer"></div>
Modified:
websites/production/tapestry/content/building-tapestry-from-source.html
==============================================================================
--- websites/production/tapestry/content/building-tapestry-from-source.html
(original)
+++ websites/production/tapestry/content/building-tapestry-from-source.html Mon
Feb 19 20:20:17 2018
@@ -75,7 +75,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>This is a guide to building
Tapestry itself from source code. This is primarily of interest to Tapestry
<em>contributors</em>, rather than Tapestry <em>users</em>.</p><p>Although
Tapestry <em>users</em> are free to use any build mechanism for their own
projects (and first class Maven support is provided), to build Tapestry itself
from source you will use Gradle.</p><p>Note: Both command line and Eclipse
Gradle IDE/EGit instructions are given here. Generally you'll want to chose
approach one or the other, rather than mixing them.</p><h2
id="BuildingTapestryfromSource-Prerequisites">Prerequisites</h2><ul><li>Install
a <strong>Java JDK</strong> (Sun/Oracle, not OpenJDK), version 1.7 (just to
prevent VU#225657, see: <a class="external-link"
href="http://www.kb.cert.org/vuls/id/225657";
rel="nofollow">http://www.kb.cert.org/vuls/id/225657</a>), or version 1.8 for
Tapestry 5.5 and later.</li><li>Install an <strong>IDE</strong> (IDEA IntelliJ
is recommended (and free to Tapestry committers), but Eclipse will also work.
NetBeans is reported to work as well.</li><li><strong>Firefox</strong>: For
Tapestry 5.4.x and earlier, install Firefox browser <a class="external-link"
href="https://ftp.mozilla.org/pub/firefox/releases/42.0/";
rel="nofollow">version 42</a> or earlier, needed for the integration tests
(because newer versions require a newer version of Selenium than Tapestry's
Java version requirements allow).</li><li><s>Set the Firefox browser's
"preferred language" to English (en), because some tests will otherwise
fail.</s> (Fixed; see <a class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-2413";>TAP5-2413</a>)</li><li>Install
a <strong>Git</strong> client<ul><li>Command-line users: <a
class="external-link" href="http://git-scm.com/downloads";
rel="nofollow">http://git-scm.com/downloads</a></li><li>Eclipse users: install
EGit from the Eclipse Marketplace, then in In Window > Preferences > Team
&
gt; Git, set your "Default repository folder" (e.g. <code>~/git</code> or
<code>%HOME%\git</code>). Note that for Eclipse 4.4 (Luna) and later Git
support is built in.</li></ul></li><li>Install <strong>Gradle</strong>
1.0-milestone-3 or newer (or a Gradle plugin to your IDE),<ul><li>Command-line
users: nothing to do (Tapestry's Gradle wrapper, gradlew, will download Gradle
automatically on first use).</li><li>Eclipse users: Install Gradle IDE (aka
Gradle Integration for Eclipse), from the Eclipse Marketplace. Note that for
Eclipse 4.6 (Neon) and later, Gradle support is built
in.</li></ul></li></ul><h2
id="BuildingTapestryfromSource-GettingStarted">Getting Started</h2><p>Please
read <a class="external-link"
href="https://git-wip-us.apache.org/";>https://git-wip-us.apache.org/</a>
first.</p><p>Windows users (especialy EGit users) should probably set the
core.autocrlf config setting to <code>false</code> so that local diffs won't
highlight line ending differences.</p><h3 id="BuildingT
apestryfromSource-ClonetheRepository">Clone the Repository</h3><p>Clone
Tapestry from the Git repo:</p><ul><li><p>Command-line git users:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>Non Committers:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>git clone</p><a class="external-link"
href="http://git-wip-us.apache.org/repos/asf/tapestry-5.git";>http://git-wip-us.apache.org/repos/asf/tapestry-5.git</a><p> </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>Committers:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>git clone</p><a
class="external-link"
href="https://git-wip-us.apache.org/repos/asf/tapestry-5.git";>https://git-wip-us.apache.org/repos/asf/tapestry-5.git</a><p> </p></td></tr></tbody></table></div></li><li>Eclipse
EGit users:<ul><li>Switch to Git perspective; then copy one of the URLs above
into paste buffer</li><li>Right-click > Paste reposi
tory path or URI. This will bring up the Clone Git Repository
dialog.</li><li>Committers: make sure Protocol is https, and enter your Apache
commiter LDAP user name & password</li><li>click Next.</li><li>Select the
branches you're interested in (e.g 5.3 and master), click Next</li><li>Select
Directory to where you want the project source code (e.g.
<code>~/git/tapestry-5</code> or
<code>%HOME%\git\tapestry-5</code>)</li><li>Select whichever "Initial Branch"
you're interested in (e.g. master)</li><li>Set "Remote name" to "origin" (the
default)</li><li><strong>VERY IMPORTANT</strong>: uncheck the "Import all
existing projects" checkbox (we'll do this using Gradle, below)</li><li>Click
Finish. (Be patient; the clone operation might take a few
minutes.)</li></ul></li></ul><h3
id="BuildingTapestryfromSource-GradlePreparation">Gradle
Preparation</h3><ul><li>Command-line gradle users only:<ul><li>If you're using
Eclipse but <strong>not</strong> Gradle IDE do <code>./gradlew eclipse</co
de></li><li>The command-line Gradle's eclipse plugin doesn't include the
provided project dependencies; you need to add them manually (Java Build Path
> Projects > Add tapestry-test). The plugin also generates a root eclipse
project, so you'll need to delete the ".project" file in the root folder, and
then you can import all Tapestry sub-projects at
once.</li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Switch to Java (or
JEE) perspective and right-click > Import... > Gradle > Gradle Project
> Next.</li><li>Set the "Root folder" to where you put your Tapestry source
in the previous section (e.g. <code>~/git/tapestry-5</code> or
<code>%Home%\git\tapestry-5</code>)</li><li>Click <code>Build Model. When it
completes, s</code>elect the top-level (the top-level module and all
sub-modules).</li><li>Be sure the "Enable dependency management" and "Create
workingset 'tapestry-5' checkboxes are checked.</li><li>Click
<code>Finish</code>. (Be patient; the import operation m
ight take a few minutes.)</li></ul></li><li>Eclipse EGit users: Do a Git
"Share" on the project:<ul><li>Still in the Java (or JEE) perspective, select
all of the Tapestry projects (top-level and sub-modules) and right-click >
Team > Share Project... > Git > Next > Ensure all are selected,
click <code>Finish</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Antlr">Antlr</h3><p>The
<code>tapestry-core</code> project will initially have errors because of
missing Java classes that are produced by ANTLR the first time the project is
built. To fix this:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on
the <code>build.gradle</code> file within tapestry-core and click Run As >
"Gradle build...", check <strong>only</strong> the generateGrammarSource task,
and change the "Name" field to something like "tapestry-core antlr", then click
Apply and Run.</li><li>When it's finished, the antlr-generated classes (e.g.
PropertyExpressionLexer.java) will be in cr
eated in $buildDir/generated-sources/antlr/, but Eclipse doesn't yet know
about that path. To fix that, right click on the <code>tapestry-core</code>
project > Properties > Java Build Path > Source > Add Folder >
find <code>tapestry-core/build/generated-sources/antlr</code> and check the
checkbox next to it, then click <code>OK</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-CoffeeScript">CoffeeScript</h3><p>If you want to
run tests from within Eclipse, Tapestry will complain that it won't find
certain JavaScript files that normally are generated during compile time from
their Coffeescript sources. In order to generate the JavaScript files you need
to have Coffeescript installed and in your path. Simply install <a
class="external-link" href="http://nodejs.org/download/";
rel="nofollow">Node.js</a> and afterwards run <code>npm install -g
coffee-script</code>. The installation should take care of
everything.</p><ul><li>Eclipse Gradle IDE users:<ul><li>Righ
t click on the <code>build.gradle</code> file within tapestry-core and click
Run As > "Gradle build...", check <strong>only</strong> the
tapestry-core:compileCoffeeScript and tapestry-core:compileTestCoffeeScript
tasks, and change the "Name" field to something like "tapestry-core
coffeescript", then click Apply and Run.</li><li>When it's finished, the
coffeescript-generated JavaScript files (e.g. t5-core-dom-jquery.js) will be in
created in $buildDir/generated-sources/compiled-coffeescript/ and
$buildDir/generated-sources/compiled-test-coffeescript/, but Eclipse doesn't
yet know about that path. To fix that, right click on the
<code>tapestry-core</code> project > Properties > Java Build Path >
Source > Add Folder > find
<code>tapestry-core/build/generated-sources/compiled-coffeescript</code> and
<code>tapestry-core/build/generated-sources/compiled-test-coffeescript</code>
and check the checkbox next to it, then click
<code>OK</code>.</li></ul></li></ul><h3 id="Buil
dingTapestryfromSource-GenerateCoffeeScriptandAntlrfilesautomaticallywhenchanged">Generate
CoffeeScript and Antlr files automatically when changed</h3><p>If you want to
have Eclipse compile the JavaScript files and lexer classes from their
Coffeescript sources and Antlr files automatically when they change, you can do
that by configuring an additional builder for the <code>tapestry-core</code>
project:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on the
<code>tapestry-core</code> project and select properties.</li><li>Select the
"Builders" entry from the list on the left and click "New.." in the right
panel.</li><li>Select "Program" and click "Ok".</li><li>Give the program a
meaningful name, e.g. "compile coffeescript and antlr".</li><li>Switch to the
"Main" tab.</li><li>For "Location:" click "Browse Workspace..." and select
gradlew (for Mac/Linux) or <code>gradlew.bat (for Windows)</code> in the
Tapestry root project. If the root project is called "tapestry-5" the entry
should look similar to "${<a class="external-link"
href="http://workspace_loc/tapestry-5/gradlew.bat";
rel="nofollow">workspace_loc:/tapestry-5/gradlew.bat</a>}".</li><li>For
"Working Directory:" click "Browse Workspace..." and select the Tapestry root
project.</li><li>For "Arguments:" enter
<code>tapestry-core:generateGrammarSource tapestry-core:compileCoffeeScript
tapestry-core:compileTestCoffeeScript</code></li><li>Switch to the "Build
Options" tab.</li><li>Make sure that only "Allocate Console", "After a
"Clean"", "During manual builds", "During auto builds" and "Specify working set
of relevant resources" are checked.</li><li>Click "Specify
Resources...".</li><li>From the "tapestry-core" project select
"src/main/antlr", "src/main/coffeescript", and
"src/test/coffeescript".</li><li>Click "Finish".</li><li>Click
"OK".</li><li>Click "OK".</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Building">Building</h3><p>You can build
individual modules, or (from the root folder) build
everything.</p><ul><li>Command-line users:<br clear="none"> *( "gradlew" is
the gradle wrapper shell script (gradlew) or batch file (gradlew.bat) found in
the root folder of the Tapestry source.<ul><li><code>./gradlew
build</code></li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Right click on
the top-level project (or any sub-project) and select Run As > Gradle
Build..., which starts an External Tools Configuration dialog box. Enter a
reasonable name, select the tasks you want to run (for example,
tapestry-core/install), and click Run.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-SeleniumSetup">Selenium Setup</h3><p>It is
necessary that you have a compatible version of Firefox installed.  On a
Mac, you should install it in ~/Applications (rather than
/Applications).</p><p>You should modify your ~/.bash_profile (or equivalent),
to add ~/Applications/Firefox.app/Contents/MacOS to the PATH variable.</p><h3
id="BuildingTapestryfromSource-RunningIndividualTests">Runn
ing Individual Tests</h3><p>Eclipse users:</p><ul><li>Install the <a
class="external-link" href="http://testng.org/doc/eclipse.html";
rel="nofollow">TestNG plugin</a> to allow running of individual TestNG unit
tests from within in Eclipse.</li><li>Right-click on any test class and select
Run As >TestNG Test</li></ul><p>Command-line users:</p><ul><li>./gradlew
-Dtest.single=myclassname</li><li>./gradlew
-Dtest.single=myclassname.mymethod</li></ul><p>where myclassname is the test
class, such as FormTest</p><p>The Tapestry integration tests will repeatedly
start up a Firefox browser.</p><ul><li>Ensure that your environment will allow
a connection to <a class="external-link" href="https://localhost:9090";
rel="nofollow">https://localhost:9090</a></li></ul><h3
id="BuildingTapestryfromSource-SkippingTests">Skipping Tests</h3><p>Running the
Tapestry integration tests can take 10 minutes or more (mostly because of
Selenium tests, which repeatedly start and stop the Firefox browser), so y
ou won't want to run them every time you try a change.</p><ul><li>Command-line
users:<ul><li><code>To build while skipping all tests: ./gradlew build -x
test</code></li><li>You can skip tests on a specific module by adding a colon
and the module name. For example: <code>-x
test:tapestry-ioc</code></li></ul></li><li>Eclipse Gradle IDE users:<ul><li>In
your External Tools Configuration, add the same -x test option as above at
Arguments > Program Arguments.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-RunningtheIntegrationTestAppsManually">Running
the Integration Test Apps Manually</h3><p>The Tapestry source includes several
web apps that are used by the automated Selenium integration tests. You can
also run these apps manually to try out nearly every browser-visible aspect of
Tapestry.</p><ul><li>Command-line users:<ul><li>./gradlew
runTestApp1</li></ul></li><li>Eclipse users:<ul><li>Use the run-jetty-run
plugin in Eclipse, with the context directory selected from among th
e <code>test</code> context directories. For example, in the tapestry-core
module, right click on the /src/test/app1 (or app2, etc) folder, and select Run
As > Run Jetty, then open your browser to <a class="external-link"
href="http://localhost:8080/tapestry-core";
rel="nofollow">http://localhost:8080/tapestry-core</a></li></ul></li></ul><h3
id="BuildingTapestryfromSource-MakingCodeChanges">Making Code
Changes</h3><p>Once you have cloned or pulled the latest changes to your local
Git repository, you can start working on it. Whenever you make some changes to
the codebase, it's good to have a related issue filed in JIRA and to use a
similarly named branch in your local Git repository. For example, to create a
branch for an issue with the key TAP5-123:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+ <div id="ConfluenceContent"><p>This is a guide to building
Tapestry itself from source code. This is primarily of interest to Tapestry
<em>contributors</em>, rather than Tapestry <em>users</em>.</p><p>Although
Tapestry <em>users</em> are free to use any build mechanism for their own
projects (and first class Maven support is provided), to build Tapestry itself
from source you will use Gradle.</p><p>Note: Both command line and Eclipse
Gradle IDE/EGit instructions are given here. Generally you'll want to chose
approach one or the other, rather than mixing them.</p><h2
id="BuildingTapestryfromSource-Prerequisites">Prerequisites</h2><ul><li>Install
a <strong>Java JDK</strong> (Sun/Oracle, not OpenJDK), version 1.7 (just to
prevent VU#225657, see: <a class="external-link"
href="http://www.kb.cert.org/vuls/id/225657";
rel="nofollow">http://www.kb.cert.org/vuls/id/225657</a>), or version 1.8 for
Tapestry 5.5 and later.</li><li>Install an <strong>IDE</strong> (IDEA IntelliJ
is recommended (and free to Tapestry committers), but Eclipse will also work.
NetBeans is reported to work as well.</li><li><strong>Firefox</strong>: For
Tapestry 5.4.x and earlier, install Firefox browser <a class="external-link"
href="https://ftp.mozilla.org/pub/firefox/releases/42.0/";
rel="nofollow">version 42</a> or earlier, needed for the integration tests
(because newer versions require a newer version of Selenium than Tapestry's
Java version requirements allow).</li><li><s>Set the Firefox browser's
"preferred language" to English (en), because some tests will otherwise
fail.</s> (Fixed; see <a class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-2413";>TAP5-2413</a>)</li><li>Install
a <strong>Git</strong> client<ul><li>Command-line users: <a
class="external-link" href="http://git-scm.com/downloads";
rel="nofollow">http://git-scm.com/downloads</a></li><li>Eclipse users: install
EGit from the Eclipse Marketplace, then in In Window > Preferences > Team
&
gt; Git, set your "Default repository folder" (e.g. <code>~/git</code> or
<code>%HOME%\git</code>). Note that for Eclipse 4.4 (Luna) and later Git
support is built in.</li></ul></li><li>Install <strong>Gradle</strong>
1.0-milestone-3 or newer (or a Gradle plugin to your IDE),<ul><li>Command-line
users: nothing to do (Tapestry's Gradle wrapper, gradlew, will download Gradle
automatically on first use).</li><li>Eclipse users: Install Gradle IDE (aka
Gradle Integration for Eclipse), from the Eclipse Marketplace. Note that for
Eclipse 4.6 (Neon) and later, Gradle support is built
in.</li></ul></li></ul><h2
id="BuildingTapestryfromSource-GettingStarted">Getting Started</h2><p>Please
read <a class="external-link"
href="https://git-wip-us.apache.org/";>https://git-wip-us.apache.org/</a>
first.</p><p>Windows users (especialy EGit users) should probably set the
core.autocrlf config setting to <code>false</code> so that local diffs won't
highlight line ending differences.</p><h3 id="BuildingT
apestryfromSource-ClonetheRepository">Clone the Repository</h3><p>Clone
Tapestry from the Git repo:</p><ul><li><p>Command-line git users:</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p>Non Committers:</p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>git clone</p><a class="external-link"
href="http://git-wip-us.apache.org/repos/asf/tapestry-5.git";>http://git-wip-us.apache.org/repos/asf/tapestry-5.git</a><p> </p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>Committers:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>git clone</p><a
class="external-link"
href="https://git-wip-us.apache.org/repos/asf/tapestry-5.git";>https://git-wip-us.apache.org/repos/asf/tapestry-5.git</a><p> </p></td></tr></tbody></table></div></li><li>Eclipse
EGit users:<ul><li>Switch to Git perspective; then copy one of the URLs above
into paste buffer</li><li>Right-click > Paste reposi
tory path or URI. This will bring up the Clone Git Repository
dialog.</li><li>Committers: make sure Protocol is https, and enter your Apache
commiter LDAP user name & password</li><li>click Next.</li><li>Select the
branches you're interested in (e.g 5.3 and master), click Next</li><li>Select
Directory to where you want the project source code (e.g.
<code>~/git/tapestry-5</code> or
<code>%HOME%\git\tapestry-5</code>)</li><li>Select whichever "Initial Branch"
you're interested in (e.g. master)</li><li>Set "Remote name" to "origin" (the
default)</li><li><strong>VERY IMPORTANT</strong>: uncheck the "Import all
existing projects" checkbox (we'll do this using Gradle, below)</li><li>Click
Finish. (Be patient; the clone operation might take a few
minutes.)</li></ul></li></ul><h3
id="BuildingTapestryfromSource-GradlePreparation">Gradle
Preparation</h3><ul><li>Command-line gradle users only:<ul><li>If you're using
Eclipse but <strong>not</strong> Gradle IDE do <code>./gradlew eclipse</co
de></li><li>The command-line Gradle's eclipse plugin doesn't include the
provided project dependencies; you need to add them manually (Java Build Path
> Projects > Add tapestry-test). The plugin also generates a root eclipse
project, so you'll need to delete the ".project" file in the root folder, and
then you can import all Tapestry sub-projects at
once.</li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Switch to Java (or
JEE) perspective and right-click > Import... > Gradle > Gradle Project
> Next.</li><li>Set the "Root folder" to where you put your Tapestry source
in the previous section (e.g. <code>~/git/tapestry-5</code> or
<code>%Home%\git\tapestry-5</code>)</li><li>Click <code>Build Model. When it
completes, s</code>elect the top-level (the top-level module and all
sub-modules).</li><li>Be sure the "Enable dependency management" and "Create
workingset 'tapestry-5' checkboxes are checked.</li><li>Click
<code>Finish</code>. (Be patient; the import operation m
ight take a few minutes.)</li></ul></li><li>Eclipse EGit users: Do a Git
"Share" on the project:<ul><li>Still in the Java (or JEE) perspective, select
all of the Tapestry projects (top-level and sub-modules) and right-click >
Team > Share Project... > Git > Next > Ensure all are selected,
click <code>Finish</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Antlr">Antlr</h3><p>The
<code>tapestry-core</code> project will initially have errors because of
missing Java classes that are produced by ANTLR the first time the project is
built. To fix this:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on
the <code>build.gradle</code> file within tapestry-core and click Run As >
"Gradle build...", check <strong>only</strong> the generateGrammarSource task,
and change the "Name" field to something like "tapestry-core antlr", then click
Apply and Run.</li><li>When it's finished, the antlr-generated classes (e.g.
PropertyExpressionLexer.java) will be in cr
eated in $buildDir/generated-sources/antlr/, but Eclipse doesn't yet know
about that path. To fix that, right click on the <code>tapestry-core</code>
project > Properties > Java Build Path > Source > Add Folder >
find <code>tapestry-core/build/generated-sources/antlr</code> and check the
checkbox next to it, then click <code>OK</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-CoffeeScript">CoffeeScript</h3><p>If you want to
run tests from within Eclipse, Tapestry will complain that it won't find
certain JavaScript files that normally are generated during compile time from
their Coffeescript sources. In order to generate the JavaScript files you need
to have Coffeescript installed and in your path. Simply install <a
class="external-link" href="http://nodejs.org/download/";
rel="nofollow">Node.js</a> and afterwards run <code>npm install -g
coffee-script</code>. The installation should take care of
everything.</p><ul><li>Eclipse Gradle IDE users:<ul><li>Righ
t click on the <code>build.gradle</code> file within tapestry-core and click
Run As > "Gradle build...", check <strong>only</strong> the
tapestry-core:compileCoffeeScript and tapestry-core:compileTestCoffeeScript
tasks, and change the "Name" field to something like "tapestry-core
coffeescript", then click Apply and Run.</li><li>When it's finished, the
coffeescript-generated JavaScript files (e.g. t5-core-dom-jquery.js) will be in
created in $buildDir/generated-sources/compiled-coffeescript/ and
$buildDir/generated-sources/compiled-test-coffeescript/, but Eclipse doesn't
yet know about that path. To fix that, right click on the
<code>tapestry-core</code> project > Properties > Java Build Path >
Source > Add Folder > find
<code>tapestry-core/build/generated-sources/compiled-coffeescript</code> and
<code>tapestry-core/build/generated-sources/compiled-test-coffeescript</code>
and check the checkbox next to it, then click
<code>OK</code>.</li></ul></li></ul><h3 id="Buil
dingTapestryfromSource-GenerateCoffeeScriptandAntlrfilesautomaticallywhenchanged">Generate
CoffeeScript and Antlr files automatically when changed</h3><p>If you want to
have Eclipse compile the JavaScript files and lexer classes from their
Coffeescript sources and Antlr files automatically when they change, you can do
that by configuring an additional builder for the <code>tapestry-core</code>
project:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on the
<code>tapestry-core</code> project and select properties.</li><li>Select the
"Builders" entry from the list on the left and click "New.." in the right
panel.</li><li>Select "Program" and click "Ok".</li><li>Give the program a
meaningful name, e.g. "compile coffeescript and antlr".</li><li>Switch to the
"Main" tab.</li><li>For "Location:" click "Browse Workspace..." and select
gradlew (for Mac/Linux) or <code>gradlew.bat (for Windows)</code> in the
Tapestry root project. If the root project is called "tapestry-5" the entry
should look similar to "${workspace_loc:/tapestry-5/gradlew.bat}".</li><li>For
"Working Directory:" click "Browse Workspace..." and select the Tapestry root
project.</li><li>For "Arguments:" enter
<code>tapestry-core:generateGrammarSource tapestry-core:compileCoffeeScript
tapestry-core:compileTestCoffeeScript</code></li><li>Switch to the "Build
Options" tab.</li><li>Make sure that only "Allocate Console", "After a
"Clean"", "During manual builds", "During auto builds" and "Specify working set
of relevant resources" are checked.</li><li>Click "Specify
Resources...".</li><li>From the "tapestry-core" project select
"src/main/antlr", "src/main/coffeescript", and
"src/test/coffeescript".</li><li>Click "Finish".</li><li>Click
"OK".</li><li>Click "OK".</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Building">Building</h3><p>You can build
individual modules, or (from the root folder) build
everything.</p><ul><li>Command-line users:<br clear="none"> *( "gradlew" is the
gradle wrapper
shell script (gradlew) or batch file (gradlew.bat) found in the root folder of
the Tapestry source.<ul><li><code>./gradlew
build</code></li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Right click on
the top-level project (or any sub-project) and select Run As > Gradle
Build..., which starts an External Tools Configuration dialog box. Enter a
reasonable name, select the tasks you want to run (for example,
tapestry-core/install), and click Run.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-SeleniumSetup">Selenium Setup</h3><p>It is
necessary that you have a compatible version of Firefox installed.  On a
Mac, you should install it in ~/Applications (rather than
/Applications).</p><p>You should modify your ~/.bash_profile (or equivalent),
to add ~/Applications/Firefox.app/Contents/MacOS to the PATH variable.</p><h3
id="BuildingTapestryfromSource-RunningIndividualTests">Running Individual
Tests</h3><p>Eclipse users:</p><ul><li>Install the <a class="external-link"
href
="http://testng.org/doc/eclipse.html"; rel="nofollow">TestNG plugin</a> to
allow running of individual TestNG unit tests from within in
Eclipse.</li><li>Right-click on any test class and select Run As >TestNG
Test</li></ul><p>Command-line users:</p><ul><li>./gradlew
-Dtest.single=myclassname</li><li>./gradlew
-Dtest.single=myclassname.mymethod</li></ul><p>where myclassname is the test
class, such as FormTest</p><p>The Tapestry integration tests will repeatedly
start up a Firefox browser.</p><ul><li>Ensure that your environment will allow
a connection to <a class="external-link" href="https://localhost:9090";
rel="nofollow">https://localhost:9090</a></li></ul><h3
id="BuildingTapestryfromSource-SkippingTests">Skipping Tests</h3><p>Running the
Tapestry integration tests can take 10 minutes or more (mostly because of
Selenium tests, which repeatedly start and stop the Firefox browser), so you
won't want to run them every time you try a change.</p><ul><li>Command-line
users:<ul><li><co
de>To build while skipping all tests: ./gradlew build -x
test</code></li><li>You can skip tests on a specific module by adding a colon
and the module name. For example: <code>-x
test:tapestry-ioc</code></li></ul></li><li>Eclipse Gradle IDE users:<ul><li>In
your External Tools Configuration, add the same -x test option as above at
Arguments > Program Arguments.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-RunningtheIntegrationTestAppsManually">Running
the Integration Test Apps Manually</h3><p>The Tapestry source includes several
web apps that are used by the automated Selenium integration tests. You can
also run these apps manually to try out nearly every browser-visible aspect of
Tapestry.</p><ul><li>Command-line users:<ul><li>./gradlew
runTestApp1</li></ul></li><li>Eclipse users:<ul><li>Use the run-jetty-run
plugin in Eclipse, with the context directory selected from among the
<code>test</code> context directories. For example, in the tapestry-core
module, right click o
n the /src/test/app1 (or app2, etc) folder, and select Run As > Run Jetty,
then open your browser to <a class="external-link"
href="http://localhost:8080/tapestry-core";
rel="nofollow">http://localhost:8080/tapestry-core</a></li></ul></li></ul><h3
id="BuildingTapestryfromSource-MakingCodeChanges">Making Code
Changes</h3><p>Once you have cloned or pulled the latest changes to your local
Git repository, you can start working on it. Whenever you make some changes to
the codebase, it's good to have a related issue filed in JIRA and to use a
similarly named branch in your local Git repository. For example, to create a
branch for an issue with the key TAP5-123:</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;">git branch TAP5-123 origin/master</pre>
</div></div><p>With per-issue branches you can easily switch back and forth
between different issues without worrying about unwanted side-effects from
unfinished changes to other issues. Whenever you want to work on the TAP5-123
example issue, simply checkout that branch and start making your
changes:</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;">git checkout TAP5-123</pre>
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/class-reloading.html
==============================================================================
--- websites/production/tapestry/content/class-reloading.html (original)
+++ websites/production/tapestry/content/class-reloading.html Mon Feb 19
20:20:17 2018
@@ -110,7 +110,18 @@
</div>
-<p>One of the best features of Tapestry is automatic reloading of changed
classes and templates. <em>Page and component</em> classes will automatically
reload when changed. Likewise, changes to component templates and other related
resources will also be picked up immediately. In addition, starting in version
5.2, your service classes will also be reloaded automatically after changes (if
you're using <a href="ioc.html">Tapestry IoC</a>).</p><h2
id="ClassReloading-TemplateReloading">Template Reloading</h2><p>When a template
changes, all page instances (as well as the hierarchy of components below them)
are discarded and reconstructed with the new template. However, classes are not
reloaded in this case.</p><h2 id="ClassReloading-ClassReloading">Class
Reloading</h2><p>On a change to <em>any</em> loaded class from inside a
controlled package (or any sub-package of a controlled package), Tapestry will
discard all page instances, and discard the class loader.</p><p><a
href="class-reloa
ding.html">Persistent field data</a> on the pages will usually not be affected
(as it is stored separately, usually in the session). This allows you to make
fairly significant changes to a component class even while the application
continues to run.</p><h2 id="ClassReloading-PackagesScanned">Packages
Scanned</h2><p>Only certain classes are subject to reload. Reloading is based
on package name; the packages that are reloaded are derived from the <a
href="configuration.html">application configuration</a>.</p><p>If your root
package is <code>org.example.myapp</code>, then only classes in the following
packages (and their sub-packages) will be scanned for automatic
reloads:</p><ul><li>org.example.myapp.pages</li><li>org.example.myapp.components</li><li>org.example.myapp.mixins</li><li>org.example.myapp.base</li><li>org.example.myapp.services
(Tapestry 5.2 and later, with restrictions)</li></ul><p>Starting in Tapestry
5.2, live class reloading includes service implementation classes. Th
ere are some limitations to this. See <a
href="service-implementation-reloading.html">Service Implementation
Reloading</a> for more details.</p><h2 id="ClassReloading-FileSystemOnly">File
System Only</h2><p>Reloading of classes and other files applies only to files
that are actually on the file system, and not files obtained from JAR files.
This is perfect during development, where the files in question are in your
local workspace. In a deployed application, you are somewhat subject to the
implementation of your servlet container or application server.</p><h2
id="ClassReloading-ClassLoaderIssues">Class Loader Issues</h2><p>Tapestry uses
an extra class loader to load page and component classes.</p><p>When a change
to an underlying Java class file is detected, Tapestry discards the class
loader and any pooled page instances.</p><p>You should be careful to not hold
any references to Tapestry pages or components in other code, such as Tapestry
IoC services. Holding such references
can cause significant memory leaks, as they can prevent the class loader from
being reclaimed by the garbage collector.</p><h2
id="ClassReloading-ClassCastExceptions">ClassCastExceptions</h2><p>Tapestry's
class loader architecture can cause minor headaches when you make use of a
services layer, or any time that you pass component instances to objects that
are not themselves components.</p><p>In such cases you may see
ClassCastException errors. This is because the same class name, say
org.example.myapp.pages.Start, exists as two different class instances. One
class instance is loaded by the web application's default class loader. A
second class instance has been loaded <em>and transformed</em> by Tapestry's
reloading class loader.</p><p>Ordinary classes, such as Tapestry IoC Services,
will be loaded by the default class loader and expect instances to be loaded by
the same class loader (or a parent).</p><p>The solution to this problem is to
introduce an interface; the component class
should implement the interface, and the service should expect an instance of
the interface, rather than a specific type.</p><p>It is important that the
interface be loaded by the default class loader. It should not be in the pages
or components package, but instead be in another package, such as
services.</p><h2 id="ClassReloading-HandlingReloadsinyourCode">Handling Reloads
in your Code</h2><p>On occasion, you may need to know when invalidations occur,
to clear your own cache. For example, if you have a binding that creates new
classes, the way <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PropertyConduitSource.html";>PropertyConduitSource</a>
does, you need to discard any cached classes or instances when a change is
detected in component classes.</p><p>You do this by registering a listener with
the correct <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tpaestry5/services/InvalidationEv
entHub.html">InvalidationEventHub</a> service.</p><p>For example, your service
may be in the business of creating new classes based on component classes, and
keep a cache of those classes:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p>One of the best features of Tapestry is automatic reloading of changed
classes and templates. <em>Page and component</em> classes will automatically
reload when changed. Likewise, changes to component templates and other related
resources will also be picked up immediately. In addition, starting in version
5.2, your service classes will also be reloaded automatically after changes (if
you're using <a href="ioc.html">Tapestry IoC</a>).</p><h2
id="ClassReloading-Contents">Contents</h2><p><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1519071568380 {padding: 0px;}
+div.rbtoc1519071568380 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1519071568380 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1519071568380">
+<ul class="toc-indentation"><li><a
href="#ClassReloading-TemplateReloading">Template Reloading</a></li><li><a
href="#ClassReloading-ClassReloading">Class Reloading</a></li><li><a
href="#ClassReloading-PackagesScanned">Packages Scanned</a></li><li><a
href="#ClassReloading-FileSystemOnly">File System Only</a></li><li><a
href="#ClassReloading-ClassLoaderIssues">Class Loader Issues</a></li><li><a
href="#ClassReloading-ClassCastExceptions">ClassCastExceptions</a></li><li><a
href="#ClassReloading-HandlingReloadsinyourCode">Handling Reloads in your
Code</a></li><li><a href="#ClassReloading-CheckingForUpdates">Checking For
Updates</a></li><li><a
href="#ClassReloading-TroubleshootingLiveClassReloading">Troubleshooting Live
Class Reloading</a>
+<ul class="toc-indentation"><li><a
href="#ClassReloading-QuickChecklist">Quick Checklist</a></li><li><a
href="#ClassReloading-IfLiveClassReloadingdoesn'twork">If Live Class Reloading
doesn't work</a>
+<ul class="toc-indentation"><li><a
href="#ClassReloading-ProductionMode">Production Mode</a></li><li><a
href="#ClassReloading-BuildPathIssues">Build Path Issues</a></li><li><a
href="#ClassReloading-BuildingAutomatically">Building
Automatically</a></li><li><a
href="#ClassReloading-TurnoffJVMhotcodeswapping&automaticrestarts">Turn off
JVM hot code swapping & automatic restarts</a></li></ul>
+</li><li><a href="#ClassReloading-TomcatSpecifics">Tomcat
Specifics</a></li><li><a
href="#ClassReloading-IfLiveClassReloadingworksbutisslow">If Live Class
Reloading works but is slow</a></li></ul>
+</li></ul>
+</div><h2 id="ClassReloading-TemplateReloading">Template Reloading</h2><p>When
a template changes, all page instances (as well as the hierarchy of components
below them) are discarded and reconstructed with the new template. However,
classes are not reloaded in this case.</p><h2
id="ClassReloading-ClassReloading">Class Reloading</h2><p>On a change to
<em>any</em> loaded class from inside a controlled package (or any sub-package
of a controlled package), Tapestry will discard all page instances, and discard
the class loader.</p><p><a href="class-reloading.html">Persistent field
data</a> on the pages will usually not be affected (as it is stored separately,
usually in the session). This allows you to make fairly significant changes to
a component class even while the application continues to run.</p><h2
id="ClassReloading-PackagesScanned">Packages Scanned</h2><p>Only certain
classes are subject to reload. Reloading is based on package name; the packages
that are reloaded are derived
from the <a href="configuration.html">application configuration</a>.</p><p>If
your root package is <code>org.example.myapp</code>, then only classes in the
following packages (and their sub-packages) will be scanned for automatic
reloads:</p><ul><li>org.example.myapp.pages</li><li>org.example.myapp.components</li><li>org.example.myapp.mixins</li><li>org.example.myapp.base</li><li>org.example.myapp.services
(Tapestry 5.2 and later, with restrictions)</li></ul><p>Starting in Tapestry
5.2, live class reloading includes service implementation classes. There are
some limitations to this. See <a
href="service-implementation-reloading.html">Service Implementation
Reloading</a> for more details.</p><h2 id="ClassReloading-FileSystemOnly">File
System Only</h2><p>Reloading of classes and other files applies only to files
that are actually on the file system, and not files obtained from JAR files.
This is perfect during development, where the files in question are in your
local workspace
. In a deployed application, you are somewhat subject to the implementation of
your servlet container or application server.</p><h2
id="ClassReloading-ClassLoaderIssues">Class Loader Issues</h2><p>Tapestry uses
an extra class loader to load page and component classes.</p><p>When a change
to an underlying Java class file is detected, Tapestry discards the class
loader and any pooled page instances.</p><p>You should be careful to not hold
any references to Tapestry pages or components in other code, such as Tapestry
IoC services. Holding such references can cause significant memory leaks, as
they can prevent the class loader from being reclaimed by the garbage
collector.</p><h2
id="ClassReloading-ClassCastExceptions">ClassCastExceptions</h2><p>Tapestry's
class loader architecture can cause minor headaches when you make use of a
services layer, or any time that you pass component instances to objects that
are not themselves components.</p><p>In such cases you may see
ClassCastException
errors. This is because the same class name, say
org.example.myapp.pages.Start, exists as two different class instances. One
class instance is loaded by the web application's default class loader. A
second class instance has been loaded <em>and transformed</em> by Tapestry's
reloading class loader.</p><p>Ordinary classes, such as Tapestry IoC Services,
will be loaded by the default class loader and expect instances to be loaded by
the same class loader (or a parent).</p><p>The solution to this problem is to
introduce an interface; the component class should implement the interface, and
the service should expect an instance of the interface, rather than a specific
type.</p><p>It is important that the interface be loaded by the default class
loader. It should not be in the pages or components package, but instead be in
another package, such as services.</p><h2
id="ClassReloading-HandlingReloadsinyourCode">Handling Reloads in your
Code</h2><p>On occasion, you may need to know when inv
alidations occur, to clear your own cache. For example, if you have a binding
that creates new classes, the way <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PropertyConduitSource.html";>PropertyConduitSource</a>
does, you need to discard any cached classes or instances when a change is
detected in component classes.</p><p>You do this by registering a listener with
the correct <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tpaestry5/services/InvalidationEventHub.html";>InvalidationEventHub</a>
service.</p><p>For example, your service may be in the business of creating
new classes based on component classes, and keep a cache of those
classes:</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 MyServiceImpl implements MyService,
InvalidationEventListener
{
public final Map<String,Class> cache = new
ConcurrentHashMap<String,Class>();
Modified: websites/production/tapestry/content/configuration.html
==============================================================================
--- websites/production/tapestry/content/configuration.html (original)
+++ websites/production/tapestry/content/configuration.html Mon Feb 19 20:20:17
2018
@@ -147,11 +147,11 @@
<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.rbtoc1519068033351 {padding: 0px;}
-div.rbtoc1519068033351 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1519068033351 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1519071568910 {padding: 0px;}
+div.rbtoc1519071568910 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1519071568910 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1519068033351">
+/*]]>*/</style></p><div class="toc-macro rbtoc1519071568910">
<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><li><a
href="#Configuration-SegregatingApplicationsIntoFolders">Segregating
Applications Into Folders</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
@@ -188,7 +188,14 @@ div.rbtoc1519068033351 li {margin-left:
}
}
</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 <strong>bold</strong> below. Use the symbol name
(tapestry.*) for JVM System Properties with the -D option, and use the constant
(in bold below) from within your Java classes (e.g. AppModule.java).</p><h3
id="Configuration-tapestry.app-catalog">tapestry.app-catalog</h3><p><strong>SymbolConstants.APPLICATION_CATALOG</strong> – 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">tapestry.application-version</h3><p><strong>SymbolConstants.APPLICATION_VERSION</strong> –
The version of the application, which is incorporated into URLs for context
and classpath assets. Assets m
ay 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">tapestry.application-folder</h3>
+</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 <strong>bold</strong> below. Use the symbol name
(tapestry.*) for JVM System Properties with the -D option, and use the constant
(in bold below) from within your Java classes (e.g. AppModule.java).</p><h3
id="Configuration-tapestry.app-catalog">tapestry.app-catalog</h3><p><strong>SymbolConstants.APPLICATION_CATALOG</strong> – 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">tapestry.application-version</h3>
+
+
+
+<div class="aui-message aui-message-info">
+Added in 5.4
+  
+</div><p><strong>SymbolConstants.APPLICATION_VERSION</strong> – The
version of the application, which is incorporated into URLs for context and
classpath assets in Tapestry versions prior to 5.4. <a
href="assets.html">Assets</a> 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">tapestry.application-folder</h3>
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 Mon Feb 19
20:20:17 2018
@@ -136,7 +136,7 @@
</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 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>Unfortunately,
wiki pages with embedded images will export with <img> tags pointing to
the origial cwiki.apache.org URLs, unless you manually change the image in the
Confluence page to be linked to the exported static image file. This has been
done for the banner image, but not every embedded image.</p><p>The time between
saving a change in Confluence and seeing the result on the public site is at
most 1 hour, dependi
ng 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/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 s
ource</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 p
age.</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 ha
rder 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:
@[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="confluence-site-setup.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 th
e 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="confluence-site-setup.html">Confluence Site
Setup</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="confluence-site-setup.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="confluence-site-setup.html">Confluence Site Setup</a> page includes the
<a href="confluence-site-setup.htm
l">Confluence Site Setup</a> and <a
href="confluence-site-setup.html">Confluence Site Setup</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="confluence-site-setup.html">Confluence Site Setup</a>, <a
href="confluence-site-setup.html">Confluence Site Setup</a> and <a
href="confluence-site-setup.html">Confluence Site Setup</a> pages
exist.</p><p>Our SiteExporter template (described above) glues everything
together. It adds the contents of the <a
href="confluence-site-setup.html">Confluence Site Setup</a> and <a
href="confluence-site-setup.html">Confluence Site Setup</a> pages in the
appropriate places and on all pages except the <a
href="confluence-site-setup.html">Confluence Site Setup</a> page. It also adds
the contents of the <a href="confluence-site-setup.html">Confluence Site
Setup</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 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>
+<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 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>Unfortunately,
wiki pages with embedded images will export with <img> tags pointing to
the origial cwiki.apache.org URLs, unless you manually change the image in the
Confluence page to be linked to the exported static image file. This has been
done for the banner image, but not every embedded image.</p><p>The time between
saving a change in Confluence and seeing the result on the public site is at
most 1 hour, dependi
ng 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/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 s
ource</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 p
age.</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 ha
rder 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:
@[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 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="confluence-site-setup.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
class="confluence-link">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
class="confluence-link">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-infor
mation-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 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>
