Author: buildbot
Date: Sun Nov 9 23:19:47 2014
New Revision: 928541
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/client-side-javascript.html
websites/production/tapestry/content/confluence-site-setup.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/client-side-javascript.html
==============================================================================
--- websites/production/tapestry/content/client-side-javascript.html (original)
+++ websites/production/tapestry/content/client-side-javascript.html Sun Nov 9
23:19:47 2014
@@ -29,6 +29,8 @@
<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 type="text/javascript">
SyntaxHighlighter.defaults['toolbar'] = false;
SyntaxHighlighter.all();
@@ -69,7 +71,73 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><p>Perhaps nothing in Tapestry has changed over
the years so much as the way client-side JavaScript is supported. From the get
go, the goal was to make JavaScript a first-class citizen in the Tapestry
world, and make it easy to encapsulate JavaScript within components.</p><p>The
<a shape="rect" href="legacy-javascript.html">legacy JavaScript</a> page
discusses the earlier approaches; the main feature of Tapestry 5.4 is a total
rewrite of all things client-side, with the following goals:</p><ul><li>Break
the hard linkage of Tapestry to <a shape="rect" class="external-link"
href="http://prototypejs.org/"; >Prototype</a> and <a shape="rect"
class="external-link" href="http://script.aculo.us/"; >Scriptaculous</a>, by
introducing an abstraction layer</li><li>Remove the clumsy
<code>Tapestry</code> and <code>T5</code> "namespaces"</li><li>Reduce the
amount of page-specific JavaScript initialization</li><li>Make it easier to
override behavior associated with clien
t elements</li><li>Support CoffeeScript and (potentially) other languages that
target JavaScript</li><li>Organize client-side JavaScript using <a shape="rect"
href="javascript-modules.html">modules</a></li><li>Make pages load
faster</li><li>Integrate <a shape="rect" class="external-link"
href="http://getbootstrap.com/"; >Bootstrap</a></li><li>Make it easier for rich
client libraries such as <a shape="rect" class="external-link"
href="http://backbonejs.org/"; >Backbone</a> or <a shape="rect"
class="external-link" href="https://angularjs.org/"; >AngularJS</a> to operate
within a page</li><li>Properly document Tapestry's client support</li></ul><h3
id="Client-SideJavaScript-TheOverallVision">The Overall Vision</h3><p>The
overall vision for the client-side in Tapestry is encapsulation, at several
different levels.</p><p>On the server-side, a Tapestry component (or mixin)
will exposes configurable parameters. The component will write DOM elements or
attributes, as well as some amo
unt of JavaScript initialization. The encapsulation here allows developers
with little or no knowledge of client-side JavaScript to enjoy the benefits (as
consumers of components created by developers who are versed in client-side
coding and Tapestry components).</p><p>On the client-side, the JavaScript
combines with the special markup to produce the behaviors that are desired ...
anything from controlling the initial focus field, to performing client-side
input field validation, to running complex Ajax workflows.</p><p>Where
possible, all of this behavior is driven by <code>data-</code> attributes on
the elements, combined with top-level event handlers. On the client side,
events are used not only to respond directly to user actions (with "click",
"mouseOver", "submit", or other event listeners) but also to allow elements to
collaborate in various ways.  For example, input validation is based on
triggering a specific custom event on each form control element, and top-level
eve
nt handlers can then manage the validation for any number of fields.</p><h3
id="Client-SideJavaScript-Prototypevs.jQuery">Prototype vs. jQuery</h3><p>For
several years, it has been obvious that Tapestry "backed the wrong horse" with
respect to Prototype and jQuery. When the first code was being laid down in
2007 or 2008, it wasn't so clear that jQuery with its odd abstractions and
unfamiliar approach, would go on to conquer the world. Meanwhile, Prototype was
very strongly integrated into Ruby on Rails and had first class documentation
and books.</p><p>That being said, jQuery may not be the be-all and end-all.
Tapestry 5.4 introduces an abstraction layer, that allows many components to
write code that doesn't care whether the foundation framework in Prototype or
jQuery. This is especially useful during the arduous process of moving Tapestry
5.3 client-side code forward to 5.4.</p><p>If you like jQuery then there's no
problem: write your application using just jQuery and you can igno
re a lot of the features in the abstraction layer. Your code will likely be
just a bit more efficient.</p><p>If you are building a reusable component or
library, writing to the abstraction layer may be worth the effort; it is
entirely possible that someone may write a replacement for the abstraction
layer that targets your favorite foundation framework, such as ExtJS, MooTools,
or something not even known of today.</p><h3
id="Client-SideJavaScript-Heavyvs.Light">Heavy vs. Light</h3><p>Earlier
Tapestry JavaScript was <em>heavy</em>. Essentially, each component would
write some very specific JavaScript initialization that would include the
component's DOM id and many other details. This initialization would reference
a function on the <code>T5.inits</code> namespace.</p><p>The function there
would typically locate the specific element by its client DOM id, then attach
event handlers to the one element. It might also create some form of
client-side controller object. There were is
sues due to this: for complex pages (or perhaps even typical pages), the
"blob" of JavaScript initialization at the bottom of the page could be quite
large.</p><p>The use of individual event handlers meant that Tapestry
applications would use more client-side objects that a bespoke jQuery solution
... because the normal approach in jQuery is to attach a single event handler
to the document or body that handles any events that bubble up to the
top <em>and</em> match a CSS selector.</p><p>In Tapestry 5.4, the goal is
to make things <em>light</em>. In most cases, there will not be a specific
initialization function; instead a <a shape="rect"
href="javascript-modules.html">JavaScript module</a> will be loaded, and it
will install one or more top-level event handlers; the elements will have <a
shape="rect" class="external-link"
href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes";
><code>data-</code> attributes</a> that are used by those top level
handlers to recognize which elements they are responsible for.</p><p>This is
more of a full lifecycle approach; adding or removing page content (such as
with a <a shape="rect" href="ajax-and-zones.html">Zone</a> component) is
both cheaper and less error prone using top-level event handlers than
per-element event handlers; there's also less of a chance of memory leaks under
Internet Explorer.</p> <div class="aui-message warning shadowed
information-macro">
+<div id="ConfluenceContent"><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:3px">
+<h3>Related Articles</h3>
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect" href="ajax-and-zones.html">Ajax
and Zones</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect"
href="legacy-javascript.html">Legacy JavaScript</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect"
href="component-cheat-sheet.html">Component Cheat Sheet</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect"
href="ajax-components-faq.html">Ajax Components FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect"
href="javascript-faq.html">JavaScript FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect" href="assets.html">Assets</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon icon-page" title="Page">Page:</span>
</div>
+
+ <div class="details">
+ <a shape="rect"
href="client-side-javascript.html">Client-Side JavaScript</a>
+
+
+ </div>
+ </li></ul>
+</div><p>Perhaps nothing in Tapestry has changed over the years so much as the
way client-side JavaScript is supported. From the get go, the goal was to make
JavaScript a first-class citizen in the Tapestry world, and make it easy to
encapsulate JavaScript within components.</p><p>The <a shape="rect"
href="legacy-javascript.html">legacy JavaScript</a> page discusses the earlier
approaches; the main feature of Tapestry 5.4 is a total rewrite of all things
client-side, with the following goals:</p><ul><li>Break the hard linkage of
Tapestry to <a shape="rect" class="external-link"
href="http://prototypejs.org/"; >Prototype</a> and <a shape="rect"
class="external-link" href="http://script.aculo.us/"; >Scriptaculous</a>, by
introducing an abstraction layer</li><li>Remove the clumsy
<code>Tapestry</code> and <code>T5</code> "namespaces"</li><li>Reduce the
amount of page-specific JavaScript initialization</li><li>Make it easier to
override behavior associated with client elements</li><li>Sup
port CoffeeScript and (potentially) other languages that target
JavaScript</li><li>Organize client-side JavaScript using <a shape="rect"
href="javascript-modules.html">modules</a></li><li>Make pages load
faster</li><li>Integrate <a shape="rect" class="external-link"
href="http://getbootstrap.com/"; >Bootstrap</a></li><li>Make it easier for rich
client libraries such as <a shape="rect" class="external-link"
href="http://backbonejs.org/"; >Backbone</a> or <a shape="rect"
class="external-link" href="https://angularjs.org/"; >AngularJS</a> to operate
within a page</li><li>Properly document Tapestry's client support</li></ul><h3
id="Client-SideJavaScript-TheOverallVision">The Overall Vision</h3><p>The
overall vision for the client-side in Tapestry is encapsulation, at several
different levels.</p><p>On the server-side, a Tapestry component (or mixin)
will exposes configurable parameters. The component will write DOM elements or
attributes, as well as some amount of JavaScript init
ialization. The encapsulation here allows developers with little or no
knowledge of client-side JavaScript to enjoy the benefits (as consumers of
components created by developers who are versed in client-side coding and
Tapestry components).</p><p>On the client-side, the JavaScript combines with
the special markup to produce the behaviors that are desired ... anything from
controlling the initial focus field, to performing client-side input field
validation, to running complex Ajax workflows.</p><p>Where possible, all of
this behavior is driven by <code>data-</code> attributes on the elements,
combined with top-level event handlers. On the client side, events are used not
only to respond directly to user actions (with "click", "mouseOver", "submit",
or other event listeners) but also to allow elements to collaborate in various
ways.  For example, input validation is based on triggering a specific
custom event on each form control element, and top-level event handlers can
then m
anage the validation for any number of fields.</p><h3
id="Client-SideJavaScript-Prototypevs.jQuery">Prototype vs. jQuery</h3><p>For
several years, it has been obvious that Tapestry "backed the wrong horse" with
respect to Prototype and jQuery. When the first code was being laid down in
2007 or 2008, it wasn't so clear that jQuery with its odd abstractions and
unfamiliar approach, would go on to conquer the world. Meanwhile, Prototype was
very strongly integrated into Ruby on Rails and had first class documentation
and books.</p><p>That being said, jQuery may not be the be-all and end-all.
Tapestry 5.4 introduces an abstraction layer, that allows many components to
write code that doesn't care whether the foundation framework in Prototype or
jQuery. This is especially useful during the arduous process of moving Tapestry
5.3 client-side code forward to 5.4.</p><p>If you like jQuery then there's no
problem: write your application using just jQuery and you can ignore a lot of
the featur
es in the abstraction layer. Your code will likely be just a bit more
efficient.</p><p>If you are building a reusable component or library, writing
to the abstraction layer may be worth the effort; it is entirely possible that
someone may write a replacement for the abstraction layer that targets your
favorite foundation framework, such as ExtJS, MooTools, or something not even
known of today.</p><h3 id="Client-SideJavaScript-Heavyvs.Light">Heavy vs.
Light</h3><p>Earlier Tapestry JavaScript was <em>heavy</em>. Essentially,
each component would write some very specific JavaScript initialization that
would include the component's DOM id and many other details. This
initialization would reference a function on the <code>T5.inits</code>
namespace.</p><p>The function there would typically locate the specific element
by its client DOM id, then attach event handlers to the one element. It might
also create some form of client-side controller object. There were issues due
to this: for
complex pages (or perhaps even typical pages), the "blob" of JavaScript
initialization at the bottom of the page could be quite large.</p><p>The use of
individual event handlers meant that Tapestry applications would use more
client-side objects that a bespoke jQuery solution ... because the normal
approach in jQuery is to attach a single event handler to the document or body
that handles any events that bubble up to the top <em>and</em> match a CSS
selector.</p><p>In Tapestry 5.4, the goal is to make
things <em>light</em>. In most cases, there will not be a specific
initialization function; instead a <a shape="rect"
href="javascript-modules.html">JavaScript module</a> will be loaded, and it
will install one or more top-level event handlers; the elements will have <a
shape="rect" class="external-link"
href="https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes";
><code>data-</code> attributes</a> that are used by those top level handlers
to recognize
which elements they are responsible for.</p><p>This is more of a full
lifecycle approach; adding or removing page content (such as with a <a
shape="rect" href="ajax-and-zones.html">Zone</a> component) is both cheaper and
less error prone using top-level event handlers than per-element event
handlers; there's also less of a chance of memory leaks under Internet
Explorer.</p> <div class="aui-message warning shadowed information-macro">
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
<p>Internet Explorer is pretty well known for
memory leaks; its DOM and JavaScript run in different kinds of memory, which
are garbage collected individually. This means that a reference from JavaScript
to a DOM element will keep the DOM element live, even if that's the only
reference to the DOM element anywhere. Meanwhile, event handler JavaScript
functions are kept live from the DOM element, making a cycle that can't be
broken. Libraries like Prototype and jQuery have to expend some effort to break
this link by unregistering event handlers from DOM elements when removing them
from the DOM.</p>
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 Sun Nov 9
23:19:47 2014
@@ -114,7 +114,7 @@
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="confluence-site-setup.html">Confluence Site Setup</a>
+ <a shape="rect"
href="developer-bible.html">Developer Bible</a>
</div>
@@ -123,81 +123,18 @@
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="developer-bible.html">Developer Bible</a>
+ <a shape="rect"
href="confluence-site-setup.html">Confluence Site Setup</a>
</div>
</li></ul>
-</div>
-
-<p>This document describes our web site setup: what is where and how it
works.</p>
-
-<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 shape="rect" 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 shape="rect" 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 20 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
shape="rect" 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 19 minutes after the hour you'll see the change in about a minute. If
you publish it at 21 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 shape="rect"
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 shape="rect"
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 shape="rect" 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
>shape="rect" 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
shape="rect" 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 shape="rect" 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 shape="rect" 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 li
stings, 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 shape="rect"
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 shape="rect"
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 shape="rect"
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 shape="rect" href="index.html">Index</a> page includes the <a
shape="rect" href="banner.html">Banner</a> and <a shape="rect"
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 shape="rect" href="navigation.html">Navigation</a>, <a
shape="rect" href="small-banner.html">Small Banner</a> and <a shape="rect"
href="footer.html">Footer</a> pages exist.</p>
-
-<p>Our SiteExporter template (described above) glues everything together. It
adds the contents of the <a shape="rect" href="navigation.html">Navigation</a>
and <a shape="rect" href="footer.html">Footer</a> pages in the appropriate
places and on all pages except the <a shape="rect" href="index.html">Index</a>
page. It also adds the contents of the <a shape="rect"
href="small-banner.html">Small Banner</a> page as well as the breadcrumbs
navigation.</p>
-
- <div class="aui-message problem shadowed information-macro">
+</div><p>This document describes our web site setup: what is where and how it
works.</p><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 shape="rect"
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 shape="rect" 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 afte
r 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 shape="rect"
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 almo
st 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 shape="rect" 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 shape="rect"
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 shape="rect"
class="external-link"
href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/tr
unk">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 shape="rect"
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 chang
e.</p><p>To pick up changes to the original CXF SiteExporter code, just
compare <a shape="rect" 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 shape="rect" 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 shape="rect" 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 section
s 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 shape="rect"
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 shape="rect"
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 shape="rect"
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
shape="rect" href="index.html">Index</a> page includes the <a shape="rect"
href="banner.html">Banner</a> and <a shape="rect" 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 shape="rect"
href="navigation.html">Navigation</a>, <a shape="rect"
href="small-banner.html">Small Banner</a> and <a shape="rect"
href="footer.html">Footer</a> pages exist.</p><p>Our SiteExporter template
(described above) glues everything together. It adds the contents of the <a
shape="rect" href="navigation.html">Navigation</a> and <a shape="rect"
href="footer.html">Footer</a> pages in the appropriate places and on all pages
except the <a shape="rect" href="index.html">Index</a> page. It also adds the
contents of the <a shape="rect" href="small-banner.html">Small Banner</a> page
as well as the breadcrumbs navigation.</p> <div class="aui-message problem
shadowed information-macro">
<span class="aui-icon icon-problem">Icon</span>
<div class="message-content">
-
-<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>
+ <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-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>
