Author: hlship
Date: Wed Mar 4 18:56:42 2009
New Revision: 750100
URL: http://svn.apache.org/viewvc?rev=750100&view=rev
Log:
TAP5-502: Improve the description of parameter passing and binding in the
documentation
Modified:
tapestry/tapestry5/trunk/src/site/apt/guide/parameters.apt
Modified: tapestry/tapestry5/trunk/src/site/apt/guide/parameters.apt
URL:
http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/src/site/apt/guide/parameters.apt?rev=750100&r1=750099&r2=750100&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/src/site/apt/guide/parameters.apt (original)
+++ tapestry/tapestry5/trunk/src/site/apt/guide/parameters.apt Wed Mar 4
18:56:42 2009
@@ -14,7 +14,20 @@
Parameters are defined by placing a
{{{../apidocs/org/apache/tapestry5/annotations/Parameter.html}Parameter}}
annotation
onto a private field.
-
+
+ In Tapestry, a parameter is not a slot into which data is pushed: it is a
<connection> between
+ a field of the component (marked with the @Parameter annotation) and a
property or resource
+ of the component's container. In most simple examples, the container is the
page, but since components
+ can have themselves have templates, sometime the container of a component is
another component.
+
+ The connection is called a <binding>. The binding is two-way: the component
can read the bound property
+ by reading its parameter field. Likewise, a component that updates its
parameter field will update
+ the bound property.
+
+ This is important in a lot of cases; for example a TextField component can
read <and update> the property
+ bound to its value parameter. It reads the value when rendering, but updates
the value when
+ the form is submitted.
+
The component listed below is a looping component; it renders its body
a number of times, defined by its start and end parameters (which set the
boundaries
of the loop). The component can update a value parameter bound to a
property of its container,
@@ -138,8 +151,16 @@
| var | Allows a render variable of the component to be read or
updated. |
*------------+----------------------------------------------------------------------------------+
+
+ Most of these binding prefixes allow parameters to be bound to read-only
values; for instance
+ a parameter bound to "message:some-key" will see the message for "some-key"
from its container's
+ message catalog in the field. If the component tries to update the parameter
(by setting the value
+ of the field), a runtime exception will be thrown to indicate that the value
is read-only.
+
+ Only prop: and var: binding prefixes are updateable.
+
Parameters have a default prefix, usually "prop:", that is used when the
prefix is not provided.
-
+
A <special prefix>, "inherit:", is used to support {{{#Inherited Parameter
Bindings}Inherted Parameter Bindings}}.
Render Variables
@@ -252,8 +273,8 @@
---
Tapestry will adjust the URL of the image so that it is processed by
Tapestry, not the servlet container.
- It will gain a URL that includes the applications version number, it will
have a far-future expires header,
- and (if the client supports it) it will be compressed before being sent to
the client.
+ It will gain a URL that includes the application's version number, it will
have a far-future expires header,
+ and (if the client supports it) its content will be compressed before being
sent to the client.
Supporting Informal Parameters
@@ -500,7 +521,7 @@
In Tapestry 5.1, you may use the publishParameters attribute of the
{{{../../apidocs/org/apache/tapestry5/annotations/Component.html}Component}}}
annotation. List one
or more parameters seperated by commas: those parameters of the
inner/embedded component become
- parameters of the outer component. You should not define a parameter field
in the outer component.
+ parameters of the outer component. You should <<not>> define a parameter
field in the outer component.
There are still cases where you want to use the "inherit:" binding prefix.
For example, if you have
several components that need to share a parameter, then you must do it the
Tapestry 5.0 way: a true parameter
