tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r932985 - in /websites/production/tapestry/content: cache/main.pageCache component-parameters.html principles.html
Date Tue, 16 Dec 2014 16:19:31 GMT
Author: buildbot
Date: Tue Dec 16 16:19:31 2014
New Revision: 932985

Log:
Production update by buildbot for tapestry

Modified:
    websites/production/tapestry/content/cache/main.pageCache
    websites/production/tapestry/content/component-parameters.html
    websites/production/tapestry/content/principles.html

Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/tapestry/content/component-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Tue Dec 16 16:19:31 2014
@@ -157,12 +157,12 @@
 </div></div><p>A component may have any number of parameters. Each parameter
has a specific name, a specific Java type (which may be a primitive value), and may be <em>optional</em>
or <em>required</em>.</p><p>Within a component class, parameters are
declared by using the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html">Parameter</a>
annotation on a private field, as we'll see below.</p><p><span class="confluence-anchor-link"
id="ComponentParameters-bindingparameters"></span></p><h1 id="ComponentParameters-ParameterBindings">Parameter
Bindings</h1><p>In Tapestry, a parameter is not a slot into which data is pushed:
it is a <em>connection</em> between a field of the component (marked with the
@Parameter annotation) and a property or resource of the component's container. (Components
can be nested, so the container can be either the page or another component.)</p><div
class="navmenu" style="float:r
 ight; background:white; margin:3px; padding:3px">
 <div class="panel" style="border-width: 1px;"><div class="panelHeader" style="border-bottom-width:
1px;"><b>Contents</b></div><div class="panelContent">
 <style type="text/css">/*<![CDATA[*/
-div.rbtoc1418667590913 {padding: 0px;}
-div.rbtoc1418667590913 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1418667590913 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1418746763176 {padding: 0px;}
+div.rbtoc1418746763176 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1418746763176 li {margin-left: 0px;padding-left: 0px;}
 
-/*]]>*/</style><div class="toc-macro rbtoc1418667590913">
-<ul class="toc-indentation"><li>Related Articles</li><li><a shape="rect"
href="#ComponentParameters-RenderVariables:Bindings">Render Variables: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Property:Bindings">Property: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Validate:Bindings">Validate: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Translate:Bindings">Translate: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Asset:Bindings">Asset: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Context:Bindings">Context: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-RequiredParameters">Required Parameters</a></li><li><a
shape="rect" href="#ComponentParameters-OptionalParameters">Optional Parameters</a></li><li><a
shape="rect" href="#ComponentParameters-ParameterBindingDefaults">Parameter Binding Defaults</a></li><li><a
shape="rect" href="#ComponentParameters-ParameterCaching">Parameter Cach
 ing</a></li></ul>
+/*]]>*/</style><div class="toc-macro rbtoc1418746763176">
+<ul class="toc-indentation"><li><a shape="rect" href="#ComponentParameters-ParameterBindings">Parameter
Bindings</a></li><li><a shape="rect" href="#ComponentParameters-BindingExpressions">Binding
Expressions</a></li><li><a shape="rect" href="#ComponentParameters-@Parameterannotation">@Parameter
annotation</a></li><li><a shape="rect" href="#ComponentParameters-Don'tusethe${...}syntax!">Don't
use the ${...} syntax!</a></li><li><a shape="rect" href="#ComponentParameters-InformalParameters">Informal
Parameters</a></li><li><a shape="rect" href="#ComponentParameters-ParametersAreBi-Directional">Parameters
Are Bi-Directional</a></li><li><a shape="rect" href="#ComponentParameters-InheritedParameterBindings">Inherited
Parameter Bindings</a></li><li><a shape="rect" href="#ComponentParameters-ComputedParameterBindingDefaults">Computed
Parameter Binding Defaults</a></li><li><a shape="rect" href="#ComponentParameters-UnboundParameters">Unbound
Parameters</a></li><li><a shape="rect" href="#Compon
 entParameters-ParameterTypeCoercion">Parameter Type Coercion</a></li><li><a
shape="rect" href="#ComponentParameters-ParameterNames">Parameter Names</a></li><li><a
shape="rect" href="#ComponentParameters-DeterminingifBound">Determining if Bound</a></li><li><a
shape="rect" href="#ComponentParameters-PublishingParameters">Publishing Parameters</a></li></ul>
 </div>
 </div></div></div><p>&#160;</p><p>The connection
between a component and a property (or resource) of its container is called a <em>binding</em>.
The binding is two-way: the component can read the bound property by reading its parameter
field. Likewise, a component that updates its parameter field will update the bound property.</p><p>This
is important in a lot of cases; for example a TextField component can read <em>and update</em>
the property bound to its value parameter. It reads the value when rendering, but updates
the value when the form is submitted.</p><p>The component listed below is a looping
component; it renders its body a number of times, defined by its <code>start</code>
and <code>end</code> parameters (which set the boundaries of the loop). The component
can update a <code>result</code> parameter bound to a property of its container;
it will automatically count up or down depending on whether <code>start</code>
or <code>end</code> is larger.</p><div class="code panel 
 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[package
org.example.app.components;

Modified: websites/production/tapestry/content/principles.html
==============================================================================
--- websites/production/tapestry/content/principles.html (original)
+++ websites/production/tapestry/content/principles.html Tue Dec 16 16:19:31 2014
@@ -82,7 +82,7 @@
                     <span class="icon icon-page" title="Page">Page:</span>  
         </div>
 
             <div class="details">
-                            <a shape="rect" href="principles.html">Principles</a>
+                            <a shape="rect" href="introduction.html">Introduction</a>
                     
                 
                             </div>
@@ -91,7 +91,7 @@
                     <span class="icon icon-page" title="Page">Page:</span>  
         </div>
 
             <div class="details">
-                            <a shape="rect" href="getting-started.html">Getting Started</a>
+                            <a shape="rect" href="tapestry-tutorial.html">Tapestry
Tutorial</a>
                     
                 
                             </div>
@@ -100,7 +100,7 @@
                     <span class="icon icon-page" title="Page">Page:</span>  
         </div>
 
             <div class="details">
-                            <a shape="rect" href="tapestry-tutorial.html">Tapestry
Tutorial</a>
+                            <a shape="rect" href="getting-started.html">Getting Started</a>
                     
                 
                             </div>
@@ -109,46 +109,13 @@
                     <span class="icon icon-page" title="Page">Page:</span>  
         </div>
 
             <div class="details">
-                            <a shape="rect" href="introduction.html">Introduction</a>
+                            <a shape="rect" href="principles.html">Principles</a>
                     
                 
                             </div>
         </li></ul>
-</div> 
-
-<h1 id="Principles-Principle1&#8211;StaticStructure,DynamicBehavior">Principle
1 &#8211; Static Structure, Dynamic Behavior</h1>
-
-<p>The concept of "Dynamic Behavior" should be pretty obvious when you are building
a web application; things should look different for different users/situations. But what does
it mean that Tapestry has "Static Structure?" Static structure implies that when you build
a page in Tapestry you are going to define all of the types of components that are used within
that page. Under no circumstance during the rendering or event processing of the page will
you be able to dynamically create a new type of component and place that into the component
tree.</p>
-
-<p>At first glance, this seems quite limiting ... other frameworks allow new elements
to be created on the fly; it's also a common feature of desktop GUIs such as Swing. But static
structure turns out to be not so limiting after all. You <em>can</em> create new
elements (you're actually re-rendering existing components with different properties). And
you have plenty of options for getting dynamic behavior out of your static structure; from
the simple conditional and looping components to the more advanced implementations of Tapestry's
BeanEditor or Grid components, Tapestry gives you control over what renders and when, and
even where it appears on the page. And starting in Tapestry 5.3 you can even use the <a
shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Dynamic.html">Dynamic
component</a>, which renders whatever is in an external template file.</p>
-
-<p>Why did Tapestry choose static structure as a core principle? It's really a matter
of meeting the requirements of agility and scalability.</p>
-
-<h2 id="Principles-Agility">Agility</h2>
-
-<p>Tapestry is designed to be an agile working environment; "code less, deliver more".
To support you writing less code Tapestry does a lot of work on your POJO pages and components
when first loading them. It also uses shared instances of page and component classes (shared
across multiple threads and requests). Having dynamically modifiable structure would imply
that each request has its own instance and, further, that the entire structure would need
to be serialized between requests so that it can be restored to handle later requests.</p>
-
-<p>Tapestry also makes you more agile by speeding up the development cycle with <a
shape="rect" href="class-reloading.html">Live Class Reloading</a>. Tapestry monitors
the file system for changes to Java page classes, component classes, service implementation
classes, HTML templates and component property files, and it hot-swaps the changes into the
running application without requiring a restart <em>or losing session data</em>.
This provides a very short code-save-view cycle that no other framework can touch.</p>
-
-<h2 id="Principles-Scalability">Scalability</h2>
-
-<p>When building large scale systems it is important to consider how your resources
are going to be used on each deployed server, and how that information is going to be shared
between servers. Static structure means that page instances do not need to be stored inside
the HttpSession and simple browsing users do not require extra system resources. This lean
use of the HttpSession is key to Tapestry's very high scalability, especially in a clustered
configuration. Again, linking an instance of a page to a particular client would require vastly
more server-side resources than having a single shared page instance.</p>
-
-<h1 id="Principles-Principle2&#8211;AdaptiveAPI">Principle 2 &#8211; Adaptive
API</h1>
-
-<p>A key feature of Tapestry 5 is its adaptive API.</p>
-
-<p>In traditional Java frameworks (including Struts, <a shape="rect" href="tapestry-for-jsf-users.html">JSF</a>
and even the now-ancient Tapestry 4) user code is expected to conform to the framework. You
create classes that extend from framework-provided base classes, or implement framework-provided
interfaces.</p>
-
-<p>This works well until you upgrade to the next release of the framework: with the
new features of the upgrade, you will more often than not experience breaks in backwards compatibility.
Interfaces or base classes will have changed and your existing code will need to be changed
to match.</p>
-
-<p>In Tapestry 5, the framework adapts to your code. You have control over the names
of the methods, the parameters they take, and the value that is returned. This is driven by
annotations, which tell Tapestry under what circumstances your methods are to be invoked.</p>
-
-<p>For example, you may have a login form and have a method that gets invoked when
the form is submitted:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
-public class Login
+</div><h1 id="Principles-Principle1&#8211;StaticStructure,DynamicBehavior">Principle
1 &#8211; Static Structure, Dynamic Behavior</h1><p>The concept of "Dynamic
Behavior" should be pretty obvious when you are building a web application; things should
look different for different users/situations. But what does it mean that Tapestry has "Static
Structure?" Static structure implies that when you build a page in Tapestry you are going
to define all of the types of components that are used within that page. Under no circumstance
during the rendering or event processing of the page will you be able to dynamically create
a new type of component and place that into the component tree.</p><p>At first
glance, this seems quite limiting ... other frameworks allow new elements to be created on
the fly; it's also a common feature of desktop GUIs such as Swing. But static structure turns
out to be not so limiting after all. You <em>can</em> create new elements (you're
actually re-rendering existi
 ng components with different properties). And you have plenty of options for getting dynamic
behavior out of your static structure; from the simple conditional and looping components
to the more advanced implementations of Tapestry's BeanEditor or Grid components, Tapestry
gives you control over what renders and when, and even where it appears on the page. And starting
in Tapestry 5.3 you can even use the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Dynamic.html">Dynamic
component</a>, which renders whatever is in an external template file.</p><p>Why
did Tapestry choose static structure as a core principle? It's really a matter of meeting
the requirements of agility and scalability.</p><h2 id="Principles-Agility">Agility</h2><p>Tapestry
is designed to be an agile working environment; "code less, deliver more". To support you
writing less code Tapestry does a lot of work on your POJO pages and component
 s when first loading them. It also uses shared instances of page and component classes (shared
across multiple threads and requests). Having dynamically modifiable structure would imply
that each request has its own instance and, further, that the entire structure would need
to be serialized between requests so that it can be restored to handle later requests.</p><p>Tapestry
also makes you more agile by speeding up the development cycle with <a shape="rect" href="class-reloading.html">Live
Class Reloading</a>. Tapestry monitors the file system for changes to Java page classes,
component classes, service implementation classes, HTML templates and component property files,
and it hot-swaps the changes into the running application without requiring a restart <em>or
losing session data</em>. This provides a very short code-save-view cycle that no other
framework can touch.</p><h2 id="Principles-Scalability">Scalability</h2><p>When
building large scale systems it is important to consider
  how your resources are going to be used on each deployed server, and how that information
is going to be shared between servers. Static structure means that page instances do not need
to be stored inside the HttpSession and simple browsing users do not require extra system
resources. This lean use of the HttpSession is key to Tapestry's very high scalability, especially
in a clustered configuration. Again, linking an instance of a page to a particular client
would require vastly more server-side resources than having a single shared page instance.</p><h1
id="Principles-Principle2&#8211;AdaptiveAPI">Principle 2 &#8211; Adaptive API</h1><p>A
key feature of Tapestry 5 is its adaptive API.</p><p>In traditional Java frameworks
(including Struts, <a shape="rect" href="tapestry-for-jsf-users.html">JSF</a>
and even the now-ancient Tapestry 4) user code is expected to conform to the framework. You
create classes that extend from framework-provided base classes, or implement framework-provid
 ed interfaces.</p><p>This works well until you upgrade to the next release of
the framework: with the new features of the upgrade, you will more often than not experience
breaks in backwards compatibility. Interfaces or base classes will have changed and your existing
code will need to be changed to match.</p><p>In Tapestry 5, the framework adapts
to your code. You have control over the names of the methods, the parameters they take, and
the value that is returned. This is driven by annotations, which tell Tapestry under what
circumstances your methods are to be invoked.</p><p>For example, you may have
a login form and have a method that gets invoked when the form is submitted:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public
class Login
 {
   @Persist
   @Property
@@ -177,130 +144,13 @@ public class Login
   }
 }
 ]]></script>
-</div></div>
-
-<p>This short snippet demonstrates a bit about how Tapestry operates. Pages and services
within the application are injected with the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html">Inject</a>
annotation. The method names, <code>onValidateFromForm()</code> and <code>onSuccessFromForm()</code>,
inform Tapestry about when each method is to be invoked. This naming convention identifies
the event that is handled, ("validate" and "success") and the id of the component from which
the event is triggered (the "form" component</p><p></p><p></p><p></p><p></p><p></p><p>&lt;style
type='text/css'&gt;
-.FootnoteMarker, .FootnoteNum a {
-  background: transparent url(/confluence/download/resources/com.adaptavist.confluence.footnoteMacros:footnote/gfx/footnote.png)
no-repeat top right;
-  padding: 1px 2px 0px 1px;
-  border-left: 1px solid #8898B8;
-  border-bottom: 1px solid #6B7C9B;
-  margin: 1px;
-  text-decoration: none;
-}
-.FootnoteNum a {
-  margin-top: 2px;
-  margin-right: 0px;
-}
-.FootnoteNum {
-  font-size: x-small;
-  text-align: right;
-  padding-bottom: 4px;
-}
-.footnote-th1 {
-  text-align: right;
-}
-.Footnote {
-  padding-left: 7px;
-  margin-bottom: 4px;
-  border: 1px none #DDDDDD;
-  writingMode: tb-rl;
-}
-.accessibility {
-     display: none;
-     visibility: hidden;
-}
-@media aural,braille,embossed {
-        .FootnoteMarker, .FootnoteNum a {
-         border: 1px solid #000000;
-         background: #ffffff none;
-    }
-    .accessibility {
-         display: run-in;
-         visibility: visible;
-    }
-}
-&lt;/style&gt;
-&lt;script type='text/javascript' language='JavaScript'&gt;
-//&lt;!--\n
-var effectInProgress = {};
-var despamEffect = function (id,effectType,duration) {
-  if ((effectInProgress[id]) || (typeof(Effect)=="undefined") || (typeof(Effect[effectType])=="undefined"))
return;
-  new Effect[effectType](id);
-  effectInProgress[id]=true;
-  setTimeout('effectInProgress[\"'+id+'\"]=false;',duration*1000);
-};
-var oldFootnoteId = '';
-var footnoteHighlight = function(id,pulsateNum) {
-  if (oldFootnoteId!='') document.getElementById('Footnote'+oldFootnoteId).style['borderStyle']
= 'none';
-  oldFootnoteId = id;
-  document.getElementById('Footnote'+id).style['borderStyle'] = 'solid';
-  despamEffect('Footnote'+id,'Highlight',1)
-  if (pulsateNum) despamEffect('FootnoteNum'+id,'Pulsate',3)
-}
-var footnoteMarkerHighlight = function(id) {
-  if (oldFootnoteId!='') document.getElementById('Footnote'+oldFootnoteId).style['borderStyle']
= 'none';
-  oldFootnoteId = '';
-  despamEffect('FootnoteMarker'+id,'Pulsate',3)
-}
-//--&gt;
-&lt;/script&gt;
-
-<sup id="FootnoteMarker1">
-    <a shape="rect" class="FootnoteMarker" name="FootnoteMarker1" href="#Footnote1" onclick="footnoteHighlight(&quot;1&quot;,true);"
alt="Footnote: Click here to display the footnote" title="Footnote: Click here to display
the footnote">
-            1
-    </a>
-</sup>
-</p><p></p><p></p><p></p><p></p><p></p>).<p></p>
-
-<p>The "validate" event is triggered to perform cross-field validations, and the "success"
event is only triggered when there are no validation errors. The <code>onSuccessFromForm()</code>
method's return value directs Tapestry on what to do next: jump to another page within the
application (here identified as the class for the page, but many other options exist). When
there are exceptions, the page will be redisplayed to the user.</p>
-
-<p>By contrast, in Tapestry 4 the Form component's listener parameter would be bound
to the method to invoke, by name. Further, the listener method had to be public. The Tapestry
5 approach not only supports multiple listeners, but also provides an improved separation
of view concerns (inside the page's HTML template) and logic concerns, inside the Java class.</p>
-
-<p>In many cases, additional information about the event is available and can be passed
into the method simply by adding parameters to the method. Again, Tapestry will adapt to your
parameters, in whatever order you supply them.</p>
-
-<p>Tapestry also saves you needless effort: the @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Property.html">Property</a>
annotation marks a field as readable and writable; Tapestry will provide the accessor methods
automatically.</p>
-
-<p>Finally, Tapestry 5 explicitly separates actions (requests that change things) and
rendering (requests that render pages) into two separate requests. Performing an action, such
as clicking an action link or submitting a form, results in a client-side redirect to the
new page. This is the "<a shape="rect" class="external-link" href="http://en.wikipedia.org/wiki/Post/Redirect/Get"
>Post/Redirect/Get</a>" pattern (alternatively "Post-Then-Redirect", or "Redirect
After Post"). This helps ensure that URLs in the browser are book-markable ... but also requires
that a bit more information be stored in the session between requests (using the @<a shape="rect"
class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Persist.html">Persist</a>
annotation).</p>
-
-<h1 id="Principles-Principle3&#8211;DifferentiatePublicvs.InternalAPIs">Principle
3 &#8211; Differentiate Public vs. Internal APIs</h1>
-
-<p>An issue plaguing much ancient versions of Tapestry (4 and earlier) was the lack
of a clear delineation between private, internal APIs and public, external APIs. The fact
that your code would extend from base objects but that many of the methods on those base objects
were "off limits" further confused the issue. This has been identified as a key factor in
the "steep learning curve of Tapestry" meme.</p>
-
-<p>Designed from a clean slate, Tapestry 5 is much more ruthless about what is internal
vs. external.</p>
-
-<p>First of all, anything inside the org.apache.tapestry5.internal package is internal.
It is part of the implementation of Tapestry. It is the man behind the curtain. You should
not ever need to directly use this code. It is a bad idea to do so, because internal code
may change from one release to the next without concern for backwards compatibility.</p>
-
-    <div class="aui-message success shadowed information-macro">
+</div></div><p>This short snippet demonstrates a bit about how Tapestry
operates. Pages and services within the application are injected with the @<a shape="rect"
class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html">Inject</a>
annotation. The method names, <code>onValidateFromForm()</code> and <code>onSuccessFromForm()</code>,
inform Tapestry about when each method is to be invoked. This naming convention identifies
the event that is handled, ("validate" and "success") and the id of the component from which
the event is triggered (the "form" component).</p><p>The "validate" event is triggered
to perform cross-field validations, and the "success" event is only triggered when there are
no validation errors. The <code>onSuccessFromForm()</code> method's return value
directs Tapestry on what to do next: jump to another page within the application (here identified
as the class for the page, but many other options exist).
  When there are exceptions, the page will be redisplayed to the user.</p><p>By
contrast, in Tapestry 4 the Form component's listener parameter would be bound to the method
to invoke, by name. Further, the listener method had to be public. The Tapestry 5 approach
not only supports multiple listeners, but also provides an improved separation of view concerns
(inside the page's HTML template) and logic concerns, inside the Java class.</p><p>In
many cases, additional information about the event is available and can be passed into the
method simply by adding parameters to the method. Again, Tapestry will adapt to your parameters,
in whatever order you supply them.</p><p>Tapestry also saves you needless effort:
the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Property.html">Property</a>
annotation marks a field as readable and writable; Tapestry will provide the accessor methods
automatically.</p><p>Finally, Tapes
 try 5 explicitly separates actions (requests that change things) and rendering (requests
that render pages) into two separate requests. Performing an action, such as clicking an action
link or submitting a form, results in a client-side redirect to the new page. This is the
"<a shape="rect" class="external-link" href="http://en.wikipedia.org/wiki/Post/Redirect/Get"
>Post/Redirect/Get</a>" pattern (alternatively "Post-Then-Redirect", or "Redirect
After Post"). This helps ensure that URLs in the browser are book-markable ... but also requires
that a bit more information be stored in the session between requests (using the @<a shape="rect"
class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Persist.html">Persist</a>
annotation).</p><h1 id="Principles-Principle3&#8211;DifferentiatePublicvs.InternalAPIs">Principle
3 &#8211; Differentiate Public vs. Internal APIs</h1><p>An issue plaguing
much ancient versions of Tapestry (4 and earlier) 
 was the lack of a clear delineation between private, internal APIs and public, external APIs.
The fact that your code would extend from base objects but that many of the methods on those
base objects were "off limits" further confused the issue. This has been identified as a key
factor in the "steep learning curve of Tapestry" meme.</p><p>Designed from a clean
slate, Tapestry 5 is much more ruthless about what is internal vs. external.</p><p>First
of all, anything inside the org.apache.tapestry5.internal package is internal. It is part
of the implementation of Tapestry. It is the man behind the curtain. You should not ever need
to directly use this code. It is a bad idea to do so, because internal code may change from
one release to the next without concern for backwards compatibility.</p>    <div
class="aui-message success shadowed information-macro">
                             <span class="aui-icon icon-success">Icon</span>
                 <div class="message-content">
-                            
-<p>If you ever find yourself forced to make use of internal APIs, please bring it up
on the developer mailing list; this is how we know which services should be exposed as public,
and fall under the backwards compatibility umbrella.</p>
+                            <p>If you ever find yourself forced to make use of internal
APIs, please bring it up on the developer mailing list; this is how we know which services
should be exposed as public, and fall under the backwards compatibility umbrella.</p>
                     </div>
     </div>
-
-
-<h1 id="Principles-Principle4&#8211;EnsureBackwardsCompatibility">Principle 4 &#8211;
Ensure Backwards Compatibility</h1>
-
-<p>Older versions of Tapestry were plagued by backwards compatibility problems with
every major release. Tapestry 5 did not even attempt to be backwards compatible to Tapestry
4. Instead, it laid the ground work for true backwards compatibility going forwards.</p>
-
-<p>Tapestry 5's API is based largely on naming conventions and annotations. Your components
are just ordinary Java classes; you annotate fields to allow Tapestry to maintain their state
or to allow Tapestry to inject resources, and you name (or annotate) methods to tell Tapestry
under what circumstances a method should be invoked.</p>
-
-<p>Tapestry will adapt to your classes. It will call your methods, passing in values
via method parameters. Instead of the rigidness of a fixed interface to implement, Tapestry
will simply adapt to your classes, using the hints provided by annotations and simple naming
conventions.</p>
-
-<p>Because of this, Tapestry 5 can change internally to a great degree without it affecting
any of the application code you write. This has finally cracked the backwards compatibility
nut, allowing you to have great assurance that you can upgrade to future releases of Tapestry
without breaking your existing applications.</p>
-
-<p>This is already evident in Tapestry 5.1, 5.2 and 5.3 where major new features and
improvements have occurred, while remaining 100% backwards compatible to Tapestry 5.0 &#8211;
as long as you've avoided the temptation to use internal APIs.</p>
-
-<hr>
-
-<p></p><p></p><p></p><p></p><p></p><p></p><p><table
class="Footnotes" style="width: 100%; border:none;" cellspacing="0" cellpadding="0" summary="This
table contains one or more notes for references made elsewhere on the page."><caption
class="accessibility">Footnotes</caption><thead class="accessibility"><tr
class="accessibility"><th colspan="1" rowspan="1" class="accessibility" id="footnote-th1">Reference</th><th
colspan="1" rowspan="1" class="accessibility" id="footnote-th2">Notes</th></tr></thead><tbody><tr
name="Footnote1"><td colspan="1" rowspan="1" valign="top" class="FootnoteNum" headings="footnote-th1">
-        <a shape="rect" id="FootnoteNum1" href="#FootnoteMarker1" onclick="footnoteMarkerHighlight(&quot;1&quot;);"
onmouseover="footnoteHighlight(&quot;1&quot;,false);" alt="Footnote: Click to return
to reference in text" title="Footnote: Click to return to reference in text">
-            1
-        </a>
-      </td><td colspan="1" rowspan="1" valign="top" class="Footnote" id="Footnote1"
width="100%" headings="footnote-th2">
-          The component id can be omitted, leaving the method name <code>onSuccess()</code>,
but that may cause confusion on a page that has multiple Form components triggering events,
so it's best to be specific about the source of the event.
-      </td></tr></tbody></table></p><p></p><p></p><p></p><p></p><p></p><p></p></div>
+<h1 id="Principles-Principle4&#8211;EnsureBackwardsCompatibility">Principle 4 &#8211;
Ensure Backwards Compatibility</h1><p>Older versions of Tapestry were plagued
by backwards compatibility problems with every major release. Tapestry 5 did not even attempt
to be backwards compatible to Tapestry 4. Instead, it laid the ground work for true backwards
compatibility going forwards.</p><p>Tapestry 5's API is based largely on naming
conventions and annotations. Your components are just ordinary Java classes; you annotate
fields to allow Tapestry to maintain their state or to allow Tapestry to inject resources,
and you name (or annotate) methods to tell Tapestry under what circumstances a method should
be invoked.</p><p>Tapestry will adapt to your classes. It will call your methods,
passing in values via method parameters. Instead of the rigidness of a fixed interface to
implement, Tapestry will simply adapt to your classes, using the hints provided by annotations
and simple naming conven
 tions.</p><p>Because of this, Tapestry 5 can change internally to a great degree
without it affecting any of the application code you write. This has finally cracked the backwards
compatibility nut, allowing you to have great assurance that you can upgrade to future releases
of Tapestry without breaking your existing applications.</p><p>This is already
evident in Tapestry 5.1, 5.2 and 5.3 where major new features and improvements have occurred,
while remaining 100% backwards compatible to Tapestry 5.0 &#8211; as long as you've avoided
the temptation to use internal APIs.</p><hr><p>&#160;</p></div>
 </div>
 
 <div class="clearer"></div>



Mime
View raw message