You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by jk...@apache.org on 2006/07/15 18:57:31 UTC
svn commit: r422268 [2/5] - in /tapestry/tapestry4/trunk: src/documentation/
src/images/ src/site/ src/site/xdoc/components/ support/
tapestry-framework/src/documentation/content/xdocs/
tapestry-framework/src/documentation/content/xdocs/tapestry/Compon...
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/FieldLabel.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/FieldLabel.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/FieldLabel.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/FieldLabel.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,187 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>FieldLabel</title>
+ </properties>
+ <body>
+
+ <section name="FieldLabel">
+
+ <p>
+ A FieldLabel works with form element components (such as
+ <a href="TextField.html">TextField</a>
+ ,
+ <a href="TextArea.html">TextArea</a>
+ ,
+ <a href="Checkbox.html">Checkbox</a>
+ , etc.), labeling the field with the
+ <code>displayName</code>
+ property of the field. The FieldLabel may also be
+ <em>decorated</em>
+ by the validation delegate (to highlight when the corresponding field is in error).
+ </p>
+
+ <p>
+ The body of the component is discarded, but often has a provisional label (for
+ WYSIWYG). The actual value is typically provided by the field (so that it may be
+ localized just once).
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/valid/FieldLabel.html">
+ org.apache.tapestry.valid.FieldLabel
+ </a>
+ ,
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">
+ IValidationDelegate
+ </a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>field</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/form/IFormComponent.html">
+ IFormComponent
+ </a>
+ </td>
+ <td>in</td>
+ <td>yes</td>
+ <td></td>
+ <td>
+ The component to be labeled. The component will be
+ <em>pre-rendered</em>
+ by the FieldLabel, and its displayName property used as the label string
+ (note that most form element components return null for displayName).
+ </td>
+ </tr>
+
+ <tr>
+ <td>displayName</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ Overrides the displayName provided by the component or supplies a
+ displayName for components (such as
+ <a href="TextField.html">TextField</a>
+ , etc.) that don't provide one. A runtime exception occurs if
+ displayName is null and not supplied by the component.
+ </td>
+ </tr>
+
+ <tr>
+ <td>raw</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+ <td>
+ If true, then the displayName is printed "raw" (without filtering),
+ which is appropriate when the displayName includes markup text.
+ </td>
+ </tr>
+
+ <tr>
+ <td>prerender</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>true</td>
+ <td>
+ If true (the default), then the field for this label is pre-renderered.
+ This is necessary so that the field can render itself, and set its
+ client id (which is needed for the FieldLabel to render). When the
+ FieldLabel is positioned
+ <em>after</em>
+ the field, prerender should be set to false.
+ </td>
+ </tr>
+
+ </table>
+
+ <p>
+ Body:
+ <strong>removed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>for</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+
+ <p>
+ FieldLabel components are simple, and generally expressed entirely in the HTML
+ template. Here we see a
+ <a href="TextField.html">TextField</a>
+ being labeled (and the displayName being provided as a FieldLabel parameter).
+ </p>
+
+ <source xml:space="preserve">
+<tr>
+ <th>
+ <span jwcid="@FieldLabel" field="component:textField" displayName="message:textfield-label">Text Field</span>:
+ </th>
+ <td>
+ <input jwcid="textField@TextField" . . . />
+ </td>
+</tr>
+<tr>
+ <th>
+ <span jwcid="@FieldLabel" field="component:validField">Valid Field</span>:
+ </th>
+ <td>
+ <input jwcid="validField@ValidField" displayName="message:validfield-label" . . . />
+ </td>
+</tr>
+</source>
+
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/FieldLabel.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/For.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/For.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/For.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/For.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,386 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>For</title>
+ </properties>
+ <body>
+
+ <section name="For">
+
+ <p>
+ Loops over a collection of source values. May also emulate an element (like an Any
+ component). If this component is placed in a Form, it will automatically store the
+ collection in Hidden fields so that the structure of the page is preserved when the
+ form is submitted even if the values in the source parameter have changed.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/components/ForBean.html">
+ org.apache.tapestry.components.ForBean
+ </a>
+ ,
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/utils/DefaultPrimaryKeyConverter.html">
+ org.apache.tapestry.utils.DefaultPrimaryKeyConverter
+ </a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>source</td>
+ <td>Iterator, Collection, Object[], or Object</td>
+ <td>in</td>
+ <td>yes</td>
+ <td></td>
+
+ <td>
+ The source of objects to be iterated, which may be a Collection, an
+ Iterator, an array of Objects, or a even a single Object (which is
+ treated as a singleton collection).
+ <p />
+ The source parameter may even be null, in which case the For's body is
+ never renderred.
+ </td>
+ </tr>
+
+ <tr>
+ <td>value</td>
+ <td>Object</td>
+ <td>out</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ If provided, the parameter is updated with the current value on each
+ iteration.
+ </td>
+ </tr>
+
+ <tr>
+ <td>index</td>
+ <td>int</td>
+ <td>out</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ If provided, the parameter is updated with the index of the loop on each
+ iteration.
+ </td>
+ </tr>
+
+ <tr>
+ <td>element</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ If provided, the component wraps its content with the requested element.
+ Informal parameters become attributes of that element.
+ </td>
+ </tr>
+
+ <tr>
+ <td>keyExpression</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ Only active in a form. An OGNL expression that returns the primary key
+ of the iterated value. The primary keys are stored in hidden fields
+ during rendering and are loaded from the form during a rewind to ensure
+ that the iterations remain the same.
+ <p />
+ This is a simpler, but a less efficient alternative of the 'converter'
+ parameter. If needed, please use in conjuction with 'fullSource' to
+ reference objects not currently present in 'source'. Use the
+ 'defaultValue' parameter to define the object to be returned if a value
+ corresponding to a particular primary key cannot be found.
+ </td>
+ </tr>
+
+ <tr>
+ <td>fullSource</td>
+ <td>Iterator, Collection, Object[], or Object</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ Only active in a form. If an object with a representation stored in the
+ form cannot be found in the 'source' parameter, then the objects
+ provided by this parameter are searched for a match next.
+ </td>
+ </tr>
+
+ <tr>
+ <td>defaultValue</td>
+ <td>Object</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ Only active in a form. The value to be used when no match for a given
+ representation stored in the hidden fields cannot be found.
+ </td>
+ </tr>
+
+ <tr>
+ <td>converter</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/components/IPrimaryKeyConverter.html">
+ IPrimaryKeyConverter
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ Only active in a form. Defines how the items iterated upon will be
+ stored in the form as hidden values and how the stored information will
+ be converted back to objects.
+ <p />
+ This interface allows only the primary key of the items to be stored,
+ rather than the whole item.
+ </td>
+ </tr>
+
+ <tr>
+ <td>primaryKeys</td>
+ <td>List</td>
+ <td>out</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ Only active in a form. If provided, the parameter is automatically
+ updated during a rewind with the list of primary keys stored in the
+ form. The parameter is updated right before the iterations begin in a
+ rewind and could be used to preload the relevant objects in the provided
+ 'converter'.
+ </td>
+ </tr>
+
+ <tr>
+ <td>match</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>true</td>
+
+ <td>
+ Only active in a form. This parameter allows the matching of the string
+ representation of the values stored in the hidden fields with that of
+ the values in 'source'. It guarantees that the values iterated upon are
+ physically identical to the ones provided.
+ <p />
+ The method is sometimes slower than simple unsqueezing, but it
+ eliminates a number of potential pitfalls. Please disable with caution.
+ </td>
+ </tr>
+
+ <tr>
+ <td>volatile</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+
+ <td>
+ Only active in a form. Determines whether to avoid creating hidden
+ fields within a form. Using this parameter may make the form structure
+ different during render and rewind, and cause exceptions as a result.
+ Please use with caution.
+ </td>
+ </tr>
+
+ </table>
+
+ <p>
+ Body:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>none</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+
+ <p>
+ <strong>View list of customers</strong>
+ </p>
+ <p>This example displays a list of customers:</p>
+
+ <source xml:space="preserve">
+<table cellspacing="10">
+ <tr>
+ <td>ID</td>
+ <td>Name</td>
+ <td>Level</td>
+ </tr>
+ <tr>
+ <td colspan="3"><hr></td>
+ </tr>
+ <tr jwcid="@For" source="ognl:customerList" value="ognl:customer" element="tr">
+ <td><span jwcid="@Insert" value="ognl:customer.id"/></td>
+ <td><span jwcid="@Insert" value="ognl:customer.fullName"/></td>
+ <td><span jwcid="@Insert" value="ognl:customer.memberLevel"/></td>
+ </tr>
+</table>
+</source>
+
+ <p>
+ <br />
+ <strong>Edit a list of customers</strong>
+ </p>
+ <p>
+ This examples allows the user to edit a list of customers. The 'keyExpression'
+ parameter is optional. It tells the component to use the 'id' expression to
+ obtain the primary key of the customers. The parameter is particularly useful
+ when the Customer object is not Serializable, as only the primary key is stored
+ in the hidden fields, rather than the full Customer record.
+ </p>
+
+ <source xml:space="preserve">
+<table cellspacing="10">
+ <tr>
+ <td>ID</td>
+ <td>Name</td>
+ <td>Level</td>
+ </tr>
+ <tr>
+ <td colspan="3"><hr></td>
+ </tr>
+ <tr jwcid="@For" source="ognl:customerList" keyExpression="id"
+ value="ognl:customer" element="tr">
+ <td><span jwcid="@Insert" value="ognl:customer.id"/></td>
+ <td><span jwcid="@TextField" value="ognl:customer.fullName"/></td>
+ <td><span jwcid="@PropertySelection" value="ognl:customer.memberLevel"
+ model="ognl:@com.mycorp.Customer@MEMBER_LEVEL_MODEL"/></td>
+ </tr>
+</table>
+</source>
+
+ </section>
+
+ <section name="Hints">
+
+
+ <p>
+ <strong>Representing data as a string</strong>
+ </p>
+ <p>
+ If the
+ <a href="site:For">For</a>
+ component is used in a form, it will automatically convert the provided data to
+ strings and store it in hidden fields in order to ensure that the form is
+ processed correctly when submitted.
+ </p>
+ <p>
+ If the data is in one of the basic types or if the data is serializable,
+ Tapestry will automatically build string representation of the objects. If it is
+ not serializable however, an
+ <code>ApplicationRuntimeException</code>
+ will be thrown with the message 'Could not find a strategy instance for class'.
+ </p>
+ <p>There are several options to resolve this problem:</p>
+ <ol>
+ <li>
+ <p>
+ <strong>Store only the primary keys of your data objects</strong>
+ <br />
+ You can define the name of a property that contains the primary keys
+ using the
+ <code>keyExpression</code>
+ parameter.
+ <br />
+ The second example shows that approach and uses the
+ <code>id</code>
+ property to represent the object.
+ <br />
+ Alternatively, you can implement the
+ <code>IPrimaryKeyConverter</code>
+ interface and use the
+ <code>converter</code>
+ parameter to define how the primary key is obtained from the object.
+ </p>
+ </li>
+ <li>
+ <strong>Make your data class Serializable.</strong>
+ <br />
+ Tapestry will automatically convert Serializable data into a string and
+ store it in the form.
+ </li>
+ <li>
+ Define your own way to convert the class into a string. To do this,
+ implement the
+ <code>SqueezeAdaptor</code>
+ interface and register your squeeze adaptor in the WEB-INF/hivemodule.xml
+ file. Please refer to the documentation for more information.
+ </li>
+ <li>
+ Make the For component volatile by setting the
+ <code>volatile</code>
+ parameter to 'true'. This approach is discouraged, since the data will not
+ be stored in the form as a result. That may cause a
+ <code>StaleLinkException</code>
+ to be thrown if the data changes between the form rendering and the form
+ submission. To avoid this problem you must make sure that the data stays the
+ same.
+ </li>
+ </ol>
+ <p>Either of the above options will work, but the first two are preferred.</p>
+
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/For.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/Form.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/Form.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/Form.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/Form.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,261 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>Form</title>
+ </properties>
+ <body>
+
+
+ <section name="Form">
+
+ <p>
+ A Form component must enclose the other form element components (such as
+ <a href="TextField.html">TextField</a>
+ and
+ <a href="Checkbox.html">Checkbox</a>
+ ). It manages the rendering of the form as well as processing when the form is
+ submitted (known as "rewinding" the form). In traditional web applications, the
+ developer is responsible for providing a name for each form and each form control
+ element; in Tapestry, the Form component generates its own unique name, and unique
+ names for each enclosed component ... this is necessary to support advanced features
+ such as loops within forms.
+ </p>
+ <p>
+ <strong>
+ See also:
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/form/Form.html">
+ org.apache.tapestry.form.Form
+ </a>
+ ,
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">
+ IValidationDelegate
+ </a>
+ </strong>
+ </p>
+ <section name="Parameters">
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>method</td>
+ <td>string</td>
+ <td>in</td>
+ <td>no</td>
+ <td>post</td>
+ <td>Method used by the form when it is submitted.</td>
+ </tr>
+ <tr>
+ <td>success</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ Listener invoked when the form is submitted normally (not a cancel or a
+ refresh) and the validation delegate indicates no errors. If the
+ delegate indicates errors, then the listener parameter (if non-null) is
+ used instead.
+ </td>
+ </tr>
+ <tr>
+ <td>cancel</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ Listener used when a form is cancelled, overriding the default listener.
+ Forms are cancelled by invoking the client-side JavaScript function
+ document.
+ <em>form-name</em>
+ .events.cancel(). A cancelled form
+ <em>does not</em>
+ rewind. If no cancel listener is provided, then the normal listener will
+ be used.
+ </td>
+ </tr>
+ <tr>
+ <td>refresh</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ Listener used when a form is refreshed, overriding the default listener.
+ A refreshed form bypasses input field validation on the client side,
+ though validation still occurs on the server side. If no refresh
+ listener is provided, then the normal listener will be used.
+ </td>
+ </tr>
+ <tr>
+ <td>listener</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ Default listener to be invoked when the form is submitted. Invoked only
+ if another listener (success, cancel or refresh) is not invoked.
+ </td>
+ </tr>
+ <tr>
+ <td>stateful</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>true</td>
+ <td>
+ If true (the default), then an active session is required when the form
+ is submitted, if there was an active session when the form was rendered.
+ </td>
+ </tr>
+ <tr>
+ <td>direct</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>true</td>
+ <td>
+ If true (the default), then the more efficient direct service is used.
+ If false, then the action service is used. The action service requires
+ rewinding of the entire page, and is rarely (if ever) used.
+ </td>
+ </tr>
+ <tr>
+ <td>delegate</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/valid/IValidationDelegate.html">
+ IValidationDelegate
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td>default instance</td>
+ <td>
+ An object that tracks user input and input field errors, and decorates
+ fields and field labels. This is typically overriden to provide an
+ application-specific look and feel.
+ </td>
+ </tr>
+ <tr>
+ <td>clientValidationEnabled</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+ <td>
+ If true, then client-side validation will be enabled for components that
+ support it (such as
+ <a href="TextField.html">TextField</a>
+ ).
+ </td>
+ </tr>
+ <tr>
+ <td>focus</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>true</td>
+ <td>
+ If true (the default), the the Form will determine a field to receive
+ input focus, and add JavaScript to move the cursor to that field.
+ Priority is given to fields in error, then required fields, then any
+ non-disabled field. On a page with multiple forms, use this parameter to
+ control which form will take focus.
+ </td>
+ </tr>
+ <tr>
+ <td>scheme</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ The required scheme ("http" or "https", typically) for the URL. This
+ will force the creation of an absolute URL when the current request's
+ scheme does not match the value for this parameter. This is most often
+ used to switch to "https" for secure portions of an application (such as
+ a login page), before switching back to standard "http" for the majority
+ of an application.
+ </td>
+ </tr>
+ <tr>
+ <td>port</td>
+ <td>Integer</td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ The required port (80, 443, 8080. 8443, typically) for the URL. This
+ will force the creation of an absolute URL when the current request's
+ scheme does not match the value for this parameter. This is most often
+ used in conjunction with scheme to switch to "https:443"/"https:8443"
+ for secure portions of an application (such as a login page), before
+ switching back to standard "http:80"/"http:80" for the majority of an
+ application.
+ </td>
+ </tr>
+ </table>
+ <p>
+ Body:
+ <strong>allowed</strong>
+ </p>
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+ <p>Reserved parameters: action, enctype, id, name, onreset, onsubmit</p>
+ <p>
+ A note about clientValidationEnabled: This refers to the revamped input
+ validation support that debuts in Tapestry 4.0.
+ </p>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/Form.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/Frame.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/Frame.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/Frame.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/Frame.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,87 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>Frame</title>
+ </properties>
+ <body>
+
+ <section name="Frame">
+
+ <p>
+ Provides the HTML <frame> element within a <frameset>, inserting the
+ specified Tapestry page as the content of the frame.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="RenderBlock.html">RenderBlock</a>
+ ,
+ <a href="RenderBody.html">RenderBody</a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>page</td>
+ <td>String</td>
+ <td>in</td>
+ <td>yes</td>
+ <td />
+ <td>The name of the page to display in the frame.</td>
+ </tr>
+
+ </table>
+
+ <p>
+ Body:
+ <strong>removed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>src</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+ <p>This example is under construction.</p>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/Frame.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/GenericLink.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/GenericLink.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/GenericLink.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/GenericLink.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,155 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>GenericLink</title>
+ </properties>
+ <body>
+
+ <section name="GenericLink">
+
+ <p>Creates an <a> hyperlink for an arbitrary URL.</p>
+ <p>
+ Although a GenericLink can be accomplished using an
+ <a href="Any.html">Any</a>
+ component, a GenericLink is more flexible: it can be disabled, like a
+ <a href="DirectLink.html">DirectLink</a>
+ and can also wrap around
+ <a href="Rollover.html">Rollover</a>
+ components. GenericLinks are often used with javascript: URLs to perform client-side
+ scripting.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="DirectLink.html">DirectLink</a>
+ ,
+ <a href="ExternalLink.html">ExternalLink</a>
+ ,
+ <a href="PageLink.html">PageLink</a>
+ ,
+ <a href="Rollover.html">Rollover</a>
+ ,
+ <a href="ServiceLink.html">ServiceLink</a>
+ </strong>
+
+ </p>
+
+ <section name="Parameters">
+
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>href</td>
+ <td>String</td>
+
+ <td>in</td>
+
+ <td>yes</td>
+ <td />
+ <td>
+ The URL to trigger when the link is clicked. This is often of the form:
+ <a> href="javascript:functionName('param')">
+ </td>
+ </tr>
+ <tr>
+
+ <td>disabled</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+
+ <td>
+
+ Controls whether the link is produced. If disabled, the portion of the
+ template the link surrounds is still rendered, but not the link itself.
+ </td>
+ </tr>
+ <tr>
+ <td>anchor</td>
+
+ <td>String</td>
+ <td>in</td>
+
+ <td>no</td>
+ <td />
+ <td>
+ The name of an anchor or element to link to. The final URL will have '#'
+ and the anchor appended to it.
+ </td>
+
+ </tr>
+ <tr>
+ <td>renderer</td>
+
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/link/ILinkRenderer.html">
+ ILinkRenderer
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td />
+
+ <td>The object which will actually render the link.</td>
+ </tr>
+
+ </table>
+
+ <p>
+ Body:
+ <strong>rendered</strong>
+ </p>
+
+ <p>
+
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>none</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+ <p>
+ Under Construction.
+
+ </p>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/GenericLink.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/Hidden.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/Hidden.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/Hidden.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/Hidden.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,164 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>Hidden</title>
+ </properties>
+ <body>
+
+ <section name="Hidden">
+
+ <p>
+ Adds a hidden HTML <input type="hidden"> field to a
+ <a href="Form.html">Form</a>
+ . This is often used to synchronize data when the form is submitted with values
+ known when the page was rendered.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="Form.html">Form</a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td>Object</td>
+
+ <td>in/out</td>
+ <td>yes</td>
+ <td />
+ <td>
+ The value to be stored in the the hidden field. The parameter is read
+ when the HTML response is generated, and then written when the form is
+ submitted. A
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/util/io/DataSqueezer.html">
+ DataSqueezer
+ </a>
+ is used to convert the value between an arbitrary type and a String.
+ </td>
+ </tr>
+
+ <tr>
+ <td>id</td>
+ <td>Object</td>
+ <td>in</td>
+ <td>no</td>
+ <td>undefined in HTML presentation.</td>
+ <td>
+ ID parameter of HTML hidden object. The parameter is read when the HTML
+ response is generated and if there is a specific value the component
+ generate parameter id with passed value in its HTML presentation.
+ </td>
+ </tr>
+ <tr>
+ <td>listener</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+
+ <td>in</td>
+ <td>no</td>
+ <td />
+ <td>
+ <p>
+ A listener that is informed after the value parameter is updated.
+ This allows the data set operated on by the rest of the
+ <a href="Form.html">Form</a>
+ components to be synchronized to the value stored in the hidden
+ field.
+ </p>
+ <p>
+ A typical use is to encode the primary key of an entity as a Hidden;
+ when the form is submitted, the Hidden's listener re-reads the
+ corresponding entity from the database.
+ </p>
+ </td>
+ </tr>
+ <tr>
+ <td>encode</td>
+
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>true</td>
+ <td>
+ <p>
+ If true (the default) a
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/util/io/DataSqueezer.html">
+ DataSqueezer
+ </a>
+ is used to transform the value Object into the HTML value string,
+ and (on submit) to convert the string back into an Object.
+ </p>
+ <p>
+ If false, then the value must be a String. This is most likely used
+ when the hidden field is used to communicate with client-side logic
+ in JavaScript (which is not able to interpret even Strings encoded
+ by
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/util/io/DataSqueezer.html">
+ DataSqueezer
+ </a>
+ ). If you find yourself getting strange errors during the form
+ rewind it could easily be Tapestry trying to interpret a value
+ you've set via JavaScript.
+ </p>
+ </td>
+
+ </tr>
+ </table>
+
+ <p>
+ Body:
+ <strong>removed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>forbidden</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>name</em>
+ </p>
+
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/Hidden.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/If.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/If.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/If.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/If.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,168 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>If</title>
+ </properties>
+ <body>
+
+ <section name="If">
+
+ <p>
+ Conditionally emulates an element and its attributes and/or includes a block of
+ content if a condition is met.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/components/IfBean.html">
+ org.apache.tapestry.components.IfBean
+ </a>
+ ,
+ <a href="Else.html">Else</a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>condition</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>yes</td>
+ <td></td>
+
+ <td>The condition to evaluate.</td>
+ </tr>
+ <tr>
+ <td>conditionValue</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ The value of the condition. During render this is obtained from the
+ condition parameter. During rewind it is the submitted condition.
+ </td>
+ </tr>
+ <tr>
+ <td>listener</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ The listener is called before the component renders itself, regardless
+ of the value of the condition parameter.
+ </td>
+ </tr>
+ <tr>
+ <td>element</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+
+ <td>
+ The element to emulate. If specified, then the component acts like an
+ <a href="Any.html">Any</a>
+ , emitting an open and close tag. Informal parameters are applied to the
+ tag. If no element is specified, informal parameters are ignored.
+ </td>
+ </tr>
+ <tr>
+ <td>volatile</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+
+ <td>
+ Only active in a form. Determines whether to avoid creating hidden
+ fields within a form. Using this parameter may make the form structure
+ different during render and rewind, and cause exceptions as a result.
+ Please use with caution.
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ Body:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>name</em>
+ ,
+ <em>form</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+
+ <p>
+ In this example we say hello to our user if he/she has login, or we ask him/her
+ login.
+ </p>
+ <p>Home.html</p>
+
+ <source xml:space="preserve">
+...
+<p>
+Hello, <span jwcid="@If" condition="ognl:user.login"><span jwcid="@Insert" value="ognl:user.name"/></span>
+<span jwcid="@Else">please <span jwcid="@PageLink" page="Login">login</span></span>
+</p>
+...
+
+</source>
+
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/If.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/Image.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/Image.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/Image.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/Image.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,189 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>Image</title>
+ </properties>
+ <body>
+
+ <section name="Image">
+
+ <p>
+ Displays an image, deriving the source URL for the image from an asset.
+ <br />
+ <a href="Rollover.html">Rollover</a>
+ is a similar component that can create dynamic mouse-over effects as well.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="ImageSubmit.html">ImageSubmit</a>
+ ,
+ <a href="Rollover.html">Rollover</a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>image</td>
+ <td>
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/IAsset.html">
+ IAsset
+ </a>
+ </td>
+
+ <td>in</td>
+ <td>yes</td>
+ <td />
+ <td>The image to show.</td>
+ </tr>
+ </table>
+
+ <p>
+ Body:
+ <strong>removed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>src</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+ <p>
+ Inserts the static context path based image.
+ <br />
+ This example uses a <context-asset> to reference the image.
+ </p>
+ <img src="../../images/tapestry/ComponentReference/PoweredByTapestry.png"
+ alt="PoweredByTapestry Screen Shot" />
+ <p>HTML Template</p>
+ <source xml:space="preserve">
+<table cellpadding="8" valign="middle">
+<tr>
+ <td>
+ <a href="http://jakarta.apache.org/tapestry/">
+ <img jwcid="@Image" image="asset:imageAsset" alt="View Tapestry Home"/>
+ </a>
+ </td>
+ <td>
+ <font color="navy" size="+2"><b><i>Powered by Tapestry</i></b></font>
+ </td>
+</tr>
+</table>
+</source>
+
+ <p>Page Specification</p>
+ <source xml:space="preserve">
+<asset name="imageAsset" path="/images/poweredby.png"/>
+</source>
+
+ <p>
+ <br />
+ Inserts the dynamic image obtained from the page's NewsItem property.
+ <br />
+ This example uses the
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/asset/ExternalAsset.html">
+ ExternalAsset
+ </a>
+ to reference the image's URL.
+ </p>
+ <img src="../../images/tapestry/ComponentReference/Image.png"
+ alt="Image Screen Shot" />
+ <p>HTML Template</p>
+ <source xml:space="preserve">
+<table cellpadding="8">
+<tr>
+ <td>
+ <h4><span jwcid="@Insert" value="ognl:newsItem.title"/></h4>
+ <span jwcid="@Insert" value="ognl:newsItem.body"/>
+ <p>
+ Date : <span jwcid="@Insert" value="ognl:newsItem.date" format="ognl:@NewsItemPage@DATE_FORMAT"/>
+ </td>
+ <td>
+ <img jwcid="@Image" image="ognl:newsItem.imageAsset" alt="ognl:newsItem.summary"/>
+ </td>
+</tr>
+</table>
+</source>
+
+ <p>Page Specification</p>
+ <source xml:space="preserve">
+<property name="orderItem" type="com.dsconsulting.cms.model.NewsItem"/>
+</source>
+
+ <p>Java classes</p>
+ <source xml:space="preserve">
+public abstract class NewsItemPage extends BasePage {
+ public static final SimpleDateFormat DATE_FORMAT = new SimpleDateFormat("dd MMM yyyy");
+
+ public abstract NewsItem getNewsItem();
+}
+
+public class NewsItem implements Serializable {
+ private String title;
+ private String body;
+ private String summary;
+ private Date date;
+ private String imageURL;
+
+ public NewsItem(String title, String summary, String body, Date date,
+ String imageURL) {
+ this.title = title;
+ this.body = body;
+ this.summary = summary;
+ this.date = date;
+ this.imageURL = imageURL;
+ }
+
+ public String getTitle() { return title; }
+
+ public String getBody() { return body; }
+
+ public String getSummary() { return summary; }
+
+ public String getDate() { return date; }
+
+ public IAsset getImageAsset() { return new ExternalAsset(imageURL, null); }
+}
+</source>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/Image.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/ImageSubmit.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/ImageSubmit.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/ImageSubmit.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/ImageSubmit.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,289 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>ImageSubmit</title>
+ </properties>
+ <body>
+
+ <section name="ImageSubmit">
+
+ <p>
+ A component that generates a clickable image that will cause the enclosing form to
+ submit. The <input type="image"> form element was originally designed for use
+ as a way to select a pixel within an image that was presumable a map; it has been
+ co-opted by web applications as a way to decorate a form submit button using a
+ custom image instead of ordinary clickable buttons. This component is simply an
+ enhanced version of the
+ <a href="Submit.html">Submit</a>
+ component that will display an image instead of a text label.
+ </p>
+
+ <p>
+ <strong>
+ See also:
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/form/ImageSubmit.html">
+ org.apache.tapestry.form.ImageSubmit
+ </a>
+ ,
+ <a href="Form.html">Form</a>
+ ,
+ <a href="LinkSubmit.html">LinkSubmit</a>
+ ,
+ <a href="Submit.html">Submit</a>
+ </strong>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>image</td>
+ <td>
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/IAsset.html">
+ IAsset
+ </a>
+ </td>
+ <td>in</td>
+ <td>yes</td>
+ <td></td>
+ <td>The normal image to display for the button.</td>
+ </tr>
+
+ <tr>
+ <td>name</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ Overrides the default mechanism for selecting the form element id; this
+ allows the name attribute of the rendered <input> tag to be
+ controlled, which is necessary is some browsers to control the tooltip
+ help message for the control.
+ </td>
+ </tr>
+
+ <tr>
+ <td>disabled</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+ <td>
+ If set to true, the button will be disabled (will not respond to the
+ mouse); the browser should provide a "greyed out" appearance.
+ </td>
+ </tr>
+
+ <tr>
+ <td>disabledImage</td>
+ <td>
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/IAsset.html">
+ IAsset
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ If specified, and if the component is disabled, then this image is used
+ rather than the normal image parameter. This allows an alternate image
+ to be used to indicate to the user that the option is not available.
+ </td>
+ </tr>
+
+ <tr>
+ <td>point</td>
+ <td>java.awt.Point</td>
+ <td>out</td>
+ <td>no</td>
+ <td></td>
+ <td>Set to the coordinates of the clicked point within the image.</td>
+ </tr>
+
+ <tr>
+ <td>selected</td>
+ <td>Object</td>
+ <td>out</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ This parameter is bound to a property that is updated when the submit
+ button is clicked by the user. The property is updated to match the tag
+ parameter.
+ </td>
+ </tr>
+ <tr>
+ <td>tag</td>
+ <td>Object</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ Tag used with the selected parameter to indicate which Submit button on
+ a form was clicked.
+ </td>
+ </tr>
+
+ <tr>
+ <td>listener</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ An optional listener (typically specified as the name of a listener
+ method), notified when the Submit is triggered.
+ </td>
+ </tr>
+ <tr>
+ <td>action</td>
+ <td>
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IActionListener.html">
+ IActionListener
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ A listener that is notified if this component is triggered just before
+ the form's listener, after all components enclosed by the Form have had
+ a chance to update their properties.
+ </td>
+ </tr>
+ <tr>
+ <td>parameters</td>
+ <td>Object</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ Parameter(s) gathered at the time the button is triggered, supplied as
+ listener parameters in the IRequestCycle available to the listener.
+ <p>
+ If the parameter is a Collection, it will be converted to an Object
+ array (to match the IRequestCycle getListenerParameters()
+ signature).
+ </p>
+ <p>
+ Allows deferred listeners (defer = true) access to any rewind state
+ not conveniently placed using tag/selected (e.g. when there are
+ multiple objects to select as might happen with a nested Foreach).
+ </p>
+ </td>
+ </tr>
+
+ </table>
+
+ <p>
+ Body:
+ <strong>removed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>type, src, border</em>
+ </p>
+
+ <p>
+ <strong>Warning:</strong>
+ <br />
+ In Tapestry 3.0, the behavior of the ImageSubmit was
+ <em>undeferred</em>
+ , the equivalent of setting the defer parameter to false. The default for the
+ defer parameter in 4.0 is
+ <strong>true</strong>
+ , which may in rare cases, cause problems when upgrading an applicaton from 3.0
+ to 4.0.
+ </p>
+
+
+ </section>
+
+ <section name="Examples">
+
+
+ <p>HTML template:</p>
+
+ <source xml:space="preserve">
+<form jwcid="form@Form" success="listener:doSubmit">
+<table>
+ <tr>
+ <th>User name:</th>
+ <td><input jwcid="userName@TextField" value="ognl:userName" size="12"/></td>
+ </tr>
+ <tr>
+ <th>Password:</th>
+ <td><input jwcid="password@TextField" value="ognl:password" hidden="true" size="12"/></td>
+ </tr>
+ <tr>
+ <td colspan="2">
+ <input type="image" src="images/login.png"/>
+ <input type="image" jwcid="help@ImageSubmit" action="listener:doHelp" image="asset:help/>
+ </td>
+ </tr>
+</table>
+</form></source>
+
+ <p>Page specification:</p>
+
+ <source xml:space="preserve">
+
+. . .
+
+ <asset name="help" path="images/help.png"/>
+
+. . .
+
+</source>
+
+
+ <p>
+ This is a variation of the example for the
+ <a href="site:Submit">Submit</a>
+ component; it uses images instead of ordinary clickable buttons for the help and
+ login actions.
+ </p>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/ImageSubmit.xml
------------------------------------------------------------------------------
svn:eol-style = native
Added: tapestry/tapestry4/trunk/src/site/xdoc/components/Insert.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry4/trunk/src/site/xdoc/components/Insert.xml?rev=422268&view=auto
==============================================================================
--- tapestry/tapestry4/trunk/src/site/xdoc/components/Insert.xml (added)
+++ tapestry/tapestry4/trunk/src/site/xdoc/components/Insert.xml Sat Jul 15 09:57:28 2006
@@ -0,0 +1,200 @@
+<?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.
+-->
+<document>
+ <properties>
+ <title>Insert</title>
+ </properties>
+ <body>
+
+ <section name="Insert">
+
+ <p>
+ Allows for the insertion of text (with a specified format) into the HTML response.
+ The text itself can be filtered or not. When filtering is enabled (the default),
+ certain characters (such as < and >) are escaped into HTML safe
+ representations (such as &lt; and &gt;).
+ </p>
+
+ <p>
+ <strong>See also:</strong>
+ <a href="../../tapestry-framework/apidocs/org/apache/tapestry/components/Insert.html">
+ org.apache.tapestry.components.Insert
+ </a>
+ <a href="RenderBlock.html">RenderBlock</a>
+ ,
+ <a href="InsertText.html">InsertText</a>
+ ,
+ <a href="RenderBody.html">RenderBody</a>
+ </p>
+
+ <section name="Parameters">
+
+
+ <table>
+ <tr>
+ <th>Name</th>
+ <th>Type</th>
+ <th>Direction</th>
+ <th>Required</th>
+ <th>Default Value</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>value</td>
+ <td>Object</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ The value to be inserted. If the binding is null, then nothing is
+ inserted. Any object may be inserted, the
+ <code>toString()</code>
+ method is used to convert it to a printable value.
+ </td>
+ </tr>
+ <tr>
+ <td>format</td>
+ <td>
+ <a
+ href="http://java.sun.com/j2se/1.5.0/docs/api/java/text/Format.html">
+ Format
+ </a>
+ </td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ An optional format object used to convert the value parameter for
+ insertion into the HTML response.
+ </td>
+ </tr>
+ <tr>
+ <td>class</td>
+ <td>String</td>
+ <td>in</td>
+ <td>no</td>
+ <td></td>
+ <td>
+ If specified, then the output is wrapped in an HTML <span> tag,
+ using the value specified as the CSS class.
+
+ <p>Informal parameters are only rendered if a class is specified.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>raw</td>
+ <td>boolean</td>
+ <td>in</td>
+ <td>no</td>
+ <td>false</td>
+ <td>
+ If true, then the method
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IMarkupWriter.html#printRaw(java.lang.String)">
+ <code>IMarkupWriter.printRaw(String)</code>
+ </a>
+ is used, rather than
+ <a
+ href="../../tapestry-framework/apidocs/org/apache/tapestry/IMarkupWriter.html#print(java.lang.String)">
+ <code>IMarkupWriter.print(String)</code>
+ </a>
+ .
+
+ <p>
+ This bypasses the normal safeguards and is used when the value to
+ insert contains HTML markup that should be emitted as is.
+ </p>
+
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ Body:
+ <strong>removed</strong>
+ </p>
+
+ <p>
+ Informal parameters:
+ <strong>allowed</strong>
+ </p>
+
+ <p>
+ Reserved parameters:
+ <em>none</em>
+ </p>
+
+ </section>
+
+ <section name="Examples">
+
+
+
+ <p>
+ Inserts the pages dueDate and applies the specified DateFormat and HTML class.
+ Example output:
+ </p>
+
+ <img src="../../images/tapestry/ComponentReference/Insert.png"
+ alt="Insert Screen Shot" />
+
+ <p>HTML template</p>
+
+ <source xml:space="preserve">
+<table class="examples" cellpadding="8">
+<tr>
+ <td>
+ The order was due on the <font color="red"><b>
+ <span jwcid="@Insert" value="ognl:date" format="ognl:dateFormat" class="ognl:dueClass">21 January 2002</span>.
+ </td>
+</tr>
+</table>
+</source>
+
+ <p>
+ This will extract the date and dueClass properties from the page. It will also
+ obtain the dateFormat property (which is lazily instantiated), and use that to
+ format the date before inserting it.
+ </p>
+
+
+ <p>Java class</p>
+
+ <source xml:space="preserve">
+public abstract class EnquiryPage extends BasePage
+{
+ private Format _dateFormat;
+
+ public Format getDateFormat()
+ {
+ if (_dateFormat == null)
+ _dateFormat = new SimpleDateFormat("dd MMM yyyy");
+
+ return _dateFormat;
+ }
+
+ public abstract Date getDueDate();
+
+ public abstract String getDueClass();
+}
+</source>
+ </section>
+
+ </section>
+
+ </body>
+</document>
Propchange: tapestry/tapestry4/trunk/src/site/xdoc/components/Insert.xml
------------------------------------------------------------------------------
svn:eol-style = native