You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2014/11/10 00:19:48 UTC
svn commit: r928541 - in /websites/production/tapestry/content:
cache/main.pageCache client-side-javascript.html confluence-site-setup.html
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>