You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by jk...@apache.org on 2006/07/03 16:32:24 UTC
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
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"><bean></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"><inject></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"><bean></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"><inject></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">
<a jwcid="@DirectLink" listener="listener:doClick" parameters="ognl:{ objectId, index }"> . . . </a>
</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">
<parameter name="listener" required="yes"/>
<inject property="listenerInvoker" object="infrastructure:listenerInvoker"/>
</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>