tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jkuhn...@apache.org
Subject svn commit: r418775 [1/2] - in /tapestry/tapestry4/trunk/src/site: resources/css/site.css resources/images/favicon.ico site.xml xdoc/UsersGuide/bindings.xml xdoc/UsersGuide/index.xml xdoc/UsersGuide/listenermethods.xml xdoc/UsersGuide/template.xml
Date Mon, 03 Jul 2006 14:32:24 GMT
Author: jkuhnert
Date: Mon Jul  3 07:32:23 2006
New Revision: 418775

URL: http://svn.apache.org/viewvc?rev=418775&view=rev
Log:
facelift

Removed:
    tapestry/tapestry4/trunk/src/site/resources/images/favicon.ico
Modified:
    tapestry/tapestry4/trunk/src/site/resources/css/site.css
    tapestry/tapestry4/trunk/src/site/site.xml
    tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml
    tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/index.xml
    tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/listenermethods.xml
    tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/template.xml

Modified: tapestry/tapestry4/trunk/src/site/resources/css/site.css
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/resources/css/site.css?rev=418775&r1=418774&r2=418775&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/resources/css/site.css (original)
+++ tapestry/tapestry4/trunk/src/site/resources/css/site.css Mon Jul  3 07:32:23 2006
@@ -1,40 +1,76 @@
-a.externalLink, a.externalLink:link, a.externalLink:visited, a.externalLink:active, a.externalLink:hover
{
-  background: none;
-  padding-right: 0;
+a.externalLink,a.externalLink:link,a.externalLink:visited,a.externalLink:active,a.externalLink:hover
{
+    background: none;
+    padding-right: 0;
+}
+
+body {
+    font-family: Lucida Grande, Arial, Helvetica, sans-serif;
 }
 
 body ul {
-  list-style-type: square;
+    list-style-type: square;
 }
 
 #downloadbox {
-  float: right;
-  margin: 0 1em 2em 2em;
-  padding: 1em;
-  border: 1px solid #999;
-  background-color: #eee;
+    float: right;
+    margin: 0 1em 2em 2em;
+    padding: 1em;
+    border: 1px solid #999;
+    background-color: #eee;
 }
 
 #downloadbox h5 {
-  color: #000;
-  margin: 0;
-  border-bottom: 1px solid #aaaaaa;
-  font-size: smaller;
-  padding: 0;
+    color: #000;
+    margin: 0;
+    border-bottom: 1px solid #aaaaaa;
+    font-size: smaller;
+    padding: 0;
 }
 
 #downloadbox p {
-  margin-top: 1em;
-  margin-bottom: 0;
+    margin-top: 1em;
+    margin-bottom: 0;
 }
 
 #downloadbox ul {
-  margin-top: 0;
-  margin-bottom: 1em;
-  list-style-type: disc;
+    margin-top: 0;
+    margin-bottom: 1em;
+    list-style-type: disc;
 }
 
 #downloadbox li {
-  font-size: smaller;
+    font-size: smaller;
+}
+
+.info {
+    float: left;
+    display: block;
+    margin: 0 1em 2em 2em;
+    padding: 1em;
+    border: 1px solid #aaa;
+    background-color: #efefef;
+}
+
+.warn {
+    float: left;
+    display: block;
+    margin: 0 1em 2em 2em;
+    padding: 1em;
+    border: 2px solid #474747;
+    background-color: #B8AC30;
 }
 
+.section p a {
+    color: #539126;
+    font-weight: bolder;
+}
+
+.section p a:hover {
+    text-decoration: underline;
+}
+
+code {
+    border: 1px dotted #aaa;
+    background: #efefef;
+    padding: 1px;
+}

Modified: tapestry/tapestry4/trunk/src/site/site.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/site.xml?rev=418775&r1=418774&r2=418775&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/site.xml (original)
+++ tapestry/tapestry4/trunk/src/site/site.xml Mon Jul  3 07:32:23 2006
@@ -30,6 +30,7 @@
         <head>
             <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"></script>
             <script type="text/javascript">_uacct = "UA-400821-1"; urchinTracker();</script>
+            <link rel="shortcut icon" href="favicon.ico" />
         </head>
         
         <menu name="Quick Links" inherit="top" >

Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml?rev=418775&r1=418774&r2=418775&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/bindings.xml Mon Jul  3 07:32:23 2006
@@ -1,181 +1,245 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- 
-   Copyright 2005 The Apache Software Foundation
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+    Copyright 2005 The Apache Software Foundation
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+    http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
 -->
 <document>
-<properties>
-<title>Component Bindings</title>
-</properties>
-<body>
-  
-<p>
-Components are configured by <em>binding</em> their parameters.  Binding of parameters
-may occur inside a page or component template, or a page or component specification.
-</p>  
-  
-<p>
-When binding a component parameter, the value to be bound may be just a literal string, or
-it could be an <a href="http://www.ognl.org">OGNL</a> expression, or subject
to any of a number of other interpretations.  Tapestry
-uses a <em>prefix</em>   value, such as "ognl:", or "message:", to identify how
the rest of the
-value is to be interpreted.  The prefix identifies the <em>binding type</em>:
-</p>  
+    <properties>
+        <title>Component Bindings</title>
+    </properties>
+    <body>
     
-
-<table>
-  <tr>
-    <th>Binding Type</th>
-    <th>Description</th>
-    <th>Example</th>
-    <th>OGNL Equivalent</th>
-  </tr>
-  
-  <tr>
-    <td>asset</td>
-    <td>References an asset of the component.</td>
-    <td>asset:stylesheet </td>
-    <td>ognl:assets.stylesheet</td>
-  </tr>
-  
-  <tr>
-    <td>bean</td>
-    <td>References a named bean (defined by a <a href="spec.html#spec.bean">&lt;bean&gt;</a>
element).</td>
-    <td>bean:validationDelegate</td>
-    <td>ognl:beans.validationDelegate</td>
-  </tr>
-  
-  <tr>
-    <td>component</td>
-    <td>References a nested component with the provided component id.</td>
-    <td>component:form</td>
-    <td>ognl:components.form</td>
-  </tr>
-  
-  <tr>
-    <td>hivemind</td>
-    <td>References a HiveMind object, much like <a href="spec.html#spec.inject">&lt;inject&gt;</a>.</td>
-    <td>hivemind:service:app.MyService</td>
-    <td/>
-  </tr>
-  
-  <tr>
-    <td>listener</td>
-    <td>The name of a <a href="listenermethods.html">listener method</a>.</td>
-    <td>listener:formSubmit</td>
-    <td>ognl:listeners.formSubmit</td>
-  </tr>
-  
-  <tr>
-    <td>literal</td>
-    <td>Used to "escape" a binding prefix, marking the suffix as a literal value.</td>
-    <td>literal:ognl:not-an-expression</td>
-    <td/>
-  </tr>
-  
-  <tr>
-    <td>message</td>
-    <td>References a localized message from the component's message catalog.</td>
-    <td>message:page-title</td>
-    <td>ognl:messages.getMessage("page-title")</td>
-  </tr>
-  
-  <tr>
-    <td>ognl</td>
-    <td>An OGNL expression to be evaluated.</td>
-    <td>ognl:engine.visit.admin</td>    
-    <td/>
-  </tr>
-  
-  <tr>
-    <td>state</td>
-    <td>True of false dependening on whether the named <a href="state.html#state.aso">application
state object</a> exists.</td>
-    <td>state:visit</td>
-    <td/>
-  </tr>
-  
-  <tr>
-    <td>translator</td>
-    <td>Initializer used to obtain and configure a <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/translator/Translator.html">Translator</a>
instance.</td>
-    <td>translator:number,pattern=#</td>
-    <td/>
-  </tr>
-  
-  <tr>
-    <td>validator</td>
-    <td>Initializer used to obtain and configure an <a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidator.html">IValidator</a>
instance (used with <a href="site:ValidField">ValidField</a>).</td>
-    <td>validator:string,required,minimumLength=5</td>
-    <td/>
-  </tr>
-  
-  <tr>
-    <td>validators</td>
-    <td>List of configured <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">Validator</a>
instances (used with <a href="site:TextField">TextField</a> and others). </td>
-    <td>validators:email,required,minLength=10</td>
-    <td/>
-  </tr>
-</table>
-
-<p>
- Most of these are quite straight forward; the 
-  <a href="validation.html#validation.validator-binding">validator, validators and
translator</a> prefixes
- require some additional description.
-</p>
-
-<p>
-<strong>Note:</strong>
-<br/>
-  You can define your own prefixes by contributing into the tapestry.bindings.BindingFactories
configuration point.
-</p>  
-
-<p>
-What happens when you omit a binding prefix?  In a page or component <em>template</em>,
the value it is assumed to be a literal string, as with the "literal:" prefix.
-In a page or component specification, or inside a Java annotation, the value is assumed to
be an <a href="http://www.ognl.org">OGNL</a> expression, as with the "ognl:" prefix
-(but even this can be configured).  You will occasionally have
-to use an explicit "literal:" prefix inside such files.
-</p>
-
-
-<p>
-  Many of the bindings are driven by a HiveMind configuration; the configuration will
-  define the available values, and contributing the configuration allows
-  new values to be defined.
-</p>
-
-<table>
-  <tr>
-    <th>Binding Prefix</th>
-    <th>Configuration</th>
-  </tr>
-  <tr>
-    <td>translator</td>
-    <td>
-<a href="../tapestry/hivedocs/config/tapestry.form.translator.Translators.html">tapestry.form.translator.Translators</a>
-</td>
-  </tr>
-  <tr>
-    <td>state</td>
-    <td>
-<a href="../tapestry/hivedocs/config/tapestry.state.ApplicationObjects.html">tapestry.state.ApplicationObjects</a>
-</td>
-  </tr>
-  <tr>
-    <td>validator</td>
-    <td>
-<a href="../tapestry/hivedocs/config/tapestry.valid.Validators.html">tapestry.valid.Validators</a>
-</td>
-  </tr>
-</table>
-  
-</body>
+    <section name="Component Bindings">
+        <p>
+            Components are configured by
+            <em>binding</em>
+            their parameters. Binding of parameters may occur inside a page or component
template,
+            or a page or component specification.
+        </p>
+
+        <p>
+            When binding a component parameter, the value to be bound may be just a literal
string,
+            or it could be an
+            <a href="http://www.ognl.org">OGNL</a>
+            expression, or subject to any of a number of other interpretations. Tapestry
uses a
+            <em>prefix</em>
+            value, such as <code>ognl:</code>, or <code>message:</code>,
to identify how the rest of the value is to be
+            interpreted. The prefix identifies the
+            <em>binding type</em>
+            :
+        </p>
+
+
+        <table>
+            <tr>
+                <th>Binding Type</th>
+                <th>Description</th>
+                <th>Example</th>
+                <th>OGNL Equivalent</th>
+            </tr>
+
+            <tr>
+                <td>asset</td>
+                <td>References an asset of the component.</td>
+                <td>asset:stylesheet</td>
+                <td>ognl:assets.stylesheet</td>
+            </tr>
+
+            <tr>
+                <td>bean</td>
+                <td>
+                    References a named bean (defined by a
+                    <a href="spec.html#spec.bean">&lt;bean&gt;</a>
+                    element).
+                </td>
+                <td>bean:validationDelegate</td>
+                <td>ognl:beans.validationDelegate</td>
+            </tr>
+
+            <tr>
+                <td>component</td>
+                <td>References a nested component with the provided component id.</td>
+                <td>component:form</td>
+                <td>ognl:components.form</td>
+            </tr>
+
+            <tr>
+                <td>hivemind</td>
+                <td>
+                    References a HiveMind object, much like
+                    <a href="spec.html#spec.inject">&lt;inject&gt;</a>
+                    .
+                </td>
+                <td>hivemind:service:app.MyService</td>
+                <td />
+            </tr>
+
+            <tr>
+                <td>listener</td>
+                <td>
+                    The name of a
+                    <a href="listenermethods.html">listener method</a>
+                    .
+                </td>
+                <td>listener:formSubmit</td>
+                <td>ognl:listeners.formSubmit</td>
+            </tr>
+
+            <tr>
+                <td>literal</td>
+                <td>Used to "escape" a binding prefix, marking the suffix as a literal
value.</td>
+                <td>literal:ognl:not-an-expression</td>
+                <td />
+            </tr>
+
+            <tr>
+                <td>message</td>
+                <td>References a localized message from the component's message catalog.</td>
+                <td>message:page-title</td>
+                <td>ognl:messages.getMessage("page-title")</td>
+            </tr>
+
+            <tr>
+                <td>ognl</td>
+                <td>An OGNL expression to be evaluated.</td>
+                <td>ognl:engine.visit.admin</td>
+                <td />
+            </tr>
+
+            <tr>
+                <td>state</td>
+                <td>
+                    True of false dependening on whether the named
+                    <a href="state.html#state.aso">application state object</a>
+                    exists.
+                </td>
+                <td>state:visit</td>
+                <td />
+            </tr>
+
+            <tr>
+                <td>translator</td>
+                <td>
+                    Initializer used to obtain and configure a
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/translator/Translator.html">
+                        Translator
+                    </a>
+                    instance.
+                </td>
+                <td>translator:number,pattern=#</td>
+                <td />
+            </tr>
+
+            <tr>
+                <td>validator</td>
+                <td>
+                    Initializer used to obtain and configure an
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidator.html">
+                        IValidator
+                    </a>
+                    instance (used with
+                    <a href="site:ValidField">ValidField</a>
+                    ).
+                </td>
+                <td>validator:string,required,minimumLength=5</td>
+                <td />
+            </tr>
+
+            <tr>
+                <td>validators</td>
+                <td>
+                    List of configured
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">
+                        Validator
+                    </a>
+                    instances (used with
+                    <a href="site:TextField">TextField</a>
+                    and others).
+                </td>
+                <td>validators:email,required,minLength=10</td>
+                <td />
+            </tr>
+        </table>
+
+        <p>
+            Most of these are quite straight forward; the
+            <a href="validation.html#validation.validator-binding">
+                validator, validators and translator
+            </a>
+            prefixes require some additional description.
+        </p>
+
+        <span class="info">
+            <strong>Note:</strong>
+            <br />
+            You can define your own prefixes by contributing into the
+            tapestry.bindings.BindingFactories configuration point.
+        </span>
+
+        <p>
+            What happens when you omit a binding prefix? In a page or component
+            <em>template</em>
+            , the value it is assumed to be a literal string, as with the "literal:" prefix.
In a
+            page or component specification, or inside a Java annotation, the value is assumed
to be
+            an
+            <a href="http://www.ognl.org">OGNL</a>
+            expression, as with the "ognl:" prefix (but even this can be configured). You
will
+            occasionally have to use an explicit "literal:" prefix inside such files.
+        </p>
+
+
+        <p>
+            Many of the bindings are driven by a HiveMind configuration; the configuration
will
+            define the available values, and contributing the configuration allows new values
to be
+            defined.
+        </p>
+
+        <table>
+            <tr>
+                <th>Binding Prefix</th>
+                <th>Configuration</th>
+            </tr>
+            <tr>
+                <td>translator</td>
+                <td>
+                    <a
+                        href="../tapestry/hivedocs/config/tapestry.form.translator.Translators.html">
+                        tapestry.form.translator.Translators
+                    </a>
+                </td>
+            </tr>
+            <tr>
+                <td>state</td>
+                <td>
+                    <a href="../tapestry/hivedocs/config/tapestry.state.ApplicationObjects.html">
+                        tapestry.state.ApplicationObjects
+                    </a>
+                </td>
+            </tr>
+            <tr>
+                <td>validator</td>
+                <td>
+                    <a href="../tapestry/hivedocs/config/tapestry.valid.Validators.html">
+                        tapestry.valid.Validators
+                    </a>
+                </td>
+            </tr>
+        </table>
+    
+    </section>
+    </body>
 </document>

Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/index.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/index.xml?rev=418775&r1=418774&r2=418775&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/index.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/index.xml Mon Jul  3 07:32:23 2006
@@ -46,7 +46,7 @@
                 logic). Tapestry takes care of the plumbing necessary to connect these user
actions
                 with the objects.
             </p>
-
+            
             <p>
                 This can take some getting used to. You don't write servlets in Tapestry,
you write
                 <a href="listenermethods.html">listener method</a>
@@ -109,7 +109,7 @@
                     any query parameters, so that you can pass along the information you
need in the
                     URL.
                 </p>
-
+                
                 <p>
                     You are also responsible for connecting your output pages (whether they
are
                     JSPs,
@@ -150,7 +150,7 @@
                     .
                 </p>
 
-                <p>
+                <span class="info">
                     <strong>Note:</strong>
                     <br />
                     Listener methods in Tapestry are very similar in intent to
@@ -159,7 +159,7 @@
                     an object. Calling this a "listener" or a "listener method" is a bit
of a naming
                     snafu; it should be called a "delegate" and a "delegate method" but the
existing
                     naming is too deeply entrenched to change any time soon.
-                </p>
+                </span>
 
                 <p>
                     You supply just the listener method ... not an entire servlet. Tapestry
takes

Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/listenermethods.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/listenermethods.xml?rev=418775&r1=418774&r2=418775&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/listenermethods.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/listenermethods.xml Mon Jul  3 07:32:23
2006
@@ -1,144 +1,194 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- 
-   Copyright 2005 The Apache Software Foundation
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+    Copyright 2005 The Apache Software Foundation
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+    http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
 -->
 <document>
-<properties>
-<title>Listener Methods</title>
-</properties>
-<body>
-
-<p>
-Listener methods are the main approach by which you add application-specific behavior to
your application.
-</p>  
-
-<p>
-Listener methods are a kind of call back; they are triggered when a form is submitted or
a link is clicked.  The listener methods
-exist within your page and component classes.  Components such as <a href="site:DirectLink">DirectLink</a>
and <a href="site:Form">Form</a> take a listener parameter,
-and you can use a listener: <a href="bindings.html">binding reference</a> to
use a listener method in your class as the listener.
-</p>
-
-<p>
-<strong>Note:</strong>
-<br/>
-The parameter type for listeners is <a href="../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">IActionListener</a>.
 Internally, Tapestry creates an object that implements
-that interface and uses reflection to invoke the corrsponding method  on your page or component
instance. On rare
-occasions, it is useful to create objects that implement the interface directly.  For pages,
components and the
-engine, there is a listeners property whose keys are the names of listener methods, but the
listener: binding reference
-is easier to use.
-</p>
-
-<p>
-A listener method is always a public  instance method.   It may take parameters, or not,
and may
-return void or certain other types.
-</p>
-
-<section name="Return Type">
-  
-  
-<p>
-A listener method may return void, may return a string, or may return an object that implements
<a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>.
-The last two options are used to change the <em>active page</em>, the page which
will render
-the response. Returning null will not change the active page (it defaults to the page containing
the
-link or form components which invoked the listener method).
-</p>
-
-<dl>
- <dt>void</dt>
- <dd>The listener method does not change the active page.</dd>
-
-<dt>java.lang.String</dt>
-<dd>The listener method may return the name of a page to activate (and render the response).
Returning
-null does not change the active page.</dd>
-
-<dt>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
-</dt>
-<dd>A non-null <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
will activate that page instance. The page object may be obtained
-from the request cycle, or via <a href="injection.html#injection.page">page injection</a>.
-</dd>
-
-<dt>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ILink.html">ILink</a>
-</dt>
-<dd>
-Returning a non-null <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ILink.html">ILink</a>
will send a redirect to the client for the URL associated with the link.
-This is commonly used to perform a <em>redirect-after-post</em>.
-</dd>
-</dl>
+    <properties>
+        <title>Listener Methods</title>
+    </properties>
+    <body>
+        
+        <section name="Listener Methods" >
+        <p>
+            Listener methods are the main approach by which you add application-specific
behavior to
+            your application.
+        </p>
+
+        <p>
+            Listener methods are a kind of call back; they are triggered when a form is submitted
or
+            a link is clicked. The listener methods exist within your page and component
classes.
+            Components such as
+            <a href="site:DirectLink">DirectLink</a>
+            and
+            <a href="site:Form">Form</a>
+            take a listener parameter, and you can use a listener:
+            <a href="bindings.html">binding reference</a>
+            to use a listener method in your class as the listener.
+        </p>
+
+        <span class="info">
+            <strong>Note:</strong>
+            <br />
+            The parameter type for listeners is
+            <a href="../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+                IActionListener
+            </a>
+            . Internally, Tapestry creates an object that implements that interface and uses
+            reflection to invoke the corrsponding method on your page or component instance.
On rare
+            occasions, it is useful to create objects that implement the interface directly.
For
+            pages, components and the engine, there is a listeners property whose keys are
the names
+            of listener methods, but the listener: binding reference is easier to use.
+        </span>
+
+        <p>
+            A listener method is always a public instance method. It may take parameters,
or not,
+            and may return void or certain other types.
+        </p>
+        
+        <subsection name="Return Type">
+
+            
+            <p>
+                A listener method may return void, may return a string, or may return an
object that
+                implements
+                <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+                . The last two options are used to change the
+                <em>active page</em>
+                , the page which will render the response. Returning null will not change
the active
+                page (it defaults to the page containing the link or form components which
invoked
+                the listener method).
+            </p>
+
+            <dl>
+                <dt>void</dt>
+                <dd>The listener method does not change the active page.</dd>
+
+                <dt>java.lang.String</dt>
+                <dd>
+                    The listener method may return the name of a page to activate (and render
the
+                    response). Returning null does not change the active page.
+                </dd>
+                
+                <dt>
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+                </dt>
+                <dd>
+                    A non-null
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/IPage.html">IPage</a>
+                    will activate that page instance. The page object may be obtained from
the
+                    request cycle, or via
+                    <a href="injection.html#injection.page">page injection</a>
+                    .
+                </dd>
+
+                <dt>
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ILink.html">
+                        ILink
+                    </a>
+                </dt>
+                <dd>
+                    Returning a non-null
+                    <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/ILink.html">
+                        ILink
+                    </a>
+                    will send a redirect to the client for the URL associated with the link.
This is
+                    commonly used to perform a
+                    <em>redirect-after-post</em>
+                    .
+                </dd>
+            </dl>
+
+        </subsection><!-- listenermethods.return -->
+
+
+
+        <subsection name="Listener Method Parameters">
+
+
+            <p>
+                When using the
+                <a href="site:DirectLink">DirectLink</a>
+                component, you may specify additional
+                <em>listener parameters</em>
+                . The listener parameters are encoded into the URL and will be available
in a later
+                request, when the listener is triggered.
+            </p>
+
+            <span class="info">
+                <strong>Note:</strong>
+                <br />
+                In Tapestry 3.0 and earlier,
+                <em>listener parameters</em>
+                were known as
+                <em>service parameters</em>
+                . In addition, listener methods had to be in a very fixed form, taking exactly
one
+                parameter of type
+                <a href="../tapestry-framework/apidocs/org/apache/tapestry/IRequestCycle.html">
+                    IRequestCycle
+                </a>
+                and returning void.
+            </span>
+
+            <p>The listener can gain access these parameters in one of two ways:</p>
+
+            <ul>
+                <li>
+                    By invoking the
+                    <code>getListenerParameters()</code>
+                    method of
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/IRequestCycle.html">
+                        IRequestCycle
+                    </a>
+                </li>
+                <li>
+                    By declaring a method parameter for
+                    <em>each</em>
+                    listener parameter (in order)
+                </li>
+            </ul>
+
+            <p>
+                Using the second method is usually the best way. The link parameter values
are
+                <em>not</em>
+                simply converted into strings, they are encoded as strings but maintain their
type;
+                therefore, the listener method parameters must be of the correct type.
+            </p>
+
+            <p>
+                For example, suppose that the link encoded a String objectId and an integer
index.
+                The component in the template names the listener method, and the two parameters
are
+                passed into the DirectLink as an OGNL list expression:
+            </p>
 
-</section> <!-- listenermethods.return -->
-
-
-
-<section name="Listener Method Parameters">
-  
-
-<p>
-When using the <a href="site:DirectLink">DirectLink</a> component, you may specify
additional <em>listener parameters</em>.  The listener parameters
-are encoded into the URL and will be available in a later request, when the listener is triggered.
-</p>
-
-<p>
-<strong>Note:</strong>
-<br/>
-In Tapestry 3.0 and earlier, <em>listener parameters</em> were known as <em>service
parameters</em>.  In addition,
-listener methods had to be in a very fixed form, taking exactly one parameter of type <a
href="../tapestry-framework/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a>
and returning void.
-</p>
-
-<p>
-The listener can gain access these parameters in one of two ways:</p>
-
-<ul>
-  <li>By invoking the <code>getListenerParameters()</code> method of <a
href="../tapestry-framework/apidocs/org/apache/tapestry/IRequestCycle.html">IRequestCycle</a>
-</li>
-  <li>By declaring a method parameter for <em>each</em> listener parameter
(in order)</li>  
-</ul>
-
-<p>
-Using the second method is usually the best way.  The link parameter values are <em>not</em>
simply
-converted into strings, they are encoded as strings but maintain their type; therefore, the
listener method
-parameters must be of the correct type.
-</p>
-
-<p>
-For example, suppose that the link encoded a String objectId and an integer index.  The component
-in the template names the listener method, and the two parameters are passed into the DirectLink
as an OGNL
-list expression:
-</p>
-
-<source xml:space="preserve">
+            <source xml:space="preserve">
 &lt;a jwcid="@DirectLink" listener="listener:doClick" parameters="ognl:{ objectId, index
}"&gt; . . . &lt;/a&gt;
 </source>
 
-<p>
-In the Java class, the listener method might look like:
-</p>
+            <p>In the Java class, the listener method might look like:</p>
 
-<source xml:space="preserve">
+            <source xml:space="preserve">
 public void doClick(String objectId, int index)
 {
   . . .
 }
 </source>
 
-<p>
-Alternately, the listener method could look like:
-</p>
+            <p>Alternately, the listener method could look like:</p>
 
-<source xml:space="preserve">
+            <source xml:space="preserve">
 public void doClick(IRequestCycle cycle)
 {
   Object[] parameters = cycle.getListenerParameters();
@@ -149,58 +199,91 @@
 }
 </source>
 
-<p>
-This second case is maintained in Tapestry 4.0 mostly for backwards compatibility, or to
handle the case
-where a single listener method must handle an indeterminate number of listener parameters.
-</p>
-
-<p>
-In fact, Tapestry does a search for the most appropriate method, given the number of listener
parameters:
-</p>
-
-<ul>
-  <li>public <em>type</em> <em>method</em>(<em>parameters</em>)</li>
-  <li>public <em>type</em> <em>method</em>(IRequestCycle cycle,
<em>parameters</em>)</li>
-  <li>public <em>type</em> <em>method</em>()</li>
-  <li>public <em>type</em> <em>method</em>(IRequestCycle cycle)</li>
-</ul>
-
-<p>
-Tapestry 3.0 and earlier only accepted the final variation (and it had to return void). 
Don't get too tricky with multiple overloadings
-of the method; Tapestry doesn't attempt to match the listener parameter types to the method
parameter types (it
-works just by comparing the <em>number</em> of parameters).  However, you can
count on Java boxing and autoboxing
-the parameter values (so you can use <code>int</code> and <code>java.lang.Integer</code>
interchangeably).
-</p>
+            <p>
+                This second case is maintained in Tapestry 4.0 mostly for backwards compatibility,
+                or to handle the case where a single listener method must handle an indeterminate
+                number of listener parameters.
+            </p>
+
+            <p>
+                In fact, Tapestry does a search for the most appropriate method, given the
number of
+                listener parameters:
+            </p>
+
+            <ul>
+                <li>
+                    public
+                    <em>type</em>
+                    <em>method</em>
+                    (
+                    <em>parameters</em>
+                    )
+                </li>
+                <li>
+                    public
+                    <em>type</em>
+                    <em>method</em>
+                    (IRequestCycle cycle,
+                    <em>parameters</em>
+                    )
+                </li>
+                <li>
+                    public
+                    <em>type</em>
+                    <em>method</em>
+                    ()
+                </li>
+                <li>
+                    public
+                    <em>type</em>
+                    <em>method</em>
+                    (IRequestCycle cycle)
+                </li>
+            </ul>
+
+            <p>
+                Tapestry 3.0 and earlier only accepted the final variation (and it had to
return
+                void). Don't get too tricky with multiple overloadings of the method; Tapestry
+                doesn't attempt to match the listener parameter types to the method parameter
types
+                (it works just by comparing the
+                <em>number</em>
+                of parameters). However, you can count on Java boxing and autoboxing the
parameter
+                values (so you can use
+                <code>int</code>
+                and
+                <code>java.lang.Integer</code>
+                interchangeably).
+            </p>
+
+        </subsection><!-- listenermethods.parameters -->
+
+        <subsection name="Invoking Listener Methods">
+
+
+
+            <p>
+                When creating components that accept a listener as a parameter, you should
not
+                invoke the
+                <a href="../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+                    IActionListener
+                </a>
+                directly, instead, you should inject the infrastructure:ListenerInvoker service
into
+                your component, and have it invoke the listener. The ListenerInvoker is extensible,
+                and application logic may depend on ListenerInvoker's behavior (commonly,
it is used
+                to mark transactions boundaries).
+            </p>
 
-</section> <!-- listenermethods.parameters -->
-
-<section name="Invoking Listener Methods">
-  
+            <p>In your component specification:</p>
 
-
-<p>
-When creating components that accept a listener as a parameter, you should not invoke the
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">IActionListener</a>
directly, instead, you should inject the infrastructure:ListenerInvoker service 
-into your component, and have it invoke the listener.  The ListenerInvoker is extensible,
and 
-application logic may depend on ListenerInvoker's behavior (commonly, it is used to mark
-transactions boundaries).
-</p>
-
-<p>
-In your component specification:
-</p>
-
-<source xml:space="preserve">
+            <source xml:space="preserve">
   &lt;parameter name="listener" required="yes"/&gt;
 
   &lt;inject property="listenerInvoker" object="infrastructure:listenerInvoker"/&gt;
 </source>
 
-<p>
-In your source code:
-</p>
+            <p>In your source code:</p>
 
-<source xml:space="preserve">
+            <source xml:space="preserve">
   public abstract IActionListener getListener();
   
   public abstract ListenerInvoker getListenerInvoker();
@@ -213,11 +296,13 @@
   invoker.invokeListener(listener, this, cycle);
 </source>
 
-<p>
-It is acceptible to pass null as the listener; this saves you the necessity of checking for
null
-when the listener is an optional parameter.
-</p>
-
-</section> <!-- listenermethods.invoking -->
-</body>
+            <p>
+                It is acceptible to pass null as the listener; this saves you the necessity
of
+                checking for null when the listener is an optional parameter.
+            </p>
+
+        </subsection><!-- listenermethods.invoking -->
+        
+        </section>
+    </body>
 </document>



Mime
View raw message