tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jkuhn...@apache.org
Subject svn commit: r420925 [9/9] - /tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/
Date Tue, 11 Jul 2006 16:54:18 GMT
Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/upgrade.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/upgrade.xml?rev=420925&r1=420924&r2=420925&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/upgrade.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/upgrade.xml Tue Jul 11 09:54:16 2006
@@ -1,64 +1,74 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- 
-   Copyright 2004, 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 2004, 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>Upgrading from Tapestry 3.0</title>
-</properties>
-<body>
- 
-<p>
-One goal of Tapestry 4.0 is to make upgrading from release 3.0 as painless as possible.  
-</p>
- 
-<p>
-Tapestry 4.0 still supports the Tapestry 3.0 DTDs (with minor exceptions). 
-</p>
+    <properties>
+        <title>Upgrading from Tapestry 3.0</title>
+    </properties>
+    <body>
 
-<section name="Defining the servlet path">
-  
-  
-<p>
-In Tapestry 3.0, the framework could automatically determine the servlet path (used when constructing new URLs), because there was only a
-single mapping.  The convention was to map the servlet to "/app", but any path-based mapping would automatically work.
-</p>  
-
-<p>
-Because of <a href="friendly-urls.html">friendly URLs</a>, there are any number of
-possible servlet mappings in Tapestry 4.0, so you must inform Tapestry what the correct
-mapping is.  It is necessary to define, to Tapestry, what this mapping is,
-using the org.apache.tapestry.servlet-path <a href="configuration.html#configuration.properties">configuration property</a>.
-</p>
-  
-</section> <!-- upgrade.servlet-path -->
 
-<section name="Defining Engine Services">
-  
-  
-<p>
-Tapestry 3.0 allowed engine services to be defined in the application specification using
-a &lt;service&gt; element. This is no longer supported in the 4.0 DTD.
-</p>
-  
-<p>
-Engine services are now defined using HiveMind, in the <code>tapestry.services.ApplicationServices</code> configuration point.
-The following is the chart service from the Workbench example:
-</p>
+        <section name="Upgrading from Tapestry 3.0">
+
+            <p>
+                One goal of Tapestry 4.0 is to make upgrading from release 3.0 as painless as
+                possible.
+            </p>
+
+            <p>Tapestry 4.0 still supports the Tapestry 3.0 DTDs (with minor exceptions).</p>
+
+            <section name="Defining the servlet path">
+
+
+                <p>
+                    In Tapestry 3.0, the framework could automatically determine the servlet path
+                    (used when constructing new URLs), because there was only a single mapping. The
+                    convention was to map the servlet to "/app", but any path-based mapping would
+                    automatically work.
+                </p>
+
+                <p>
+                    Because of
+                    <a href="friendly-urls.html">friendly URLs</a>
+                    , there are any number of possible servlet mappings in Tapestry 4.0, so you must
+                    inform Tapestry what the correct mapping is. It is necessary to define, to
+                    Tapestry, what this mapping is, using the org.apache.tapestry.servlet-path
+                    <a href="configuration.html#configuration.properties">configuration property</a>
+                    .
+                </p>
+
+            </section><!-- upgrade.servlet-path -->
+
+            <section name="Defining Engine Services">
+
+
+                <p>
+                    Tapestry 3.0 allowed engine services to be defined in the application
+                    specification using a &lt;service&gt; element. This is no longer supported in
+                    the 4.0 DTD.
+                </p>
+
+                <p>
+                    Engine services are now defined using HiveMind, in the
+                    <code>tapestry.services.ApplicationServices</code>
+                    configuration point. The following is the chart service from the Workbench
+                    example:
+                </p>
 
-<source xml:space="preserve">
+                <source xml:space="preserve">
   &lt;contribution configuration-id="tapestry.services.ApplicationServices"&gt;
     &lt;service name="chart" object="service:Chart"/&gt;
   &lt;/contribution&gt;
@@ -74,111 +84,139 @@
   &lt;/service-point&gt;
 </source>
 
-<p>
-The &lt;service&gt; element in a Tapestry 3.0 DTD is now <strong>ignored</strong>.
-</p>
-
-<p>
-The <a href="../tapestry-framework/apidocs/org/apache/tapestry/engine/IEngineService.html">IEngineService</a> interface has changed in non-backwards compatible ways. If your application created
-custom engine services, you will have to make changes to your code. If your custom service was
-based on the <code>org.apache.tapestry.engine.AbstractService</code> class, that class has been removed
-so you will have significant rewrites. As a suggested course of action, find the service
-that the original service was based on, and build a new service based on that Tapestry service.
-For example, if the original service was based on <code>org.apache.tapestry.asset.AssetService</code>, then
-get the source for the AssetService, and model your service after the new implementation.
-</p>
+                <p>
+                    The &lt;service&gt; element in a Tapestry 3.0 DTD is now
+                    <strong>ignored</strong>
+                    .
+                </p>
+
+                <p>
+                    The
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/engine/IEngineService.html">
+                        IEngineService
+                    </a>
+                    interface has changed in non-backwards compatible ways. If your application
+                    created custom engine services, you will have to make changes to your code. If
+                    your custom service was based on the
+                    <code>org.apache.tapestry.engine.AbstractService</code>
+                    class, that class has been removed so you will have significant rewrites. As a
+                    suggested course of action, find the service that the original service was based
+                    on, and build a new service based on that Tapestry service. For example, if the
+                    original service was based on
+                    <code>org.apache.tapestry.asset.AssetService</code>
+                    , then get the source for the AssetService, and model your service after the new
+                    implementation.
+                </p>
+
+            </section><!-- upgrade.service -->
+
+            <section name="Component Parameters">
+
+
+                <p>
+                    Tapestry 4.0 has greatly streamlined
+                    <a href="components.html#components.parameters">component parameters</a>
+                    .
+                </p>
+
+                <subsection name="Parameter Type">
+
+
+                    <p>
+                        In Tapestry 3.0, the
+                        <a href="spec.html#spec.parameter">&lt;parameter&gt;</a>
+                        element included a type attribute. This has been removed in Tapestry 4.0.
+                    </p>
+
+                    <p>
+                        The parameter type is now determined from the Java class, by examining the
+                        accessor methods for the property.
+                    </p>
+
+                    <p>
+                        Tapestry 3.0 required an exact match on values bound to parameters. The
+                        bound value had to be assignable to the parameter's type. In Tapestry 4.0,
+                        parameters include built-in
+                        <em>coercion</em>
+                        ; Tapestry will attempt to coerce the value extracted from the bound
+                        property into the correct type. This is especially useful when using literal
+                        bindings for numeric properties. For example, an HTML template may specify a
+                        numeric value to an attribute as a simple string:
+                    </p>
 
-</section>  <!-- upgrade.service -->
-
-<section name="Component Parameters">
-  
-  
-<p>
-Tapestry 4.0 has greatly streamlined  <a href="components.html#components.parameters">component parameters</a>.
-</p>
-
-<subsection name="Parameter Type">
-  
-
-<p>
-In Tapestry 3.0, the <a href="spec.html#spec.parameter">&lt;parameter&gt;</a> element included a type attribute. This has been removed in Tapestry 4.0.  
-</p>
-
-<p>
-The parameter type is now determined from the Java class, by examining the accessor methods for the property.
-</p>
-
-<p>
-Tapestry 3.0 required an exact match on values bound to parameters. The bound value had to be assignable to the parameter's type.
-In Tapestry 4.0, parameters include built-in <em>coercion</em>; Tapestry will attempt to coerce the value extracted from the bound property 
-into the correct type.
-This is especially useful when using literal bindings for numeric properties.  For example, an HTML template may specify a numeric value
-to an attribute as a simple string:
-</p>
-  
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   &lt;span jwcid="@MyComponent" intParam="50"/&gt;
 </source>
 
-<p>
-The type of the parameter is determined from the accessor method:
-</p>
+                    <p>The type of the parameter is determined from the accessor method:</p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
 public abstract class MyComponent . . .
 
   public abstract int getIntParam();
 </source>
-  
-<p>
-Tapestry will convert the string value to an integer automatically.
-</p>  
-
-<p>
-The coercion rules are driven by a number of configuration points and services, starting with
-the <code>tapestry.coerce.ValueConverter</code> service.
-</p>
 
-</subsection>
-  
-  
-<subsection name="Parameter Direction">
-  
+                    <p>Tapestry will convert the string value to an integer automatically.</p>
+
+                    <p>
+                        The coercion rules are driven by a number of configuration points and
+                        services, starting with the
+                        <code>tapestry.coerce.ValueConverter</code>
+                        service.
+                    </p>
+
+                </subsection>
+
+
+                <subsection name="Parameter Direction">
+
 
 
-<p>
-In Tapestry 3.0, it was necessary to inform Tapestry of how and when a component parameter property was accessed -- this
-was parameter direction.
-Parameter direction is now ignored; Tapestry 4.0 now generates smart, caching accessor methods for parameter properties that work properly
-in all cases.  In effect, all parameters are now of direction auto (but its a smarter, more flexible version of direction
-auto than was available in Tapestry 3.0).
-</p>
-
-<p>
-This may be of concern if your component used the custom parameter direction. In Tapestry 3.0, direction custom meant that your code
-would directly access the <a href="../tapestry-framework/apidocs/org/apache/tapestry/IBinding.html">IBinding</a> object for the parameter, and no property for the parameter would be created.  In Tapestry 4.0, 
-a property <em>will</em> be created ... even if you continue to use the 3.0 DTD and specify direction custom.
-</p>
-
-<p>
-<strong>Warning:</strong>
-<br/>
-  You should search for all component parameters that use direction custom and update the Java class.
-</p>
-
-<p>
-For example, if you had a Tapestry 3.0 specification for a listener parameter:
-</p>
+                    <p>
+                        In Tapestry 3.0, it was necessary to inform Tapestry of how and when a
+                        component parameter property was accessed -- this was parameter direction.
+                        Parameter direction is now ignored; Tapestry 4.0 now generates smart,
+                        caching accessor methods for parameter properties that work properly in all
+                        cases. In effect, all parameters are now of direction auto (but its a
+                        smarter, more flexible version of direction auto than was available in
+                        Tapestry 3.0).
+                    </p>
+
+                    <p>
+                        This may be of concern if your component used the custom parameter
+                        direction. In Tapestry 3.0, direction custom meant that your code would
+                        directly access the
+                        <a href="../tapestry-framework/apidocs/org/apache/tapestry/IBinding.html">
+                            IBinding
+                        </a>
+                        object for the parameter, and no property for the parameter would be
+                        created. In Tapestry 4.0, a property
+                        <em>will</em>
+                        be created ... even if you continue to use the 3.0 DTD and specify direction
+                        custom.
+                    </p>
+
+                    <span class="warn">
+                        <strong>Warning:</strong>
+                        <p>
+                            You should search for all component parameters that use direction custom
+                            and update the Java class.
+                        </p>
+                    </span>
+
+                    <p>
+                        For example, if you had a Tapestry 3.0 specification for a listener
+                        parameter:
+                    </p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   &lt;parameter name="listener" direction="custom" type="org.apache.tapestry.IActionListener"/&gt;  
 </source>
 
-<p>
-Then your 3.0 source code might look like:
-</p>
+                    <p>Then your 3.0 source code might look like:</p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   public abstract IBinding getListenerBinding();
   
   public void someMethod(. . .)
@@ -196,19 +234,15 @@
     . . .      
 </source>
 
-<p>
-In Tapestry 4.0, the specification is much simpler:
-</p>
+                    <p>In Tapestry 4.0, the specification is much simpler:</p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   &lt;parameter name="listener"/&gt;
 </source>
 
-<p>
-As is the Java code:
-</p>
+                    <p>As is the Java code:</p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   public abstract IActionListener getListener();
   
   public void someMethod(. . .)
@@ -222,74 +256,89 @@
   . . .
 </source>
 
-<p>
-Tapestry takes care of de-referencing the binding (if the parameter is bound), along with type checks or coercions.
-</p>
-
-</subsection>
-
-<subsection name="Accessing binding objects">
-  
-  
-<p>
-In Tapestry 3.0, it was possible to access a <a href="../tapestry-framework/apidocs/org/apache/tapestry/IBinding.html">IBinding</a> object for a parameter by defining an additional property in your component's
-Java code:
-</p>
+                    <p>
+                        Tapestry takes care of de-referencing the binding (if the parameter is
+                        bound), along with type checks or coercions.
+                    </p>
+
+                </subsection>
+
+                <subsection name="Accessing binding objects">
+
+
+                    <p>
+                        In Tapestry 3.0, it was possible to access a
+                        <a href="../tapestry-framework/apidocs/org/apache/tapestry/IBinding.html">
+                            IBinding
+                        </a>
+                        object for a parameter by defining an additional property in your
+                        component's Java code:
+                    </p>
 
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   public abstract IBinding getListenerBinding();
 </source>
 
-<p>
-This is no longer supported; the correct way to obtain a binding object is via the getBinding() method.  
-</p>
-
-<p>
-<strong>Note:</strong>
-<br/>
-Because of the other improvements to parameters, it is virtually never necessary to obtain a binding object.
-</p>
-  
-</subsection>
+                    <p>
+                        This is no longer supported; the correct way to obtain a binding object is
+                        via the getBinding() method.
+                    </p>
+
+                    <span class="info">
+                        <strong>Note:</strong>
+                        <p>
+                        Because of the other improvements to parameters, it is virtually never
+                        necessary to obtain a binding object.
+                        </p>
+                    </span>
+
+                </subsection>
+
+                <subsection name="Default value">
+
+
+                    <p>
+                        In the Tapestry 3.0 DTD, the optional default-value attribute was used to
+                        provide an OGNL expression to use for a parameter, if the parameter is not
+                        otherwise bound. In the Tapestry 4.0 DTD, the default-value attribute is a
+                        <a href="bindings.html">binding reference</a>
+                        . The following are equivalent:
+                    </p>
 
-<subsection name="Default value">
-  
-  
-<p>
-In the Tapestry 3.0 DTD, the optional default-value attribute was used to provide an OGNL expression to use for a parameter, if the
-parameter is not otherwise bound.  In the Tapestry 4.0 DTD, the default-value attribute is a <a href="bindings.html">binding reference</a>.  The following are
-equivalent:
-</p>
-
-<source xml:space="preserve">
+                    <source xml:space="preserve">
   &lt;parameter name="foo" type="int" default-value="bar.baz"/&gt;  &lt;!-- 3.0 --&gt;
   
   &lt;parameter name="foo" default-value="bar.baz"/&gt;             &lt;!-- 4.0 --&gt;
 </source>
-  
 
-<source xml:space="preserve">
+
+                    <source xml:space="preserve">
   &lt;parameter name="bar" type="java.lang.String" 
     default-value="messages.getMessage('default-bar')"/&gt;      &lt;!-- 3.0 --&gt;
   
   &lt;parameter name="bar" default-value="message:default-bar"/&gt; &lt;!-- 4.0 --&gt; 
 </source>
-  
-  
-  
-  
-</subsection>
 
-<subsection name="Inherited binding">
-  
-  
-<p>
-Tapestry 3.0 included an &lt;inherited-binding&gt; element, this was a way to directly pass the <a href="../tapestry-framework/apidocs/org/apache/tapestry/IBinding.html">IBinding</a> object for a component parameter
-to a parameter of a nested component. This is no longer supported in Tapestry 4.0; instead, the property for the component parameter should be 
-bound to the nested component parameter:
-</p>
 
-<source xml:space="preserve">
+
+
+                </subsection>
+
+                <subsection name="Inherited binding">
+
+
+                    <p>
+                        Tapestry 3.0 included an &lt;inherited-binding&gt; element, this was a way
+                        to directly pass the
+                        <a href="../tapestry-framework/apidocs/org/apache/tapestry/IBinding.html">
+                            IBinding
+                        </a>
+                        object for a component parameter to a parameter of a nested component. This
+                        is no longer supported in Tapestry 4.0; instead, the property for the
+                        component parameter should be bound to the nested component parameter:
+                    </p>
+
+                    <source xml:space="preserve">
 
   &lt;!-- 3.0 --&gt;
   
@@ -309,104 +358,143 @@
 
 </source>
 
-<p>
-<strong>Warning:</strong>
-<br/>
-  inherited-binding may make a comeback in Tapestry 4.0!
-</p>
-  
-</subsection>
-  
-</section> <!-- upgrade.parameters -->
-
-
-<section name="Specified Properties">
-  
-  
-<p>
-Property specifications in Tapestry 4.0 have been simplified.  The specification element has changed
-from &lt;property-specification&gt; to the simpler, <a href="spec.html#spec.property">&lt;property&gt;</a>.
-</p>
-
-<p>
-In Tapestry 3.0, it was necessary to specify the type of the property; this is no longer necessary or possible. The type
-attribute has been removed, and the type is determined from the Java code (and defaults to Object if 
-the Java code does not define abstract accessors).
-</p>
-  
-<p>
-In addition, any abstract properties in the Java code will be converted into transient properties, even if there is no
-matching <a href="spec.html#spec.property">&lt;property&gt;</a> element.  Typically, the <a href="spec.html#spec.property">&lt;property&gt;</a> element is only used when the property is either
-not referenced inside Java code (such as a listener method), or when when the property must be persistent.
-</p>
-
-<p>
-In the 3.0 DTDs, properties could have an initial value set. The initial-value attribute was an OGNL expression used to
-initial the property when the page is first constructed, and when the page is detached (at the end of a request cycle). The initial value
-may instead be specified as the enclosed character data of the &lt;property-specification&gt; element.
-</p>
-
-<p>
-Using the 4.0 DTDs, this is still true, but the initial-value attribute (or the enclosed character data) is a <a href="bindings.html">binding reference</a> with
-a default prefix of "ognl:".
-</p>
-  
-</section> <!-- upgrade.property -->
-
-<section name="Managed beans">
-  
-  
-<p>
-The <a href="spec.html#spec.bean">&lt;bean&gt;</a> element is used to define managed beans. In Tapestry 3.0, it could contain &lt;set-property&gt; and &lt;set-message-property&gt;
-elements to configure the properties of the bean.
-</p>
-  
-<p>
-In Tapestry 4.0, these two elements have been replaced by the <a href="spec.html#spec.set">&lt;set&gt;</a> element, which uses a <a href="bindings.html">binding reference</a> to provide the 
-value.
-</p>
-
-</section>  <!-- upgrade.bean -->
+                    <span class="warn">
+                        <strong>Warning:</strong>
+                        <p>inherited-binding may make a comeback in Tapestry 4.0!</p>
+                    </span>
+
+                </subsection>
+
+            </section><!-- upgrade.parameters -->
+
+
+            <section name="Specified Properties">
+
+
+                <p>
+                    Property specifications in Tapestry 4.0 have been simplified. The specification
+                    element has changed from &lt;property-specification&gt; to the simpler,
+                    <a href="spec.html#spec.property">&lt;property&gt;</a>
+                    .
+                </p>
+
+                <p>
+                    In Tapestry 3.0, it was necessary to specify the type of the property; this is
+                    no longer necessary or possible. The type attribute has been removed, and the
+                    type is determined from the Java code (and defaults to Object if the Java code
+                    does not define abstract accessors).
+                </p>
+
+                <p>
+                    In addition, any abstract properties in the Java code will be converted into
+                    transient properties, even if there is no matching
+                    <a href="spec.html#spec.property">&lt;property&gt;</a>
+                    element. Typically, the
+                    <a href="spec.html#spec.property">&lt;property&gt;</a>
+                    element is only used when the property is either not referenced inside Java code
+                    (such as a listener method), or when when the property must be persistent.
+                </p>
+
+                <p>
+                    In the 3.0 DTDs, properties could have an initial value set. The initial-value
+                    attribute was an OGNL expression used to initial the property when the page is
+                    first constructed, and when the page is detached (at the end of a request
+                    cycle). The initial value may instead be specified as the enclosed character
+                    data of the &lt;property-specification&gt; element.
+                </p>
+
+                <p>
+                    Using the 4.0 DTDs, this is still true, but the initial-value attribute (or the
+                    enclosed character data) is a
+                    <a href="bindings.html">binding reference</a>
+                    with a default prefix of "ognl:".
+                </p>
+
+            </section><!-- upgrade.property -->
+
+            <section name="Managed beans">
+
+
+                <p>
+                    The
+                    <a href="spec.html#spec.bean">&lt;bean&gt;</a>
+                    element is used to define managed beans. In Tapestry 3.0, it could contain
+                    &lt;set-property&gt; and &lt;set-message-property&gt; elements to configure the
+                    properties of the bean.
+                </p>
+
+                <p>
+                    In Tapestry 4.0, these two elements have been replaced by the
+                    <a href="spec.html#spec.set">&lt;set&gt;</a>
+                    element, which uses a
+                    <a href="bindings.html">binding reference</a>
+                    to provide the value.
+                </p>
+
+            </section><!-- upgrade.bean -->
+
+            <section name="Dependency Changes">
+
+
+                <p>
+                    Part of the transition to Tapestry 4.0, and targetting (in a later release) a
+                    minimum JDK of 1.5, is the
+                    <em>removal</em>
+                    of support for the Jakarta commons-lang library. commons-lang defined an Enum
+                    class that makes it impossible to compile code for JDK 1.5 ("enum" is a reserved
+                    word in JDK 1.5). With the loss of that dependency, so goes
+                    org.apache.tapestry.form.EnumPropertySelectionModel, an
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/IPropertySelectionModel.html">
+                        IPropertySelectionModel
+                    </a>
+                    implementation.
+                </p>
+
+            </section>
+
+            <section name="Other code changes">
+
+
+                <p>
+                    A number of more subtle, and more rarely used, changes exist between the 3.0 and
+                    4.0 releases.
+                </p>
+
+                <p>
+                    The contract for
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/resolver/ISpecificationResolverDelegate.html">
+                        ISpecificationResolverDelegate
+                    </a>
+                    has changed. The specifications returned by the delegate are now cached by
+                    Tapestry exactly as if they had been read from files on the classpath or web
+                    context.
+                </p>
+
+            </section>
+
+            <section name="Changes to Components">
+
+
+                <subsection name="Image and Rollover">
+
+
+                    <p>
+                        The border parameter of the
+                        <a href="site:Image">Image</a>
+                        and
+                        <a href="site:Rollover">Rollover</a>
+                        components has been removed, for XHTML compliance. You may still specify a
+                        value for border as an informal parameter ... or better yet, handle this
+                        using CSS.
+                    </p>
 
-<section name="Dependency Changes">
-  
-  
-<p>
-Part of the transition to Tapestry 4.0, and targetting (in a later release) a minimum JDK of 1.5, is the <em>removal</em> of support for the
-Jakarta commons-lang library.  commons-lang defined an Enum class that makes it impossible to compile code for JDK 1.5 ("enum" is a reserved word
-in JDK 1.5).  With the loss of that dependency, so goes org.apache.tapestry.form.EnumPropertySelectionModel, an <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/IPropertySelectionModel.html">IPropertySelectionModel</a> implementation.
-</p>
-  
-</section>
+                </subsection>
 
-<section name="Other code changes">
-  
-  
-<p>
-A number of more subtle, and more rarely used, changes exist between the 3.0 and 4.0 releases.
-</p>  
-
-<p>
-The contract for <a href="../tapestry-framework/apidocs/org/apache/tapestry/resolver/ISpecificationResolverDelegate.html">ISpecificationResolverDelegate</a> has changed.  The specifications returned by the delegate are now cached by Tapestry
-exactly as if they had been read from files on the classpath or web context.
-</p>
-  
-</section>
+            </section>
 
-<section name="Changes to Components">
-  
-  
-  <subsection name="Image and Rollover">
-    
-    
-    <p>
-      The border parameter of the <a href="site:Image">Image</a> and <a href="site:Rollover">Rollover</a> components has been removed, for XHTML compliance.
-      You may still specify a value for border as an informal parameter ... or better yet, handle this using CSS.
-    </p>
-      
-  </subsection>
-  
-</section>
+        </section>
 
-</body>
+    </body>
 </document>

Modified: tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/validation.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/validation.xml?rev=420925&r1=420924&r2=420925&view=diff
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/validation.xml (original)
+++ tapestry/tapestry4/trunk/src/site/xdoc/UsersGuide/validation.xml Tue Jul 11 09:54:16 2006
@@ -1,290 +1,414 @@
 <?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>Input Validation</title>
-</properties>
-<body>
-
-<p>
-  The tapestry validation system provides a very powerful means of validating data intuitively on most
-  of the form element components, such as <a href="site:TextField">TextField</a>, <a href="site:TextArea">TextArea</a>, <a href="site:Checkbox">Checkbox</a>, and so forth.  All of these
-  components implement the interface
-  <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/IFormComponent.html">IFormComponent</a>, and include the necessary hooks to fit into
-  the overall validation framework.
-</p>
-<p>
-  Localization, server-side, and client side validation are handled by the framework,
-  as well as the ability to extend or override most of the built in functionality to suit your purposes as
-  you see fit.
-</p>
-
-  <p>
-    Validation has evolved over time (the first attempt at proper validation using Tapestry occured back in 2001).
-    Through Tapestry 3, validation was limited to the <a href="site:ValidField">ValidField</a> component (which is now deprecated).
-    For Tapestry 4, the APIs related to validation were effectively rewritten, resulting in a more powerful, more
-    extensible approach that can be used with all kinds of form element components. 
-  </p>
-
-<section name="FieldLabel component">
-  
-  <p>
-Generally speaking, every form input component (<a href="site:TextField">TextField</a>, etc.) will be paired with a <a href="site:FieldLabel">FieldLabel</a> component.
-The FieldLabel is responsible for generating the HTML &lt;label&gt; element, which is extremely effective for
-accessible user interfaces (user interfaces that work for people with visual disabilities).  Typical usage:
-  </p>
-  
-<source xml:space="preserve">
+    <properties>
+        <title>Input Validation</title>
+    </properties>
+    <body>
+
+        <section name="Input Validation">
+
+            <p>
+                The tapestry validation system provides a very powerful means of validating data
+                intuitively on most of the form element components, such as
+                <a href="site:TextField">TextField</a>
+                ,
+                <a href="site:TextArea">TextArea</a>
+                ,
+                <a href="site:Checkbox">Checkbox</a>
+                , and so forth. All of these components implement the interface
+                <a
+                    href="../tapestry-framework/apidocs/org/apache/tapestry/form/IFormComponent.html">
+                    IFormComponent
+                </a>
+                , and include the necessary hooks to fit into the overall validation framework.
+            </p>
+            <p>
+                Localization, server-side, and client side validation are handled by the framework,
+                as well as the ability to extend or override most of the built in functionality to
+                suit your purposes as you see fit.
+            </p>
+
+            <p>
+                Validation has evolved over time (the first attempt at proper validation using
+                Tapestry occured back in 2001). Through Tapestry 3, validation was limited to the
+                <a href="site:ValidField">ValidField</a>
+                component (which is now deprecated). For Tapestry 4, the APIs related to validation
+                were effectively rewritten, resulting in a more powerful, more extensible approach
+                that can be used with all kinds of form element components.
+            </p>
+
+            <section name="FieldLabel component">
+
+                <p>
+                    Generally speaking, every form input component (
+                    <a href="site:TextField">TextField</a>
+                    , etc.) will be paired with a
+                    <a href="site:FieldLabel">FieldLabel</a>
+                    component. The FieldLabel is responsible for generating the HTML &lt;label&gt;
+                    element, which is extremely effective for accessible user interfaces (user
+                    interfaces that work for people with visual disabilities). Typical usage:
+                </p>
+
+                <source xml:space="preserve">
 &lt;tr&gt;
    &lt;td&gt;&lt;label jwcid="@FieldLabel" field="component:userName"&gt;User Name&lt;/label&gt;&lt;/td&gt;
    &lt;td&gt;&lt;input jwcid="userName@TextField" value="ognl:userName" validators="validators:required" displayName="User Name" size="30"/&gt;
 &lt;/tr&gt;
-</source>  
-  
- 
-  <p>
-    At runtime, this may render as:
-  </p> 
- 
-  <source xml:space="preserve">
+</source>
+
+
+                <p>At runtime, this may render as:</p>
+
+                <source xml:space="preserve">
 &lt;tr&gt;
    &lt;td&gt;&lt;label for="userName"&gt;User Name&lt;/label&gt;&lt;/td&gt;
    &lt;td&gt;&lt;input name="userName" id="userName" value="" size="30"/&gt;
 &lt;/tr&gt;
-</source> 
-  
-  <p>
-    However, this is not all there is to FieldLabel.  An important part of validation is <em>decoration</em> of fields, to mark
-    when they contain errors.  This is one of the responsibilities <a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">IValidationDelegate</a> ... decorating fields and labels.
-  </p>  
-  
-  <p>
-    If the above form is submitted without specifying a user name, the userName field will be in error. The page will be redisplayed
-    to show the user the error message and the decorated fields and labels.  The <em>default</em> decoration is primitive, but effective:
-  </p>
-  
-  
-  <source xml:space="preserve">
+</source>
+
+                <p>
+                    However, this is not all there is to FieldLabel. An important part of validation
+                    is
+                    <em>decoration</em>
+                    of fields, to mark when they contain errors. This is one of the responsibilities
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">
+                        IValidationDelegate
+                    </a>
+                    ... decorating fields and labels.
+                </p>
+
+                <p>
+                    If the above form is submitted without specifying a user name, the userName
+                    field will be in error. The page will be redisplayed to show the user the error
+                    message and the decorated fields and labels. The
+                    <em>default</em>
+                    decoration is primitive, but effective:
+                </p>
+
+
+                <source xml:space="preserve">
 &lt;tr&gt;
    &lt;td&gt;&lt;font color="red"&gt;&lt;label for="userName"&gt;User Name&lt;/label&gt;&lt;/font&gt;&lt;/td&gt;
    &lt;td&gt;&lt;input name="userName" id="userName" value="" size="30"/&gt;&amp;nbsp;&lt;font color="red"&gt;**&lt;/font&gt;
 &lt;/tr&gt;
-</source> 
-  
-  <p>
-   By subclassing the default implementation of <a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">IValidationDelegate</a> (the <a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/ValidationDelegate.html">ValidationDelegate</a> class), you can change how these
-   decorations are rendered. It then becomes a matter of providing this custom validation delegate to the <a href="site:Form">Form</a> component, via
-   its delegate parameter. This is covered in more detail shortly.
-  </p>
-  
-  </section> <!-- validation.fieldlabel -->
-  
-  <section name="Field validation">
-    
-    
-    <p>
-      Validation for form element components, such as <a href="site:TextField">TextField</a>, is controlled by two common component parameters
-      provided by all such components: validators and displayName.
-    </p>
-    
-    <p>
-      The validators parameter provides a list of validator objects, objects that implement the <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">Validator</a> interface.
-      Why a list?  Unlike Tapestry 3 validation, each individual validator checks just a single <em>constraint</em>.
-      Contraints are things like minimum string length, maximum string length, minimum numeric  value, etc.  This is a very fine
-      grained approach, and one that is easily extensible to new contraints.
-    </p>
-    
-    <p>
-      The displayName parameter is used to provide the label for the component (perhaps some day, this parameter will be renamed to "label"; why
-      it has such a cumbersome name has been forgotten). In any case, this label is used by the matching <a href="site:FieldLabel">FieldLabel</a> component,
-      and is also incorporated into an error messages created for the component.
-    </p>
-    
-  <subsection name="validators: binding prefix">
-    
+</source>
 
-    
-    <p>
-      The validators: binding prefix is a powerful shorthand for
-      constructing a list of configured <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">Validator</a> objects. It allows a very declarative style; for
-      example, to state that a field is required with a minimum length of four characters,
-      the following parameter binding could be used (in a page or component specification): 
-      </p>
-    <source xml:space="preserve">
+                <p>
+                    By subclassing the default implementation of
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">
+                        IValidationDelegate
+                    </a>
+                    (the
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/valid/ValidationDelegate.html">
+                        ValidationDelegate
+                    </a>
+                    class), you can change how these decorations are rendered. It then becomes a
+                    matter of providing this custom validation delegate to the
+                    <a href="site:Form">Form</a>
+                    component, via its delegate parameter. This is covered in more detail shortly.
+                </p>
+
+            </section><!-- validation.fieldlabel -->
+
+            <section name="Field validation">
+
+
+                <p>
+                    Validation for form element components, such as
+                    <a href="site:TextField">TextField</a>
+                    , is controlled by two common component parameters provided by all such
+                    components: validators and displayName.
+                </p>
+
+                <p>
+                    The validators parameter provides a list of validator objects, objects that
+                    implement the
+                    <a
+                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">
+                        Validator
+                    </a>
+                    interface. Why a list? Unlike Tapestry 3 validation, each individual validator
+                    checks just a single
+                    <em>constraint</em>
+                    . Contraints are things like minimum string length, maximum string length,
+                    minimum numeric value, etc. This is a very fine grained approach, and one that
+                    is easily extensible to new contraints.
+                </p>
+
+                <p>
+                    The displayName parameter is used to provide the label for the component
+                    (perhaps some day, this parameter will be renamed to "label"; why it has such a
+                    cumbersome name has been forgotten). In any case, this label is used by the
+                    matching
+                    <a href="site:FieldLabel">FieldLabel</a>
+                    component, and is also incorporated into an error messages created for the
+                    component.
+                </p>
+
+                <subsection name="validators: binding prefix">
+
+
+
+                    <p>
+                        The validators: binding prefix is a powerful shorthand for constructing a
+                        list of configured
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">
+                            Validator
+                        </a>
+                        objects. It allows a very declarative style; for example, to state that a
+                        field is required with a minimum length of four characters, the following
+                        parameter binding could be used (in a page or component specification):
+                    </p>
+                    <source xml:space="preserve">
 &lt;binding name="validators" value="validators:required,minLength=4"/&gt;    
     </source>
-    
-    <p>
-      Notice that the actual type of the data isn't specified in this instance, it is implied by which parameters
-      you specify. A specification is a comma-seperated list of entries. Each entry is in one of the following forms:
-    </p>
-    
-    <ul>
-      <li>
-<em>name</em>
-</li>
-      <li>
-<em>name</em>=<em>value</em>
-</li>
-      <li>
-<em>name[<em>message</em>]</em>
-</li>
-      <li>
-<em>name</em>=<em>value</em>[<em>message</em>]</li>
-      <li>$<em>name</em>
-</li>
-    </ul>
-    
-    <p>
-      Most validator classes are <em>configurable</em>: they have a property that matches their
-      name. For example, <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MinDate.html">MinDate</a> (which is named "minDate"
-      has a <code>minDate</code> property. A few validators are not configurable ("required" =&gt;
-      <a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Required.html">Required</a>, for example).
-    </p>
-    <p>
-      Validators are expected to have a public no-args constructor. They are also expected to have a
-      <code>message</code> property which is set from the value in brackets.
-      The message is either a literal string, or may be prefixed with a '%' character, to indicate
-      a localized key, resolved using the component's message catalog.
-    </p>
-    <p>
-      When the name is prefixed with a dollary sign, it indicates a reference to a <a href="spec.html#spec.bean">&lt;bean&gt;</a>
-      with the given name.
-    </p>
-    <p>
-      A full validator specification might be:
-      <code>required,email[%email-format],minLength=20[Email addresses must be at least 20 characters long.]</code>
-    </p>
-    
-    <p>
-      Here is a partial list of the validator classes provided and their configurable attributes.
-    </p>
-    <p>
-<strong>Fixme:</strong>
-<br/>
-      Fill in all of the possible attributes started in the table below.
-    </p>
-    <table>
-      <tr>
-        <th>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">Validator</a>
-</th>
-        <th>attributes</th>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/BaseValidator.html">BaseValidator</a>
-</td>
-        <td>
-<code>message</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Email.html">Email</a>
-</td>
-        <td>
-<code>none, uses standard email regexp "^\\w[-._\\w]*\\w@\\w[-._\\w]*\\w\\.\\w{2,6}$"</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Max.html">Max</a>
-</td>
-        <td>
-<code>max=&lt;maximum value, 10&gt;</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MaxDate.html">MaxDate</a>
-</td>
-        <td>
-<code>maxDate=&lt;maximum date, 06/09/2010&gt;</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MaxLength.html">MaxLength</a>
-</td>
-        <td>
-<code>maxLength=&lt;maximum length, 23&gt;</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Min.html">Min</a>
-</td>
-        <td>
-<code>min=&lt;minimum value, 0.718&gt;</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MinDate.html">MinDate</a>
-</td>
-        <td>
-<code>minDate=&lt;minimum date, 04/23/05&gt;</code>
-</td>
-      </tr>
-      <tr>
-        <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MinLength.html">MinLength</a>
-</td>
-        <td>
-<code>minLength=&lt;minmum length, 15&gt;</code>
-</td>
-      </tr>
-    </table>
-    
-    <p>
-<strong>Fixme:</strong>
-<br/>
-      Examples!
-    </p>
-    
-    <p>
-<strong>Fixme:</strong>
-<br/>
-      Write about how the validation constraints specified with the above syntax are universally
-      applied on both the client and server-side, as well as how to override the default behaviour
-      for displaying client-side validation messages via subclassing the Tapestry.default_invalid_field_handler
-      javascript prototyped method.
-    </p>
-    
-  </subsection> <!-- validation.validators -->
-  
-  </section> <!-- validation.fields -->
-    
-    
-  <section name="Extending ValidationDelegate">
-          
-   
-   <p>
-      There are a lot of scenerios where you may wish to do something more than that provided by the 
-      default, like apply a CSS class to labels in error, or even provide the ability to render the error 
-      message directly in or around the label or field.
-      </p>
-      
-      <p>
-      Below is a typical subclass of ValidationDelegate that provides more application-specific decorations:
-      </p>
-      
-      <source xml:space="preserve">
+
+                    <p>
+                        Notice that the actual type of the data isn't specified in this instance, it
+                        is implied by which parameters you specify. A specification is a
+                        comma-seperated list of entries. Each entry is in one of the following
+                        forms:
+                    </p>
+
+                    <ul>
+                        <li>
+                            <em>name</em>
+                        </li>
+                        <li>
+                            <em>name</em>
+                            =
+                            <em>value</em>
+                        </li>
+                        <li>
+                            <em>
+                                name[
+                                <em>message</em>
+                                ]
+                            </em>
+                        </li>
+                        <li>
+                            <em>name</em>
+                            =
+                            <em>value</em>
+                            [
+                            <em>message</em>
+                            ]
+                        </li>
+                        <li>
+                            $
+                            <em>name</em>
+                        </li>
+                    </ul>
+
+                    <p>
+                        Most validator classes are
+                        <em>configurable</em>
+                        : they have a property that matches their name. For example,
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MinDate.html">
+                            MinDate
+                        </a>
+                        (which is named "minDate" has a
+                        <code>minDate</code>
+                        property. A few validators are not configurable ("required" =&gt;
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Required.html">
+                            Required
+                        </a>
+                        , for example).
+                    </p>
+                    <p>
+                        Validators are expected to have a public no-args constructor. They are also
+                        expected to have a
+                        <code>message</code>
+                        property which is set from the value in brackets. The message is either a
+                        literal string, or may be prefixed with a '%' character, to indicate a
+                        localized key, resolved using the component's message catalog.
+                    </p>
+                    <p>
+                        When the name is prefixed with a dollary sign, it indicates a reference to a
+                        <a href="spec.html#spec.bean">&lt;bean&gt;</a>
+                        with the given name.
+                    </p>
+                    <p>
+                        A full validator specification might be:
+                        <code>
+                            required,email[%email-format],minLength=20[Email addresses must be at
+                            least 20 characters long.]
+                        </code>
+                    </p>
+
+                    <p>
+                        Here is a partial list of the validator classes provided and their
+                        configurable attributes.
+                    </p>
+
+                    <span class="info">
+                        <strong>Fixme:</strong>
+                        <p>Fill in all of the possible attributes started in the table below.</p>
+                    </span>
+
+                    <p>
+                        <table>
+                            <tr>
+                                <th>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Validator.html">
+                                        Validator
+                                    </a>
+                                </th>
+                                <th>attributes</th>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/BaseValidator.html">
+                                        BaseValidator
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>message</code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Email.html">
+                                        Email
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>
+                                        none, uses standard email regexp
+                                        "^\\w[-._\\w]*\\w@\\w[-._\\w]*\\w\\.\\w{2,6}$"
+                                    </code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Max.html">
+                                        Max
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>max=&lt;maximum value, 10&gt;</code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MaxDate.html">
+                                        MaxDate
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>maxDate=&lt;maximum date, 06/09/2010&gt;</code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MaxLength.html">
+                                        MaxLength
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>maxLength=&lt;maximum length, 23&gt;</code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/Min.html">
+                                        Min
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>min=&lt;minimum value, 0.718&gt;</code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MinDate.html">
+                                        MinDate
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>minDate=&lt;minimum date, 04/23/05&gt;</code>
+                                </td>
+                            </tr>
+                            <tr>
+                                <td>
+                                    <a
+                                        href="../tapestry-framework/apidocs/org/apache/tapestry/form/validator/MinLength.html">
+                                        MinLength
+                                    </a>
+                                </td>
+                                <td>
+                                    <code>minLength=&lt;minmum length, 15&gt;</code>
+                                </td>
+                            </tr>
+                        </table>
+                    </p>
+
+                    <span class="info">
+                        <strong>Fixme:</strong>
+                        <p>Examples!</p>
+                    </span>
+
+                    <span class="info">
+                        <strong>Fixme:</strong>
+                        <p>
+                            Write about how the validation constraints specified with the above
+                            syntax are universally applied on both the client and server-side, as
+                            well as how to override the default behaviour for displaying client-side
+                            validation messages via subclassing the
+                            Tapestry.default_invalid_field_handler javascript prototyped method.
+                        </p>
+                    </span>
+
+                </subsection><!-- validation.validators -->
+
+            </section><!-- validation.fields -->
+
+
+            <section name="Extending ValidationDelegate">
+
+
+                <p>
+                    There are a lot of scenerios where you may wish to do something more than that
+                    provided by the default, like apply a CSS class to labels in error, or even
+                    provide the ability to render the error message directly in or around the label
+                    or field.
+                </p>
+
+                <p>
+                    Below is a typical subclass of ValidationDelegate that provides more
+                    application-specific decorations:
+                </p>
+
+                <source xml:space="preserve">
 /**
  * Provides more intelligent validation delegate support.
  */
@@ -321,102 +445,142 @@
  }
  
  }</source>
-  </section> <!-- validation.delegate -->
-  
-  
-  <section name="ValidField component">
-    
-    <p>
-<strong>Warning:</strong>
-<br/>
-      The ValidField component and it's associated validators under org.apache.tapestry.valid should be considered
-      deprecated in favor of the new system found under org.apache.tapestry.form.validator. 
-    </p>
-    
-    <subsection name="validator: binding prefix ">
-      
-      
-      <p>
-        For <a href="site:ValidField">ValidField</a>, validation is specified through a single parameter, validator.  
-        The validator parameter is an object that implements the <a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidator.html">IValidator</a> interface. In Tapestry 3.0, it was necessary to
-        provide a configured Java object as the validator, using Java code, or
-        the specification's &lt;bean&gt; element.
-      </p>
-      
-      <p>
-        Although the ValidField component is deprecated in release 4.0 (and likely to be removed in a later release),
-        some legacy support for ValidField was added in release 4.0 ... a special binding prefix, "validator:", that streamlines
-        the process of assembling a validator object for the validator parameter. 
-      </p>
-      
-      <p>The validator: <a href="bindings.html">binding prefix</a> is a powerful shorthand for specifying validators.
-        The string provided does two things:  it identifies (by a short logical name) the Java class of the validator to create, and
-        it specifies (as a comma seperated list) the properties of the validator to set.   The form of the string is:
-      </p>
-      
-      <source xml:space="preserve">
+            </section><!-- validation.delegate -->
+
+
+            <section name="ValidField component">
+
+                <span class="warn">
+                    <strong>Warning:</strong>
+                    <p>
+                        The ValidField component and it's associated validators under
+                        org.apache.tapestry.valid should be considered deprecated in favor of the
+                        new system found under org.apache.tapestry.form.validator.
+                    </p>
+                </span>
+
+                <subsection name="validator: binding prefix ">
+
+
+                    <p>
+                        For
+                        <a href="site:ValidField">ValidField</a>
+                        , validation is specified through a single parameter, validator. The
+                        validator parameter is an object that implements the
+                        <a
+                            href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidator.html">
+                            IValidator
+                        </a>
+                        interface. In Tapestry 3.0, it was necessary to provide a configured Java
+                        object as the validator, using Java code, or the specification's
+                        &lt;bean&gt; element.
+                    </p>
+
+                    <p>
+                        Although the ValidField component is deprecated in release 4.0 (and likely
+                        to be removed in a later release), some legacy support for ValidField was
+                        added in release 4.0 ... a special binding prefix, "validator:", that
+                        streamlines the process of assembling a validator object for the validator
+                        parameter.
+                    </p>
+
+                    <p>
+                        The validator:
+                        <a href="bindings.html">binding prefix</a>
+                        is a powerful shorthand for specifying validators. The string provided does
+                        two things: it identifies (by a short logical name) the Java class of the
+                        validator to create, and it specifies (as a comma seperated list) the
+                        properties of the validator to set. The form of the string is:
+                    </p>
+
+                    <source xml:space="preserve">
         validator:<em>name</em>[,<em>property</em>[=<em>value</em>]]*
       </source>
-      
-      <p>
-        The name corresponds to contributions to the tapestry.valid.Validators configuration point.  After the name is a list of properties to set.
-        A simple conversion from string value to actual data type is performed.  For boolean properties, the value can be skipped and will default to true. 
-        Alternatively, the value can be prefixed with an exclamation point, and the property will be set to false.  Example:
-      </p>
-      
-      <source xml:space="preserve">
+
+                    <p>
+                        The name corresponds to contributions to the tapestry.valid.Validators
+                        configuration point. After the name is a list of properties to set. A simple
+                        conversion from string value to actual data type is performed. For boolean
+                        properties, the value can be skipped and will default to true.
+                        Alternatively, the value can be prefixed with an exclamation point, and the
+                        property will be set to false. Example:
+                    </p>
+
+                    <source xml:space="preserve">
         validator:string,required,minimumLength=5
-      </source> 
-      
-      <p>
-        In some cases, this is insufficiently powerful to set the properties of the validator instance, in which case the <a href="spec.html#spec.bean">&lt;bean&gt;</a> element can be used
-        instead.
-      </p> 
-      
-      <p>
-        The following validator names are defined:
-      </p>
-      
-      <table>
-        <tr>
-          <th>Name</th>
-          <th>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidator.html">IValidator</a> implementation class</th>
-        </tr>
-        <tr>
-          <td>string</td> <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/StringValidator.html">StringValidator</a>
-</td>
-        </tr>
-        <tr>
-          <td>date</td>
-          <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/DateValidator.html">DateValidator</a>
-</td>
-        </tr>
-        <tr>
-          <td>email</td>
-          <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/EmailValidator.html">EmailValidator</a>
-</td>
-        </tr>
-        <tr>
-          <td>url</td> 
-          <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/UrlValidator.html">UrlValidator</a>
-</td>
-        </tr>
-        <tr>
-          <td>int</td>
-          <td>
-<a href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IntValidator.html">IntValidator</a>
-</td>
-        </tr>
-      </table>
-      
-    </subsection> <!-- validation.validfield -->
-  </section> <!-- validation.validfield -->
-  
+      </source>
+
+                    <p>
+                        In some cases, this is insufficiently powerful to set the properties of the
+                        validator instance, in which case the
+                        <a href="spec.html#spec.bean">&lt;bean&gt;</a>
+                        element can be used instead.
+                    </p>
+
+                    <p>The following validator names are defined:</p>
+
+                    <table>
+                        <tr>
+                            <th>Name</th>
+                            <th>
+                                <a
+                                    href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidator.html">
+                                    IValidator
+                                </a>
+                                implementation class
+                            </th>
+                        </tr>
+                        <tr>
+                            <td>string</td>
+                            <td>
+                                <a
+                                    href="../tapestry-framework/apidocs/org/apache/tapestry/valid/StringValidator.html">
+                                    StringValidator
+                                </a>
+                            </td>
+                        </tr>
+                        <tr>
+                            <td>date</td>
+                            <td>
+                                <a
+                                    href="../tapestry-framework/apidocs/org/apache/tapestry/valid/DateValidator.html">
+                                    DateValidator
+                                </a>
+                            </td>
+                        </tr>
+                        <tr>
+                            <td>email</td>
+                            <td>
+                                <a
+                                    href="../tapestry-framework/apidocs/org/apache/tapestry/valid/EmailValidator.html">
+                                    EmailValidator
+                                </a>
+                            </td>
+                        </tr>
+                        <tr>
+                            <td>url</td>
+                            <td>
+                                <a
+                                    href="../tapestry-framework/apidocs/org/apache/tapestry/valid/UrlValidator.html">
+                                    UrlValidator
+                                </a>
+                            </td>
+                        </tr>
+                        <tr>
+                            <td>int</td>
+                            <td>
+                                <a
+                                    href="../tapestry-framework/apidocs/org/apache/tapestry/valid/IntValidator.html">
+                                    IntValidator
+                                </a>
+                            </td>
+                        </tr>
+                    </table>
+
+                </subsection><!-- validation.validfield -->
+            </section><!-- validation.validfield -->
+
+        </section>
 
-</body>
+    </body>
 </document>



Mime
View raw message