tapestry-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r972100 - in /websites/production/tapestry/content: cache/main.pageCache page-navigation.html
Date Wed, 11 Nov 2015 14:19:39 GMT
Author: buildbot
Date: Wed Nov 11 14:19:38 2015
New Revision: 972100

Log:
Production update by buildbot for tapestry

Modified:
    websites/production/tapestry/content/cache/main.pageCache
    websites/production/tapestry/content/page-navigation.html

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

Modified: websites/production/tapestry/content/page-navigation.html
==============================================================================
--- websites/production/tapestry/content/page-navigation.html (original)
+++ websites/production/tapestry/content/page-navigation.html Wed Nov 11 14:19:38 2015
@@ -144,7 +144,7 @@
                         
                     </div>
     </li></ul>
-</div><p>In essence, a Tapestry application is a number of related pages, working
together. To some degree, each page is like an application unto itself.</p><p>Any
individual request will be targeted at a single page. Requests come in two forms:&#160;</p><ul><li><em>component
event</em> requests target a specific component on a specific page, triggering an event
within that component</li><li><em>render</em> requests target a specific
page, and stream the HTML markup for that page back to the client</li></ul><p>This
dichotomy between component event requests and render requests alleviates a number of problems
in traditional web applications related to the browser back button, or to the user hitting
the refresh button in their browser.</p><p><br clear="none"><span style="color:
rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Logical Page Name Shortening</span></p><p>In
certain cases, Tapestry will shorten the the logical name of a page. For example, the page
class org.example.page
 s.address.CreateAddress will be given a logical name of "address/Create" (the redundant "Address"
is removed as a suffix). However, this only affects how the page is referenced in URLs; the
template file will still be CreateAddress.tml, whether on the classpath, or as address/CreateAddress.tml
(in the web context).</p><p><span>Tapestry actually creates multiple names
for the name page: "address/Create" and "address/CreateAddress" are both synonymous. You can
user either in Java code that refers to a page by name, or as the page parameter of a PageLink.</span></p><h2
id="PageNavigation-ComponentEventRequests&amp;Responses">Component Event Requests &amp;
Responses</h2><p>Main Article: <a  href="component-events.html">Component
Events</a></p><p>Component event requests may take the form of hyperlinks
(<a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/EventLink.html">EventLink</a>
or <a  class="external-link" href="http://
 tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/ActionLink.html">ActionLink</a>)
or form submissions (<a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a>).</p><p>The
value returned from an <a  href="component-events.html">event handler method</a>
controls the response sent to the client web browser.</p><p>The URL for a component
event request identifies the name of the page, the nested id of the component, and the name
of the event to trigger on the component (this is usually "action"). Further, a component
event request may contain additional context information, which will be provided to the event
handler method.</p><p>These URLs expose a bit of the internal structure of the
application. Over time, as an application grows and is maintained, the ids of components may
change. This means that component event request URLs should not be bookmarked. Fortunately,
users will rare
 ly have the chance to do so (see below).</p><h3 id="PageNavigation-1.Nullresponse">1.
Null response</h3><p>If the event handler method returns no value, or returns
null, then the current page (the page containing the component) will render the response.</p><p>A
page render link for the current page is created and sent to the client as a client side redirect.
The client browser will automatically submit a new request to generate the page.</p><p>The
user will see the newly generated content in their browser. In addition, the URL in the browser's
address bar will be a render request URL. Render request URLs are shorter and contain less
application structure (for instance, they don't include component ids or event types). Render
requests URLs are what your users will bookmark. The component event request URLs are transitory,
meaningful only while the application is actively engaged, and not meant to be used in later
sessions.</p><div class="code panel pdl" style="border-width: 1px;"><di
 v class="codeContent panelContent pdl">
+</div><p>In essence, a Tapestry application is a number of related pages, working
together. To some degree, each page is like an application unto itself.</p><p>Any
individual request will be targeted at a single page. Requests come in two forms:&#160;</p><ul><li><em>component
event</em> requests target a specific component on a specific page, triggering an event
within that component</li><li><em>render</em> requests target a specific
page, and stream the HTML markup for that page back to the client</li></ul><p>This
dichotomy between component event requests and render requests alleviates a number of problems
in traditional web applications related to the browser back button, or to the user hitting
the refresh button in their browser.</p><p><br clear="none"><span style="color:
rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Logical Page Name Shortening</span></p><p>In
certain cases, Tapestry will shorten the the logical name of a page. For example, the page
class org.example.page
 s.address.CreateAddress will be given a logical name of "address/Create" (the redundant "Address"
is removed as a suffix). However, this only affects how the page is referenced in URLs; the
template file will still be CreateAddress.tml, whether on the classpath, or as address/CreateAddress.tml
(in the web context).</p><p><span>Tapestry actually creates multiple names
for the name page: "address/Create" and "address/CreateAddress" are both synonymous. You can
user either in Java code that refers to a page by name, or as the page parameter of a PageLink.</span></p><h2
id="PageNavigation-ComponentEventRequests&amp;Responses">Component Event Requests &amp;
Responses</h2><p>Main Article: <a  href="component-events.html">Component
Events</a></p><p>Component event requests may take the form of hyperlinks
(<a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/EventLink.html">EventLink</a>
or <a  class="external-link" href="http://
 tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/ActionLink.html">ActionLink</a>)
or form submissions (<a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a>).</p><p>The
value returned from an <a  href="component-events.html">event handler method</a>
controls the response sent to the client web browser.</p><p>The URL for a component
event request identifies the name of the page, the nested id of the component, and the name
of the event to trigger on the component (this is usually "action"). Further, a component
event request may contain additional context information, which will be provided to the event
handler method.</p><p>These URLs expose a bit of the internal structure of the
application. Over time, as an application grows and is maintained, the ids of components may
change. This means that component event request URLs should not be bookmarked. Fortunately,
users will rare
 ly have the chance to do so (see below).</p><h3 id="PageNavigation-1.Nullresponse">1.
Null response</h3><p>If the event handler method returns no value, or returns
null, then the current page (the page containing the component) will render the response.</p><p>A
page render URL for the current page is created and sent to the client as a client side redirect.
The client browser will automatically submit a new request to generate the page.</p><p>The
user will see the newly generated content in their browser. In addition, the URL in the browser's
address bar will be a render request URL. Render request URLs are shorter and contain less
application structure (for instance, they don't include component ids or event types). Render
requests URLs are what your users will bookmark. The component event request URLs are transitory,
meaningful only while the application is actively engaged, and not meant to be used in later
sessions.</p><div class="code panel pdl" style="border-width: 1px;"><div
  class="codeContent panelContent pdl">
 <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public
Object onAction(){
   return null;
 }</pre>
@@ -167,30 +167,48 @@ public Object onAction(){
 <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public
Object onAction(){
   return new HttpError(302, "The Error message);
 }</pre>
-</div></div><h3 id="PageNavigation-6.Linkresponse">6. Link response</h3><p>An
event handler method may return a <a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html">Link</a>
instance directly. The Link is converted into a URL and a client redirect to that URL is sent
to the client.</p><p>The <a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html">ComponentResources</a>
object that is injected into your pages (and components) has methods for creating component
links.</p><p>The&#160;<a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PageRenderLinkSource.html">PageRenderLinkSource</a>
service can be injected to allow links to other pages to be created (though that is rarely
necessary, given the other options listed above).</p><h3 id="PageNavigation-7.Streamresponse">7.
Stream response</h3><p>An event handler can als
 o return a <a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a>
object, which encapsulates a stream to be sent directly to the client browser. This is useful
for components that want to, say, generate an image or PDF and provide it to the client.</p><h3
id="PageNavigation-8.URLresponse">8. URL response</h3><p>A java.net.URL response
is handled as a client redirect to an external URL. (In Tapestry 5.3.x and earlier this only
works for non-Ajax requests.)</p><h3 id="PageNavigation-9.Objectresponse">9. Object
response</h3><p>Any other type of object returned from an event handler method
is an error.</p><h2 id="PageNavigation-PageRenderRequests">Page Render Requests</h2><p>Render
requests are simpler in structure and behavior than component event requests. In the simplest
case, the URL is simply the logical name of the page.</p><p>Pages may have an
<em>activation context</em>. The activation context repre
 sents persistent information about the state of the page. In practical terms, the activation
context is usually the id of some database-persistent object.</p><p>When a page
has an activation context, the values of the context are appended to the URL path.</p><p>Not
all pages have an activation context.</p><p>The activation context may be explicitly
set when the render request link is created (the PageLink component has a context parameter
for this purpose). When no explicit activation context is provided, the page itself is queried
for its activation context.</p><p>This querying takes the form of an event trigger.
The event name is "passivate" (as we'll see shortly, there's a corresponding "activate").
The return value of the method is used as the context. For example:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="PageNavigation-6.Linkresponse">6. Link response</h3><p>An
event handler method may return a <a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html">Link</a>
instance directly. The Link is converted into a URL and a client redirect to that URL is sent
to the client.</p><p>The <a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html">ComponentResources</a>
object that is injected into your pages (and components) has methods for creating component
links.</p><p>The&#160;<a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PageRenderLinkSource.html">PageRenderLinkSource</a>
service can be injected to allow links to other pages to be created (though that is rarely
necessary, given the other options listed above).</p><h3 id="PageNavigation-7.Streamresponse">7.
Stream response</h3><p>An event handler can als
 o return a <a  class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a>
object, which encapsulates a stream to be sent directly to the client browser. This is useful
for components that want to, say, generate an image or PDF and provide it to the client.</p><h3
id="PageNavigation-8.URLresponse">8. URL response</h3><p>A java.net.URL response
is handled as a client redirect to an external URL. (In Tapestry 5.3.x and earlier this only
works for non-Ajax requests.)</p><h3 id="PageNavigation-9.Objectresponse">9. Object
response</h3><p>Any other type of object returned from an event handler method
is an error.</p><h2 id="PageNavigation-PageRenderRequests">Page Render Requests</h2><p>Render
requests are simpler in structure and behavior than component event requests. In the simplest
case, the URL is simply the logical name of the page.</p><p>Pages may have an
<em>activation context</em>. The activation context repre
 sents persistent information about the state of the page. In practical terms, the activation
context is usually the id of some database-persistent object.</p><p>When a page
has an activation context, the values of the context are appended to the URL path. For example,
in&#160;<code>http://www.example.com/myapp/foo/bar</code> the "myapp" part
is the servlet context (usually the name of your app), and the "foo/bar" part is the activation
context, with "foo" being the first activation parameter and "bar" being the second.</p><p>It
is common for most pages to not have any activation context.</p><p>The activation
context may be explicitly set when the render request link is created (the PageLink component
has a context parameter for this purpose).</p><p>When no explicit activation context
is provided, the page itself is queried for its activation context. This querying takes the
form of an event trigger. The event name is "passivate" (as we'll see shortly, there's a corresponding
"activa
 te"). The return value of the method is used as the context. For example:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent
pdl">
 <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public
class ProductDetail
 {
   private Product product;
-
   . . .
-
   long onPassivate() { return product.getId(); }
 }
 </pre>
-</div></div><p>The activation context may consist of a series of values,
in which case the return value of the method should be an array or a List.</p><div
class="confluence-information-macro confluence-information-macro-information"><span
class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Note: If you are using the <a  href="hibernate-user-guide.html">tapestry-hibernate</a>
integration library and your passivate context is a Hibernate entity, then you can just use
the entity itself, not its id. Tapestry will automatically extract the entity's id into the
URL, and convert it back for the "activate" event handler method.</p></div></div><h2
id="PageNavigation-Pageactivation">Page activation</h2><p>When a page render
request arrives, the page is activated before it is rendered.</p><div class="navmenu"
style="float:right; background:#eee; margin:3px; padding:0 1em">
+</div></div><p>The activation context may consist of a series of values,
in which case the return value of the method should be an array or a List.</p><div
class="confluence-information-macro confluence-information-macro-information"><span
class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Note: If you are using the <a  href="hibernate-user-guide.html">tapestry-hibernate</a>
integration library and your passivate context is a Hibernate entity, then you can just use
the entity itself, not its id. Tapestry will automatically extract the entity's id into the
URL, and convert it back for the "activate" event handler method.</p></div></div><h2
id="PageNavigation-Pageactivation">Page activation</h2><p>When a page render
request arrives, the page is <em>activated</em> before it is rendered.</p><div
class="navmenu" style="float:right; background:#eee; margin:3px; padding:0 1em">
 <p>    <strong>JumpStart Demos:</strong><br clear="none">
     <a  class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/navigation/onactivateandonpassivate/3"
rel="nofollow">onActivate and onPassivate</a><br clear="none">
-    <a  class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/handlingabadcontext/1"
rel="nofollow">Handling A Bad Context</a></p></div>Activation serves
two purposes:<ul><li>It allows the page to restore its internal state from data
encoded into the URL (the activation context discussed above).</li><li>It provides
coarse approach to validating access to the page.<br clear="none"> The later case, validation,
is generally concerned with user identity and access; if you have pages that may only be accessed
by certain users, you may use the page's activate event handler responsible for verifying
that access.</li></ul><p>A page's activate event handler mirrors its passivate
handler:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">  .
. .
-
+    <a  class="external-link" href="http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/handlingabadcontext/1"
rel="nofollow">Handling A Bad Context</a></p></div>Activation serves
two purposes:<ul><li>It allows the page to restore its internal state from data
encoded into the URL (the activation context discussed above).</li><li>It provides
coarse approach to validating access to the page.</li></ul><p>The later
case &#8211; validation&#160;&#8211; is generally concerned with user identity
and access; if you have pages that may only be accessed by certain users, you may use the
page's activate event handler for verifying that access.</p><p>Page activation
uses Tapestry's <em>Component Event</em> mechanism. See <a  href="component-events.html">Component
Events</a> for details.</p><p>A page's activate event handler mirrors its
passivate handler:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">  private
Product product;
+  . . .
   void onActivate(long productId)
   {
      product = productDAO.getById(productId);
   }
+  . . .
+</pre>
+</div></div><p>Here's the relevant part: when the page renders, it is likely
to include more component event request URLs (links and forms). The component event requests
for those links and forms will <em>also</em> start by activating the page, before
performing other work. This forms an unbroken chain of requests that include the same activation
context.</p><p>To some degree, this same effect could be accomplished using a
<a  href="persistent-page-data.html">persistent page value</a>, but that requires
an active servlet session, and the result is not bookmarkable.</p><p>Your activate
event handler, like any event handler, may also return a value, which is treated identically
to a return value of a component event method. This technique is commonly used as a simple
access validation mechanism.</p><p>You sometimes need to handle multiple page
activation scenarios in one page class. You could create multiple activate event handler methods
with different arguments (see the "Multiple Me
 thod Matches" section at <a  href="component-events.html">Component Events</a>
for details), but if you do so, you should generally return&#160;<code>true</code>
from each to avoid having more than one activation event handler method from being called
for each page request. However, a better approach is to create one method with an EventContext
argument. Tapestry will populate the EventContext argument with all of the activation parameters,
and the EventContext's&#160;<code>get</code> method will retrieve and coerce
each parameter to the desired type. For example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">  .
. .
+
+  void onActivate(EventContext eventContext) {
+
+    String color = DEFAULT_COLOR;
+
+    if (eventContext.getCount() &gt; 0) {
+      long productId = eventContext.get(Long.class, 0);
+
+      if (eventContext.getCount() &gt; 1) {
+        String color = eventContext.get(String.class, 1);
+      }
+      product = productDAO.getById(productId, color);
+    } else {
+      return SelectProduct.class; // no product selected
+    }
+  }
 
   . . .
 </pre>
-</div></div><p>Here's the relevant part: when the page renders, it is likely
to include more component event request URLs (links and forms). The component event requests
for those links and forms will <em>also</em> start by activating the page, before
performing other work. This forms an unbroken chain of requests that include the same activation
context.</p><p>To some degree, this same effect could be accomplished using a
<a  href="persistent-page-data.html">persistent page value</a>, but that requires
an active session, and the result is not bookmarkable.</p><p>The activate event
handler may also return a value, which is treated identically to a return value of a component
event request event trigger. This will typically be used in an access validation scenario.</p><h2
id="PageNavigation-PageNavigationPatterns">Page Navigation Patterns</h2><p>This
combination of action links and context and page context can be put together in any number
of ways.</p><p>Let's take a typical master/d
 etail relationship using the concept of a product catalog page. In this example, the ProductListing
page is a list of products, and the ProductDetails page must display the details for a specific
product.</p><h3 id="PageNavigation-Pattern1:Componenteventrequests/PersistentData">Pattern
1: Component event requests / Persistent Data</h3><p>In this pattern, the ProductListing
page uses action events and a persistent field on the ProductDetails page.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>ProductListing.html</b></div><div
class="codeContent panelContent pdl">
+</div></div><h2 id="PageNavigation-PageNavigationPatterns">Page Navigation
Patterns</h2><p>This combination of action links and context and page context
can be put together in any number of ways.</p><p>Let's take a typical master/detail
relationship using the concept of a product catalog page. In this example, the ProductListing
page is a list of products, and the ProductDetails page must display the details for a specific
product.</p><h3 id="PageNavigation-Pattern1:Componenteventrequests/PersistentData">Pattern
1: Component event requests / Persistent Data</h3><p>In this pattern, the ProductListing
page uses action events and a persistent field on the ProductDetails page.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>ProductListing.html</b></div><div
class="codeContent panelContent pdl">
 <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">  &lt;t:loop
source="products" value="product"&gt;
     &lt;a t:type="actionlink" t:id="select" context="product.id"&gt;${product.name}&lt;/a&gt;
   &lt;/t:loop&gt;



Mime
View raw message