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 2007/05/28 06:21:45 UTC
svn commit: r542105 - in /tapestry/tapestry4/trunk: src/site/apt/ajax/
src/site/xdoc/usersguide/
tapestry-annotations/src/java/org/apache/tapestry/annotations/
tapestry-annotations/src/site/xdoc/
Author: jkuhnert
Date: Sun May 27 21:21:43 2007
New Revision: 542105
URL: http://svn.apache.org/viewvc?view=rev&rev=542105
Log:
Some documentation cleanup.
Modified:
tapestry/tapestry4/trunk/src/site/apt/ajax/debugging.apt
tapestry/tapestry4/trunk/src/site/apt/ajax/eventlistener.apt
tapestry/tapestry4/trunk/src/site/apt/ajax/responsebuilder.apt
tapestry/tapestry4/trunk/src/site/xdoc/usersguide/bindings.xml
tapestry/tapestry4/trunk/src/site/xdoc/usersguide/template.xml
tapestry/tapestry4/trunk/tapestry-annotations/src/java/org/apache/tapestry/annotations/EventListener.java
tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml
Modified: tapestry/tapestry4/trunk/src/site/apt/ajax/debugging.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/apt/ajax/debugging.apt?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/src/site/apt/ajax/debugging.apt (original)
+++ tapestry/tapestry4/trunk/src/site/apt/ajax/debugging.apt Sun May 27 21:21:43 2007
@@ -26,9 +26,16 @@
+-----------------------------------------------------------
This simple configuration example should be enough to turn on an enormous amount of detail on the inner workings of the
- {{{../apidocs/org/apache/tapestry/services/ResponseBuilder.html}ResponseBuilder}} service. The global ResponseBuilder hivemind service
- already comes pre-configured with the hivemind {{{http://hivemind.apache.org/hivemind1/hivemind/LoggingInterceptor.html}logging interceptor}}
- service, so you should be able to watch as each of the core methods on that interface are invoked.
+ {{{../apidocs/org/apache/tapestry/services/ResponseBuilder.html}ResponseBuilder}} service. The global
+ {{{../tapestry-framework/hivedoc/service/tapestry.globals.ResponseBuilder.html}tapestry.globals.ResponseBuilder}} hivemind service
+ should be a great place to apply the hivemind {{{http://hivemind.apache.org/hivemind1/hivemind/LoggingInterceptor.html}logging interceptor}}
+ service. An example of applying the logging interceptor would be:
+
++----------------------------------------------------------------------------------
+<implementation service-id="tapestry.globals.ResponseBuilder">
+ <interceptor service-id="hivemind.LoggingInterceptor" />
+</implementation>
++----------------------------------------------------------------------------------
Client Side Debugging
@@ -39,7 +46,7 @@
* Configuration
The logging facilities employed on the client side work in much the same way as the standard log4j style logging semantics many people are used to. The options
- for turning this kind of logging on / configuration can all be controlled through the {{{../components/general/shell.html}Shell}} or ScriptIncludes components -
+ for turning this kind of logging on / configuration can all be controlled through the {{{../components/general/shell.html}Shell}} or {{{../components/general/scriptincludes.html}ScriptIncludes}} components -
whichever you use in your projects.
There are 3 core configuration parameters to these components that control the majority of logic here:
Modified: tapestry/tapestry4/trunk/src/site/apt/ajax/eventlistener.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/apt/ajax/eventlistener.apt?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/src/site/apt/ajax/eventlistener.apt (original)
+++ tapestry/tapestry4/trunk/src/site/apt/ajax/eventlistener.apt Sun May 27 21:21:43 2007
@@ -10,22 +10,24 @@
The {{{../tapestry-annotations/index.html#EventListener}EventListener}} annotation is probably going to
be the most frequently used new feature <(if history from tacos users is any indicator)> in
- Tapestry 4.1. It offers an awful lot, and is based around the functionality now familiar to many
- in {{{http://dojotoolkit.org}dojo}}'s {{{http://manual.dojotoolkit.org/WikiHome/DojoDotBook/Book10}event API}}.
+ Tapestry 4.1. It offers an awful lot, and is based around the functionality now familiar to many
+ in {{{http://dojotoolkit.org}dojo}}'s {{{http://dojotoolkit.org/book/dojo-book-0-4/part-5-connecting-pieces/event-system-0}event API}}.
<<See also:>> {{{../tapestry-annotations/index.html#EventListener}EventListener}} core annotation documentation., {{{http://www.quirksmode.org/js/introevents.html}Quircksmode}}
At its core this new annotation allows you to bind client side events to page/component
- {{{../UsersGuide/listenermethods.html}listener}} methods. "Client Side" events can have a lot
+ {{{../usersguide/listenermethods.html}listener}} methods. "Client Side" events can have a lot
of different meanings. It could mean listening to function calls on a Tapestry
{{{../apidocs/org/apache/tapestry/dojo/IWidget.html}supported}} dojo widget,
- or it could mean listening to changing field values in a Tapestry {{{../components/Form.html}Form}} component.
+ or it could mean listening to changing field values in a Tapestry {{{../components/form/form.html}Form}} component.
-* Basic example, listening to DOM events
+* Basic example, listening to pure DOM events
In this example we want to be notified whenever anyone moves their mouse over a particular
- html element on our page.:
-
+ html element on our page. :
+
+ <<Note:>> Not to be confused with listening to elements rendered by components, for that use the target attribute.
+
+-----------------------------------------------------------
....
<body>
@@ -76,7 +78,7 @@
** Listening to widget functions
- In this example we want our {{{../UsersGuide/listenermethods.html}listener}} method to
+ In this example we want our {{{../usersguide/listenermethods.html}listener}} method to
be called when the {{{../apidocs/org/apache/tapestry/dojo/form/Autocompleter.html}Autocomplete}}
component on our page has selected an entry.
@@ -104,7 +106,7 @@
"validators=validators:required"})
public abstract Autocompleter getProjectSelection();
-@EventListener(targets = "projectChoose", events = "selectOption")
+@EventListener(targets = "projectChoose", events = "onValueChanged")
public void projectSelected()
{
// do something
@@ -118,15 +120,17 @@
supposed to do with an event that comes from a
{{{../apidocs/org/apache/tapestry/form/IFormComponent.html}IFormComponent}} that
doesn't also submit and update the form value that was changed?
-
- To add automatic submission to our form we only need to modify the definition of our annotation
- so that it also submits our form named <<<myform>>> before invoking our
- {{{../UsersGuide/listenermethods.html}listener}}. <(asynchronously)>
+
+ Nothing! If you specify a component target that already implements {{{../apidocs/org/apache/tapestry/form/IFormComponent.html}IFormComponent}}
+ the event system will automatically wire up the form submission for you.
+
+ In the rare instance where you would want to submit some <<other>> form instead of the default you can do so
+ by using the <<<submitForm>>> parameter.
+-----------------------------------------------------------------------
....
-@EventListener(targets = "projectChoose", events = "selectOption",
+@EventListener(targets = "projectChoose", events = "onValueChanged",
submitForm = "myForm")
public void projectSelected()
{
@@ -136,13 +140,30 @@
....
+-----------------------------------------------------------------------
- That's it! When your {{{../UsersGuide/listenermethods.html}listener}} is invoked you can be confident
- that your <<<projectSelect>>> {{{../apidocs/org/apache/tapestry/dojo/form/Autocompleter.html}Autocomplete}}
+ That's it! When your {{{../usersguide/listenermethods.html}listener}} is invoked you can be confident
+ that your <<<projectSelect>>> {{{../components/dojo/autocompleter.html}Autocompleter}}
component has also been updated to reflect the currently selected value.
As an added bonus, form validation is turned off by default with the {{{../tapestry-annotations/index.html#EventListener}EventListener}}
annotation as the majority use case is likely to be one off individual events where invoking
client side validation would be a cumbersome experience for users.
+
+** Turning off asynchronous submissions
+
+ There are some rare instances where you want to wire up an event to a {{{../apidocs/org/apache/tapestry/form/IFormComponent.html}IFormComponent}} that
+ you would like to cause a submission but not have it happen asynchronously. For that you can use the <<<async=false>>> attribute.
+
++-----------------------------------------------------------------------
+....
+
+@EventListener(targets = "projectChoose", events = "onValueChanged", async = false)
+public void projectSelected()
+{
+ // do something
+}
+
+....
++-----------------------------------------------------------------------
* A note about event names
Modified: tapestry/tapestry4/trunk/src/site/apt/ajax/responsebuilder.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/apt/ajax/responsebuilder.apt?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/src/site/apt/ajax/responsebuilder.apt (original)
+++ tapestry/tapestry4/trunk/src/site/apt/ajax/responsebuilder.apt Sun May 27 21:21:43 2007
@@ -40,8 +40,7 @@
+-----------------------------------------------------------------------
....
-@EventListener(targets = "projectChoose", events = "selectOption",
- submitForm = "myForm")
+@EventListener(targets = "projectChoose", events = "onValueChanged")
public void projectSelected(IRequestCycle cycle)
{
cycle.getResponseBuilder().updateComponent("myComponentId");
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?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/usersguide/bindings.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/usersguide/bindings.xml Sun May 27 21:21:43 2007
@@ -19,225 +19,225 @@
<title>Component Bindings</title>
</properties>
<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>clientId</td>
- <td>The clientId of the given component.</td>
- <td>clientId:myForm</td>
- <td>ognl:components.myForm.clientId</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>meta</td>
- <td>References a meta configured value for a specific component/page or global configuration file. (such as APPNAME.application or FooComponent.jwc)</td>
- <td>meta:renderIfTags</td>
- <td>n/a</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="../apidocs/org/apache/tapestry/form/translator/Translator.html">
- Translator
- </a>
- instance.
- </td>
- <td>translator:number,pattern=#</td>
- <td />
- </tr>
- <tr>
- <td>validators</td>
- <td>
- List of configured
- <a
- href="../apidocs/org/apache/tapestry/form/validator/Validator.html">
- Validator
- </a>
- instances (used with
- <a href="../components/form/textfield.html">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>
+ <section name="Component Bindings">
<p>
- You can define your own prefixes by contributing into the
- tapestry.bindings.BindingFactories configuration point.
+ 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>
- </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-framework/hivedoc/config/tapestry.form.translator.Translators.html">
- tapestry.form.translator.Translators
- </a>
- </td>
- </tr>
- <tr>
- <td>state</td>
- <td>
- <a href="../tapestry-framework/hivedoc/config/tapestry.state.ApplicationObjects.html">
- tapestry.state.ApplicationObjects
- </a>
- </td>
- </tr>
- <tr>
- <td>validator</td>
- <td>
- <a href="../tapestry-framework/hivedoc/config/tapestry.valid.Validators.html">
- tapestry.valid.Validators
- </a>
- </td>
- </tr>
- </table>
-
- </section>
+ <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>clientId</td>
+ <td>The clientId of the given component.</td>
+ <td>clientId:myForm</td>
+ <td>ognl:components.myForm.clientId</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>meta</td>
+ <td>References a meta configured value for a specific component/page or global configuration file. (such as APPNAME.application or FooComponent.jwc)</td>
+ <td>meta:renderIfTags</td>
+ <td>n/a</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="../apidocs/org/apache/tapestry/form/translator/Translator.html">
+ Translator
+ </a>
+ instance.
+ </td>
+ <td>translator:number,pattern=#</td>
+ <td />
+ </tr>
+ <tr>
+ <td>validators</td>
+ <td>
+ List of configured
+ <a
+ href="../apidocs/org/apache/tapestry/form/validator/Validator.html">
+ Validator
+ </a>
+ instances (used with
+ <a href="../components/form/textfield.html">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>
+ <p>
+ You can define your own prefixes by contributing into the
+ <a href="../tapestry-framework/hivedoc/config/tapestry.bindings.BindingFactories.html">tapestry.bindings.BindingFactories</a> configuration point.
+ </p>
+ </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-framework/hivedoc/config/tapestry.form.translator.Translators.html">
+ tapestry.form.translator.Translators
+ </a>
+ </td>
+ </tr>
+ <tr>
+ <td>state</td>
+ <td>
+ <a href="../tapestry-framework/hivedoc/config/tapestry.state.ApplicationObjects.html">
+ tapestry.state.ApplicationObjects
+ </a>
+ </td>
+ </tr>
+ <tr>
+ <td>validator</td>
+ <td>
+ <a href="../tapestry-framework/hivedoc/config/tapestry.valid.Validators.html">
+ tapestry.valid.Validators
+ </a>
+ </td>
+ </tr>
+ </table>
+
+ </section>
</body>
</document>
Modified: tapestry/tapestry4/trunk/src/site/xdoc/usersguide/template.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/usersguide/template.xml?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/usersguide/template.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/usersguide/template.xml Sun May 27 21:21:43 2007
@@ -28,16 +28,14 @@
<a href="http://opensymphony.com/webwork/">WebWork</a>
, Tapestry does not "plug into" an external templating system such as JavaServer
Pages or
- <a href="http://jakarta.apache.org/velocity/">Velocity</a>
+ <a href="http://velocity.apache.org/">Velocity</a>
. Instead, Tapestry integrates its own templating system.
-
</p>
<p>
Tapestry templates are designed to look like valid HTML files (component HTML
templates will just be snippets of HTML rather than complete pages). Tapestry
"hides" its extensions into special attributes of ordinary HTML elements.
-
</p>
<p>
@@ -46,18 +44,12 @@
</p>
<subsection name="Template locations">
-
-
-
<p>
The general rule of thumb is that a page's HTML template is simply an HTML file,
stored in the context root directory. That is, you'll have a
- <em>MyPage</em>
- .html HTML template, a WEB-INF/
- <em>MyPage</em>
- .page page specification, and a
- <em>MyPage</em>
- class, in some Java package.
+ <em>MyPage</em>.html HTML template, a WEB-INF/
+ <em>MyPage</em>.page page specification, and a
+ <em>MyPage</em> class, in some Java package.
</p>
<p>
Modified: tapestry/tapestry4/trunk/tapestry-annotations/src/java/org/apache/tapestry/annotations/EventListener.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-annotations/src/java/org/apache/tapestry/annotations/EventListener.java?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-annotations/src/java/org/apache/tapestry/annotations/EventListener.java (original)
+++ tapestry/tapestry4/trunk/tapestry-annotations/src/java/org/apache/tapestry/annotations/EventListener.java Sun May 27 21:21:43 2007
@@ -80,8 +80,8 @@
boolean focus() default false;
/**
- * If used in conjunction with {@link #submitForm()}, will either submit the form normally or
- * asynchronously. Default is asyncrhonous.
+ * If used in conjunction with {@link #submitForm()} <i>(or just targeting a {@link org.apache.tapestry.form.IFormComponent})</i>,
+ * will either submit the form normally or asynchronously. Default is asyncrhonous.
*
* @return True if form should be submitted asynchronously, false otherwise.
*/
Modified: tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml?view=diff&rev=542105&r1=542104&r2=542105
==============================================================================
--- tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml (original)
+++ tapestry/tapestry4/trunk/tapestry-annotations/src/site/xdoc/index.xml Sun May 27 21:21:43 2007
@@ -52,7 +52,7 @@
The
<a href="apidocs/org/apache/tapestry/annotations/Asset.html">Asset</a>
annotation is the equivalent of the
- <a href="../UsersGuide/spec.html#<asset> element"><asset></a>
+ <a href="../usersguide/spec.html#<asset> element"><asset></a>
element in a specification. The value attribute is the path to the asset
(possibly prefixed to indicate the domain for the path):
</p>
@@ -78,7 +78,7 @@
The
<a href="apidocs/org/apache/tapestry/annotations/Bean.html">Bean</a>
annotation is the equivalent of the
- <a href="../UsersGuide/spec.html#<bean> element"><bean></a>
+ <a href="../usersguide/spec.html#<bean> element"><bean></a>
element in a specification.
</p>
@@ -139,7 +139,7 @@
<a href="apidocs/org/apache/tapestry/annotations/Component.html">Component</a>
annotation is attached to an accessor method and allows a component type to be
defined in place, as with the
- <a href="../UsersGuide/spec.html#<component> element"><component></a>
+ <a href="../usersguide/spec.html#<component> element"><component></a>
element.
</p>
@@ -206,7 +206,7 @@
</a>
annotation is used to mark a Java class as a component, and allows several
properties normally specified using the
- <a href="../UsersGuide/spec.html#<component-specification> element">
+ <a href="../usersguide/spec.html#<component-specification> element">
<component-specification></a> element.
</p>
@@ -291,12 +291,11 @@
</p>
<source xml:space="preserve">
-@EventListener(events = "selectOption", targets = "projectChoose",
-submitForm = "taskForm", async=true)
+@EventListener(events = "onValueChanged", targets = "projectChoose")
public void projectSelected(IRequestCycle cycle)
{
- cycle.getResponseBuilder().updateComponent("projectDescription");
- cycle.getResponseBuilder().updateComponent("feedbackBlock");
+ cycle.getResponseBuilder().updateComponent("projectDescription");
+ cycle.getResponseBuilder().updateComponent("feedbackBlock");
}
</source>
@@ -315,17 +314,18 @@
<td>targets</td>
<td>String[],String</td>
<td>no</td>
- <td></td>
+ <td> </td>
<td>
Specifies the components/widgets to listen to events on, in the form of unique
- component ids. One of either elements OR targets must be supplied.
+ component ids. One of either elements OR targets must be supplied. This is supposed to
+ be the id as returned by <code>IComponent.getClientId()</code>.
</td>
</tr>
<tr>
<td>elements</td>
<td>String[],String</td>
<td>no</td>
- <td></td>
+ <td> </td>
<td>
Specifies the unique html element dom node ID's to listen to events on. One of
either elements OR targets must be supplied.
@@ -335,26 +335,34 @@
<td>events</td>
<td>String[],String</td>
<td>yes</td>
- <td></td>
+ <td> </td>
<td>
Specifies which javascript "events" to listen for. Just as with the dojo api, these
- events can be simple things like <code>onClick</code> or <code>onSubmit</code>, but can
+ events can be simple things like <code>onclick</code> or <code>onsubmit</code>, but can
also be bound to specific functions if they exist on the component/widget you are targeting.
- <p>
- For example, the Autocomplete component wraps a dojo ComboBox widget that has a function named
- <code>selectOption</code> that is called when an item in the list is selected.
- </p>
+ <br/><br />
+ For example, the Autocomplete component wraps a dojo ComboBox widget that has a function named
+ <code>onValueChanged</code> that is called when an item in the list is selected.
</td>
</tr>
<tr>
<td>submitForm</td>
<td>String</td>
<td>no</td>
- <td></td>
+ <td> </td>
<td>
If specified, the form matching the passed in form ID will be submitted before calling your
listener method.
+
+ <span class="info">
+ <strong>Information:</strong>
+ <p>
+ In almost all instances you will <i>not</i> want to use this parameter as any component
+ target implementing IFormComponent will automatically submit the form containing it for you. This
+ only needs to be used in the rare instance where you want to submit a different form.
+ </p>
+ </span>
</td>
</tr>
<tr>
@@ -363,8 +371,8 @@
<td>no</td>
<td>false</td>
<td>
- When used in conjunction with the <code>submitForm</code> parameter, optionally enables/disables
- client side validation when the form is submitted.
+ When targeting a component implementing IFormComponent, optionally enables/disables
+ both client side validation <em>and</em> server side validation when the form is submitted.
</td>
</tr>
<tr>
@@ -373,19 +381,53 @@
<td>no</td>
<td>true</td>
<td>
- When used in conjunction with the <code>submitForm</code> parameter, optionally submits the form
- via a dynamic asynchronous request, or submits it using normal http IO POST methods.
+ When components implementing IFormComponent are targeted and will cause a form submission this parameter
+ can additionally be used to cause the submission to happen with or without asynchronous (ajax) IO calls.
+ </td>
+ </tr>
+ <tr>
+ <td>autoSubmit</td>
+ <td>boolean</td>
+ <td>no</td>
+ <td>true</td>
+ <td>
+ When components implementing IFormComponent are targeted they will normally automatically cause a form
+ submission to happen so that the property they manage on your form is updated when your listener method
+ is called - this parameter can be used to disable the automatic submission of the enclosing form.
+
+ <span class="warn">
+ <strong>Warning:</strong>
+ <p>
+ Use at your own risk, this is no guarantee what kind of state your properties will be in when this method
+ is invoked. If you aren't relying on form specific properties to do things everything should be fine - just be careful.
+ </p>
+ </span>
+ </td>
+ </tr>
+ <tr>
+ <td>focus</td>
+ <td>boolean</td>
+ <td>no</td>
+ <td>false</td>
+ <td>
+ When components implementing IFormComponent are targeted and will cause a form submission this parameter
+ can additionally be used to turn on/off the normal client side form element focusing that normally happens in
+ Tapestry forms to focus the most important / first field in error. This can be annoying on AJAX IO calls and so is turned
+ off by default.
</td>
</tr>
</table>
</subsection>
+ <subsection name="Listener Parameters">
+ Many people have asked about the possibility of specifying a list of parameters to pass in to the listener method like you would
+ do with a <a href="../components/link/directlink.html">DirectLink</a> component. We are aware of this and hope to get it implemented
+ sometime in one of the upcoming Tapestry 4.X releases.
+ </subsection>
+
</subsection>
<subsection name="InitialValue">
-
-
-
<p>
The
<a href="apidocs/org/apache/tapestry/annotations/InitialValue.html">
@@ -450,7 +492,7 @@
<p>
This is equivalent to specifying the property attribute of the
- <a href="../UsersGuide/spec.html#<asset> element"><asset></a>
+ <a href="../usersguide/spec.html#<asset> element"><asset></a>
element.
</p>
@@ -475,7 +517,7 @@
<p>
This is functionally the same as providing the property attribute of the
- <a href="../UsersGuide/spec.html#<component> element"><component></a>
+ <a href="../usersguide/spec.html#<component> element"><component></a>
element.
</p>
@@ -488,7 +530,7 @@
The
<a href="apidocs/org/apache/tapestry/annotations/InjectMeta.html">InjectMeta</a>
annotation allows meta data from the specification (
- <a href="../UsersGuide/spec.html#<meta> element"><meta> elements</a> )
+ <a href="../usersguide/spec.html#<meta> element"><meta> elements</a> )
to be exposed as properties.
</p>
@@ -534,7 +576,7 @@
<p>
The end result is the same as using the
- <a href="../UsersGuide/spec.html#<inject> element"><inject></a>
+ <a href="../usersguide/spec.html#<inject> element"><inject></a>
element, with the default type of "object".
</p>
@@ -598,7 +640,7 @@
<p>
The end result is equivalent to using the
- <a href="../UsersGuide/spec.html#<inject> element"><inject></a>
+ <a href="../usersguide/spec.html#<inject> element"><inject></a>
element, with a type of "state".
</p>
@@ -636,7 +678,7 @@
<p>
The end result is equivalent to using the
- <a href="../UsersGuide/spec.html#<inject> element"><inject></a>
+ <a href="../usersguide/spec.html#<inject> element"><inject></a>
element, with a type of "state-flag".
</p>
@@ -740,7 +782,7 @@
<a href="apidocs/org/apache/tapestry/annotations/Meta.html">Meta</a>
annotation is used to define a meta data value on a page or component class, as
with the
- <a href="../UsersGuide/spec.html#<meta> element"><meta></a>
+ <a href="../usersguide/spec.html#<meta> element"><meta></a>
element in an XML component or page specification.
</p>
@@ -782,7 +824,7 @@
The
<a href="apidocs/org/apache/tapestry/annotations/Parameter.html">Parameter</a>
annotation defines a new property, as with
- <a href="../UsersGuide/spec.html#<parameter> element"><parameter></a>
+ <a href="../usersguide/spec.html#<parameter> element"><parameter></a>
element in an XML component specification.
</p>
@@ -850,7 +892,7 @@
<p>
This annotation works exactly like a
- <a href="../UsersGuide/spec.html#<property> element"><property></a>
+ <a href="../usersguide/spec.html#<property> element"><property></a>
element, except that the initial-value attribute can't be specified. Use the
<a href="#InitialValue">@InitialValue</a>
annotation to set the property's initial value.