You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by hl...@apache.org on 2008/01/30 04:11:42 UTC
svn commit: r616604 - in /tapestry/tapestry5/trunk/tapestry-core/src/main:
java/org/apache/tapestry/corelib/components/
resources/org/apache/tapestry/corelib/components/
Author: hlship
Date: Tue Jan 29 19:11:41 2008
New Revision: 616604
URL: http://svn.apache.org/viewvc?rev=616604&view=rev
Log:
TAPESTRY-2076: Start creating extra documentation for each component
Added:
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Checkbox.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Delegate.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Errors.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/EventLink.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Form.xdoc
Modified:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Delegate.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Errors.java
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Delegate.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Delegate.java?rev=616604&r1=616603&r2=616604&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Delegate.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Delegate.java Tue Jan 29 19:11:41 2008
@@ -1,4 +1,4 @@
-// Copyright 2007 The Apache Software Foundation
+// Copyright 2007, 2008 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.
@@ -18,15 +18,14 @@
import org.apache.tapestry.annotations.Parameter;
/**
- * A component that does not do any rendering of its own, but will delegate to some other object
- * that can do rendering. This other object may be a component or a {@link Block} (among other
- * things).
+ * A component that does not do any rendering of its own, but will delegate to some other object that can do rendering.
+ * This other object may be a component or a {@link Block} (among other things).
*/
public class Delegate
{
/**
- * Th object which will be rendered in place of the Delegate component. This is typically a
- * specific component instance, or a {@link Block}.
+ * The object which will be rendered in place of the Delegate component. This is typically a specific component
+ * instance, or a {@link Block}.
*/
@Parameter(required = true)
private Object _to;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Errors.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Errors.java?rev=616604&r1=616603&r2=616604&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Errors.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Errors.java Tue Jan 29 19:11:41 2008
@@ -1,4 +1,4 @@
-// Copyright 2006, 2007 The Apache Software Foundation
+// Copyright 2006, 2007, 2008 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.
@@ -25,15 +25,15 @@
import java.util.List;
/**
- * Standard validation error presenter. Must be enclosed by a {@link org.apache.tapestry.corelib.components.Form} component. If errors are
- * present, renders a div element around a banner message and around an unnumbered list of error
- * messages. Renders nothing if the {@link org.apache.tapestry.ValidationTracker} shows no errors.
+ * Standard validation error presenter. Must be enclosed by a {@link org.apache.tapestry.corelib.components.Form}
+ * component. If errors are present, renders a div element around a banner message and around an unnumbered list of
+ * error messages. Renders nothing if the {@link org.apache.tapestry.ValidationTracker} shows no errors.
*/
public class Errors
{
/**
- * The banner message displayed above the errors. The default value is "You must correct the
- * following errors before you may continue.".
+ * The banner message displayed above the errors. The default value is "You must correct the following errors before
+ * you may continue.".
*/
@Parameter("message:default-banner")
private String _banner;
@@ -53,9 +53,6 @@
void beginRender(MarkupWriter writer)
{
- // TODO: Would be nice if there was a Location to report ... can we add a Location property
- // to ComponentResources?
-
if (_tracker == null) throw new RuntimeException(InternalMessages.encloseErrorsInForm());
if (!_tracker.getHasErrors()) return;
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Checkbox.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Checkbox.xdoc?rev=616604&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Checkbox.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Checkbox.xdoc Tue Jan 29 19:11:41 2008
@@ -0,0 +1,91 @@
+<document>
+ <body>
+ <section name="Examples">
+
+
+ <p>
+ In this example, a Checkbox will be used alone to manipulate a property of the page.
+ </p>
+
+ <subsection name="ViewAccounts.tml">
+
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+ <h1>View Accounts</h1>
+
+ <t:form>
+ <t:checkbox t:id="showall" onclick="this.form.submit();"/> <t:label for="showall"/>
+ </t:form>
+
+ <t:grid t:id="accounts"/>
+
+ </body>
+</html>
+]]></source>
+
+ <p>
+ The Grid component will do most of the work in terms of displaying the account data.
+ </p>
+
+ <p>
+ Normally, we should bind the value parameter explicitly; here the component's id, "showAll",
+ matches against a property of the page and the value parameter is automatically bound
+ as a convienience.
+ </p>
+
+ <p>
+ A small amount of JavaScript is provided in-line to submit the form when the checkbox is clicked.
+ </p>
+
+ <p>
+ All Tapestry form control element components must be enclosed by a Form component.
+ </p>
+
+ <p>
+ The Label component is responsible for rendering a <label> element connected to the checkbox.
+ This
+ is good for accessibility, it also provides a larger "target" to click on.
+ The label's text will be "Show All", derived from the property name. Using a Label component is
+ optional
+ but recommended.
+ </p>
+
+
+ </subsection>
+
+ <subsection name="ViewAccounts.java">
+
+ <source><![CDATA[
+public class ViewAccount
+{
+ @Persist
+ private boolean _showAll;
+
+ @Inject
+ private AccountDAO _accountDAO;
+
+ public boolean isShowAll() { return _showAll; }
+
+ public void setShowAll(boolean showAll) { _showAll = showAll; }
+
+ public List<Account> getAccounts()
+ {
+ return _showAll ? _accountDAO.getAllAccounts() : _accountDAO.getActiveAccounts();
+ }
+}]]></source>
+
+ <p>
+ The component updates the _showAll field, and that's used to determine which
+ set of accounts should be provided to the Grid component. As always in Tapestry, you
+ must be careful to mark fields persistent if they need to hold their value between
+ the action request (the form submission) and the render request.
+ </p>
+
+
+ </subsection>
+
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Delegate.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Delegate.xdoc?rev=616604&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Delegate.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Delegate.xdoc Tue Jan 29 19:11:41 2008
@@ -0,0 +1,111 @@
+<document>
+ <body>
+
+ <section name="Examples">
+
+ <p>
+ The Delegate component allows us to be very flexible in how and what gets rendered, and
+ in what order. In some cases, the object to be rendered may come from an entirely
+ different page.
+ </p>
+
+ <p>
+ This example is simpler, and could easily be accomplished using an If component. We'll create
+ a page that can be used for viewing or editting an object.
+ </p>
+
+ <subsection name="ViewAccount.tml">
+
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+ <h1>View Account</h1>
+
+ <t:delegate to="activeBlock"/>
+
+ <t:block id="view">
+ <t:beandisplay object="account"/>
+
+ <p><t:actionlink t:id="edit">Edit this account</t:actionlink></p>
+ </t:block>
+
+ <t:block id="edit">
+ <t:beaneditform t:id="account"/>
+ </t:block>
+ </body>
+</html>]]></source>
+
+ <p>
+ So we end up with a display of the Account's properties, and a link to activate edit mode.
+ In edit mode, we use the other block and show a BeanEditForm.
+ </p>
+
+ </subsection>
+
+ <subsection name="ViewAccount.java">
+ <source><![CDATA[
+public class ViewAccount
+{
+ @Persist
+ private Account _account;
+
+ @Persist
+ private boolean _editMode;
+
+ @Inject
+ private Block _view;
+
+ @Inject
+ private Block _edit;
+
+ @Inject
+ private AccountDAO _accountDAO;
+
+ public Account getAccount()
+ {
+ return _account;
+ }
+
+ public void setAccount(Account account)
+ {
+ _account = account;
+ _editMode = false;
+ }
+
+ void onSuccess()
+ {
+ _accountDAO.update(_account);
+
+ _editMode = false;
+ }
+
+ void onActionFromEdit()
+ {
+ _editMode = true;
+ }
+
+ public Object getActiveBlock()
+ {
+ return _editMode ? _edit : _view;
+ }
+}]]></source>
+
+ <p>
+ The use of the @Inject annotation on a field of type Block is used to access a
+ <code><![CDATA[<t:block>]]></code>
+ element from the template. The field name,
+ stripped of leading underscores, is matched against the block's id.
+ </p>
+
+ <p>
+ The rest is concerned with handling the form submission, turning on edit mode,
+ and determining which block will be the one to render.
+ </p>
+
+
+ </subsection>
+
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Errors.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Errors.xdoc?rev=616604&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Errors.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Errors.xdoc Tue Jan 29 19:11:41 2008
@@ -0,0 +1,39 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ The Errors component automatically connects with the Form that encloses it. Just place the
+ component inside a Form.
+ </p>
+
+ <subsection name="Search.tml">
+
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+
+ <t:form>
+
+ <t:errors>
+
+ <t:label for="search"/>
+ <t:textfield t:id="search"/>
+
+ <input type="submit" value="Search"/>
+
+ </t:form>
+
+ </body>
+</html>]]></source>
+
+ <p>
+ The Errors component here will display any validation errors that occur when the form is submitted.
+ </p>
+
+ </subsection>
+
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/EventLink.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/EventLink.xdoc?rev=616604&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/EventLink.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/EventLink.xdoc Tue Jan 29 19:11:41 2008
@@ -0,0 +1,81 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ This example is from Tapestry itself, from the GridColumns component that displays the columns
+ titles across to the top of a Grid. We've simplified the example somewhat to focus in on
+ the use of the EventLink component.
+ </p>
+
+ <subsection name="GridColumns.tml">
+ <source><![CDATA[
+<thead xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <tr>
+ <th t:type="Loop" source="columnNames" value="columnName">
+ <a t:id="sort">${columnModel.label}</a>
+ <a t:id="sort2">
+ <img src="${icon}" id="${columnModel.id}:sort" class="t-sort-icon" alt="${iconLabel}"/>
+ </a>
+ </th>
+ </tr>
+</thead>]]></source>
+
+ </subsection>
+
+ <subsection name="GridColumns.java (partial)">
+ <source><![CDATA[
+public class GridColumns
+{
+ . . .
+
+ @Component(parameters = {"event=sort", "context=columnModel.id"})
+ private EventLink _sort, _sort2;
+
+ void onSort(String columnId)
+ {
+ if (columnId.equals(_sortColumnId))
+ {
+ _sortAscending = !_sortAscending;
+ }
+ else
+ {
+ _sortColumnId = columnId;
+ _sortAscending = true;
+ }
+ }
+
+}]]></source>
+
+ <p>
+ The advantage of the EventLink component is that instead of having two identical event handler
+ methods,
+ onActionFromSort() and onActionFromSort2(), we have a single event handler method,
+ onSort(), that covers events triggered by either component. In addition, the URLs for the two
+ components
+ will be identical, whereas if using ActionLink components, the URLs would be slightly different, to
+ reflect to two different component ids.
+ </p>
+
+ <p>
+ This example also shows the advantages of defining the component in the Java class,
+ using the
+ @Component annotation, rather than in the template (as we do in most examples). We can
+ simply define two fields with the same configuration.
+ </p>
+
+
+ </subsection>
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ The event parameter is often omitted; it defaults to the component's id ... you will often specify
+ the component id, or a specific event name, but not both.
+ </p>
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Form.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Form.xdoc?rev=616604&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Form.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Form.xdoc Tue Jan 29 19:11:41 2008
@@ -0,0 +1,117 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ Examples of the Form component are provided in the many
+ other pages that discuss specific form control element components,
+ such as TextArea.
+ </p>
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ The Form component generates a seemingly bewildering number of
+ events, designed to address a wide range of needs. The goal
+ is to give you as the developer the tools necessary to
+ effeciently manage state.
+ </p>
+
+ <p>
+ All of the events that are triggered will pass along
+ the values defined by the context parameter. Most often,
+ there is no context, or the context is a single value
+ (a primary key used to identify the object being updated
+ by the form).
+ </p>
+
+
+ <subsection name="Render Events">
+
+ <p>
+ Render event handler methods should
+ <em>not</em>
+ return a value, doing
+ so will be an error. The methods are intended to allow
+ the page to convert a primary key stored in the context
+ back into an object ready to have its properties updated
+ by the Form.
+ </p>
+
+ <p>
+ The context passed to component event handler methods is provided by reading the context parameter.
+ </p>
+
+ <ul>
+ <li>prepareForRender</li>
+ <li>prepare</li>
+ </ul>
+
+
+ </subsection>
+
+ <subsection name="Submit Events">
+
+ <p>
+ Submit events may return a navigational value, which will
+ abort any remaining processing of the form submission.
+ </p>
+
+ <p>
+ The context provided to component event handler methods
+ originates in the form submission (it is stored in hidden form fields); the
+ context parameter is
+ <em>not</em>
+ read during a form submission.
+ </p>
+
+ <ul>
+ <li>prepareForSubmit</li>
+ <li>prepare</li>
+ <li>validate</li>
+ <li>failure
+ <em>or</em>
+ success
+ </li>
+ <li>submit</li>
+ </ul>
+
+ <p>
+ The validate event is to allow the page to
+ perform cross-field validation. The failure or success
+ event is fired based on whether there are or are not any
+ validation errors.
+ </p>
+
+ </subsection>
+
+
+ <subsection name="Form Ids">
+
+ <p>
+ It is considered a best practice to give explicit ids to
+ Form components, and form control element components.
+ These ids propogate down to the client side as
+ element names and/or ids, and eventually show up
+ as query parameters when the form is submitted.
+ </p>
+
+ <p>
+ To achieve a more RESTful URL scheme, give the form component
+ an id based on what it does rather than what data it updates, thus
+ <code><![CDATA[<t:form t:id="search"/>]]></code>
+ rather than
+ <code><![CDATA[<t:form t:id="searchData"/>]]></code>
+ or
+ <code><![CDATA[<t:form t:id="searchForm"/>]]></code>.
+
+ </p>
+
+
+ </subsection>
+
+ </section>
+ </body>
+</document>
\ No newline at end of file