You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by hl...@apache.org on 2008/01/31 02:59:54 UTC
svn commit: r616985 - in /tapestry/tapestry5/trunk:
tapestry-component-report/src/main/java/org/apache/tapestry/mojo/
tapestry-core/src/main/java/org/apache/tapestry/corelib/components/
tapestry-core/src/main/java/org/apache/tapestry/internal/ tapestry...
Author: hlship
Date: Wed Jan 30 17:59:47 2008
New Revision: 616985
URL: http://svn.apache.org/viewvc?rev=616985&view=rev
Log:
TAPESTRY-2076: Create extra documentation for each component
Added:
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/If.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Label.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Loop.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Radio.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/RadioGroup.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Select.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Submit.xdoc
Modified:
tapestry/tapestry5/trunk/tapestry-component-report/src/main/java/org/apache/tapestry/mojo/ComponentReport.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/GridColumns.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Label.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Loop.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Radio.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Submit.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/TapestryInternalUtils.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumSelectModel.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumValueEncoder.java
tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/coerce.apt
tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/decorator.apt
tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/service.apt
Modified: tapestry/tapestry5/trunk/tapestry-component-report/src/main/java/org/apache/tapestry/mojo/ComponentReport.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-component-report/src/main/java/org/apache/tapestry/mojo/ComponentReport.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-component-report/src/main/java/org/apache/tapestry/mojo/ComponentReport.java (original)
+++ tapestry/tapestry5/trunk/tapestry-component-report/src/main/java/org/apache/tapestry/mojo/ComponentReport.java Wed Jan 30 17:59:47 2008
@@ -15,6 +15,7 @@
package org.apache.tapestry.mojo;
import nu.xom.*;
+import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.SystemUtils;
import org.apache.maven.artifact.Artifact;
import org.apache.maven.artifact.repository.ArtifactRepository;
@@ -28,7 +29,6 @@
import org.apache.tapestry.ioc.internal.util.InternalUtils;
import org.codehaus.doxia.sink.Sink;
import org.codehaus.doxia.site.renderer.SiteRenderer;
-import org.codehaus.plexus.util.StringUtils;
import org.codehaus.plexus.util.cli.CommandLineException;
import org.codehaus.plexus.util.cli.CommandLineUtils;
import org.codehaus.plexus.util.cli.Commandline;
@@ -145,6 +145,9 @@
}
+ private final static Set<String> SUPPORTED_SUBPACKAGES = CollectionFactory.newSet("base", "components", "mixins",
+ "pages");
+
/**
* Generates the report; this consist of the index page
*
@@ -175,8 +178,34 @@
sink.sectionTitle1_();
sink.list();
+ String currentSubpackage = null;
+
for (String className : InternalUtils.sortedKeys(descriptions))
{
+ String subpackage = extractSubpackage(className);
+
+ if (!SUPPORTED_SUBPACKAGES.contains(subpackage)) continue;
+
+ if (!subpackage.equals(currentSubpackage))
+ {
+ if (currentSubpackage != null)
+ {
+ sink.list_();
+ sink.section2_();
+ }
+
+ sink.section2();
+ sink.sectionTitle2();
+ sink.text(StringUtils.capitalize(subpackage));
+ sink.sectionTitle2_();
+
+
+ sink.list();
+
+ currentSubpackage = subpackage;
+ }
+
+
sink.listItem();
sink.link(className + ".html");
@@ -190,13 +219,24 @@
sink.listItem_();
}
- sink.list_();
+ if (currentSubpackage != null)
+ {
+ sink.list_();
+ sink.section2_();
+ }
}
catch (Exception ex)
{
throw new MavenReportException(ex.getMessage(), ex);
}
+ }
+
+ private String extractSubpackage(String className)
+ {
+ int dotx = className.indexOf(".", rootPackage.length() + 1);
+
+ return className.substring(rootPackage.length() + 1, dotx);
}
private List<File> createDocSearchPath()
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/GridColumns.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/GridColumns.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/GridColumns.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/GridColumns.java Wed Jan 30 17:59:47 2008
@@ -29,8 +29,7 @@
import java.util.List;
/**
- * Renders out the column headers for the grid. Eventually, this will include control over column sorting, perhaps even
- * column ordering.
+ * Renders out the column headers for the grid, including links (where appropriate) to control column sorting.
*/
public class GridColumns
{
@@ -41,9 +40,9 @@
private GridModelProvider _dataProvider;
/**
- * If true, then the CSS class on each <TH> cell will be omitted, which can reduce the amount of output from
- * the component overall by a considerable amount. Leave this as false, the default, when you are leveraging the CSS
- * to customize the look and feel of particular columns.
+ * If true, then the CSS class on each <TH> element will be omitted, which can reduce the amount of output
+ * from the component overall by a considerable amount. Leave this as false, the default, when you are leveraging
+ * the CSS to customize the look and feel of particular columns.
*/
@Parameter
private boolean _lean;
@@ -57,7 +56,7 @@
private String _sortColumnId;
/**
- * If true, then the sort is ascending (A - Z), if false the descending (Z - A).
+ * If true, then the sort is ascending (A - Z), if false then descending (Z - A).
*/
@Parameter(required = true)
private boolean _sortAscending;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Label.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Label.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Label.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Label.java Wed Jan 30 17:59:47 2008
@@ -27,10 +27,10 @@
/**
* Generates a <label> element for a particular field.
* <p/>
- * <p/>
- * A Label will render its body, if it has one. However, in most cases it will not have a body, and will render it's
- * {@linkplain org.apache.tapestry.Field#getLabel()} field's label} as it's body. Remember, however, that it is the
- * field label that will be used in any error messages.
+ * A Label will render its body, if it has one. However, in most cases it will not have a body, and will render its
+ * {@linkplain org.apache.tapestry.Field#getLabel() field's label} as it's body. Remember, however, that it is the field
+ * label that will be used in any error messages. The Label component allows for client- and server-side validation
+ * error decorations.
*/
@SupportsInformalParameters
public class Label
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Loop.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Loop.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Loop.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Loop.java Wed Jan 30 17:59:47 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.
@@ -29,12 +29,12 @@
import java.util.List;
/**
- * Basic looping class; loops over a number of items (provided by its source parameter), rendering
- * its body for each one. It turns out that gettting the component to <em>not</em> store its state
- * in the Form is very tricky and, in fact, a series of commands for starting and ending heartbeats,
- * and advancing through the iterator, are still stored. For a non-volatile Loop inside the form,
- * the Loop stores a series of commands that start and end heartbeats and store state (either as
- * full objects when there is not encoder, or as client-side objects when there is an encoder).
+ * Basic looping class; loops over a number of items (provided by its source parameter), rendering its body for each
+ * one. It turns out that gettting the component to <em>not</em> store its state in the Form is very tricky and, in
+ * fact, a series of commands for starting and ending heartbeats, and advancing through the iterator, are still stored.
+ * For a non-volatile Loop inside the form, the Loop stores a series of commands that start and end heartbeats and store
+ * state (either as full objects when there the encoder parameter is not bound, or as client-side objects when there is
+ * an encoder).
*/
@SupportsInformalParameters
public class Loop
@@ -53,8 +53,8 @@
};
/**
- * Setup command for volatile rendering. Volatile rendering relies on re-acquiring the Iterator
- * and working our way through it (and hoping for the best!).
+ * Setup command for volatile rendering. Volatile rendering relies on re-acquiring the Iterator and working our way
+ * through it (and hoping for the best!).
*/
private static final ComponentAction<Loop> SETUP_FOR_VOLATILE = new ComponentAction<Loop>()
{
@@ -68,9 +68,8 @@
};
/**
- * Advances to next value in a volatile way. So, the <em>number</em> of steps is intrinsically
- * stored in the Form (as the number of ADVANCE_VOLATILE commands), but the actual values are
- * expressly stored only on the server.
+ * Advances to next value in a volatile way. So, the <em>number</em> of steps is intrinsically stored in the Form
+ * (as the number of ADVANCE_VOLATILE commands), but the actual values are expressly stored only on the server.
*/
private static final ComponentAction<Loop> ADVANCE_VOLATILE = new ComponentAction<Loop>()
{
@@ -83,8 +82,8 @@
};
/**
- * Used in both volatile and non-volatile mode to end the current heartbeat (started by either
- * ADVANCE_VOLATILE or one of the RestoreState commands). Also increments the index.
+ * Used in both volatile and non-volatile mode to end the current heartbeat (started by either ADVANCE_VOLATILE or
+ * one of the RestoreState commands). Also increments the index.
*/
private static final ComponentAction<Loop> END_HEARTBEAT = new ComponentAction<Loop>()
{
@@ -98,8 +97,7 @@
};
/**
- * Restores a state value (this is the case when there is no encoder and the complete value is
- * stored).
+ * Restores a state value (this is the case when there is no encoder and the complete value is stored).
*/
static class RestoreState implements ComponentAction<Loop>
{
@@ -119,8 +117,7 @@
}
/**
- * Restores the value using a stored primary key via
- * {@link PrimaryKeyEncoder#toValue(Serializable)}.
+ * Restores the value using a stored primary key via {@link PrimaryKeyEncoder#toValue(Serializable)}.
*/
static class RestoreStateViaEncodedPrimaryKey implements ComponentAction<Loop>
{
@@ -169,15 +166,15 @@
private Iterable<?> _source;
/**
- * Optional primary key converter; if provided and inside a form and not volatile, then each
- * iterated value is converted and stored into the form.
+ * Optional primary key converter; if provided and inside a form and not volatile, then each iterated value is
+ * converted and stored into the form.
*/
@Parameter
private PrimaryKeyEncoder<Serializable, Object> _encoder;
/**
- * If true and the Loop is enclosed by a Form, then the normal state saving logic is turned off.
- * Defaults to false, enabling state saving logic within Forms.
+ * If true and the Loop is enclosed by a Form, then the normal state saving logic is turned off. Defaults to false,
+ * enabling state saving logic within Forms.
*/
@Parameter
private boolean _volatile;
@@ -186,8 +183,8 @@
private FormSupport _formSupport;
/**
- * The element to render. If not null, then the loop will render the indicated element around
- * its body (on each pass through the loop). The default is derived from the component template.
+ * The element to render. If not null, then the loop will render the indicated element around its body (on each pass
+ * through the loop). The default is derived from the component template.
*/
@Parameter(value = "prop:componentResources.elementName", defaultPrefix = "literal")
private String _elementName;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Radio.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Radio.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Radio.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Radio.java Wed Jan 30 17:59:47 2008
@@ -93,6 +93,9 @@
return _defaultProvider.defaultBinding("value", _resources);
}
+ /**
+ * Returns the element name provided by the containing {@link org.apache.tapestry.RadioContainer}.
+ */
public String getElementName()
{
return _elementName;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Submit.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Submit.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Submit.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/Submit.java Wed Jan 30 17:59:47 2008
@@ -27,18 +27,17 @@
import org.apache.tapestry.services.Request;
/**
- * Corresponds to <input type="submit">, a client-side element that can force the enclosing
- * form to submit. The submit responsible for the form submission will post a notification that
- * allows the application to know that it was the responsible entity. The notification is named
- * "selected" and has no context.
+ * Corresponds to <input type="submit">, a client-side element that can force the enclosing form to submit. The
+ * submit responsible for the form submission will post a notification that allows the application to know that it was
+ * the responsible entity. The notification is named "selected" and has no context.
*/
public final class Submit extends AbstractField
{
static final String SELECTED_EVENT = "selected";
/**
- * If true, then any notification sent by the component will be deferred until the end of the
- * form submission (this is usually desirable).
+ * If true (the default), then any notification sent by the component will be deferred until the end of the form
+ * submission (this is usually desirable).
*/
@Parameter
private boolean _defer = true;
@@ -97,8 +96,7 @@
// When not deferred, don't wait, fire the event now (actually, at the end of the current
// heartbeat). This is most likely because the Submit is inside a Loop and some contextual
- // information will change if we defer. Another option might be to wait until the next
- // heartbeak?
+ // information will change if we defer.
if (_defer) _formSupport.defer(sendNotification);
else _heartbeat.defer(sendNotification);
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/TapestryInternalUtils.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/TapestryInternalUtils.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/TapestryInternalUtils.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/internal/TapestryInternalUtils.java Wed Jan 30 17:59:47 2008
@@ -472,6 +472,12 @@
}
/**
+ * Converts an enum to a label string, allowing for overrides from a message catalog.
+ * <p/>
+ * <ul> <li>As key <em>prefix</em>.<em>name</em> if present. Ex: "ElementType.LOCAL_VARIABLE" <li>As key
+ * <em>name</em> if present, i.e., "LOCAL_VARIABLE". <li>As a user-presentable version of the name, i.e., "Local
+ * Variable". </ul>
+ *
* @param messages the messages to search for the label
* @param prefix
* @param value to get a label for
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumSelectModel.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumSelectModel.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumSelectModel.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumSelectModel.java Wed Jan 30 17:59:47 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.
@@ -26,14 +26,10 @@
import java.util.List;
/**
- * A basic select model for a particular Enum type. The labels for each Enum are drawn from the Enum
- * instance name and the provides message catalog:
- * <ul>
- * <li>As key <em>ClassName</em>-<em>name</em> if present. The class name excludes the
- * package portion. Ex: "ElementType.LOCAL_VARIABLE"
- * <li>As key <em>name</em> if present, i.e., "LOCAL_VARIABLE".
- * <li>As a user-presentable version of the name, i.e., "Local Variable".
- * </ul>
+ * A basic select model for a particular Enum type. The labels for each Enum are drawn from the Enum instance name and
+ * the provides message catalog: <ul> <li>As key <em>ClassName</em>.<em>name</em> if present. The class name excludes
+ * the package portion. Ex: "ElementType.LOCAL_VARIABLE" <li>As key <em>name</em> if present, i.e., "LOCAL_VARIABLE".
+ * <li>As a user-presentable version of the name, i.e., "Local Variable". </ul>
*/
public final class EnumSelectModel extends AbstractSelectModel implements Serializable
{
@@ -51,7 +47,7 @@
notNull(enumClass, "enumClass");
notNull(messages, "messages");
- String prefix = TapestryInternalUtils.lastTerm(enumClass.getName());
+ String prefix = enumClass.getSimpleName();
for (T value : values)
{
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumValueEncoder.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumValueEncoder.java?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumValueEncoder.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/util/EnumValueEncoder.java Wed Jan 30 17:59:47 2008
@@ -18,8 +18,7 @@
import static org.apache.tapestry.ioc.internal.util.Defense.notNull;
/**
- * A value encoder that can be used for aribrary Enum types. The enum name is stored as the client side value (the
- * "primary key").
+ * A value encoder that can be used for aribrary Enum types. The enum name is stored as the client side value.
*/
public class EnumValueEncoder<E extends Enum<E>> implements ValueEncoder<E>
{
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/If.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/If.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/If.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/If.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,56 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <subsection name="Start.tml">
+
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+ <h1>Welcome!</h1>
+
+ <t:if test="user">
+ Welcome back, ${user.firstName}
+ <t:parameter name="else">
+ <t:pagelink name="login">Login</t:pagelink> /
+ <t:pagelink name="register">Register</t:pagelink>
+ </t:parameter>
+ </t:if>
+
+ . . .
+
+</html>]]></source>
+
+ <p>
+ Here, the main text is rendered if the user is logged in (the user property will
+ be non-null after the user logs in). Otherwise, links to a login and register
+ page are rendered.
+ </p>
+
+ </subsection>
+
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ Tapestry has many builtin coercions to boolean:
+ </p>
+
+ <dl>
+ <dt>String</dt>
+ <dd>True if non-blank</dd>
+
+ <dt>Number</dt>
+ <dd>True if non-zero</dd>
+ <dt>Collection</dt>
+ <dd>True if non-empty</dd>
+ <dt>Object</dt>
+ <dd>True (as long as its not null)</dd>
+ </dl>
+
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Label.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Label.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Label.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Label.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,50 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <subsection name="Search.tml">
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+
+ <t:form>
+ <t:label for="search"/>
+ <t:textfield t:id="search" size="50"/>
+
+ <t:checkbox t:id="all"/>
+ <t:label for="all">
+ Include out of date records
+ </t:label>
+
+ . . .
+
+</html>]]></source>
+
+ <p>
+ This demonstrates that the Label can come before
+ or after the form control element component (the TextField and Checkbox components).
+ When a Label has a body, that takes precendence over the field's label, though the field's
+ label is what's used in any error messages.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ The Label component is very important for user accessiblity. A user will be able to click
+ on the label to move the cursor into the corresponding field.
+ </p>
+
+ <p>
+ The Label component supports informal parameters; this can be very useful
+ for adding the
+ <code>accesskey</code>
+ attribute supported by most browsers.
+ </p>
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Loop.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Loop.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Loop.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Loop.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,225 @@
+<document>
+ <body>
+ <section name="Basic Example">
+
+ <p>
+ This example is based around a NavBar component that generates a set
+ of links to other pages in the applilcation.
+ </p>
+
+ <subsection name="NavBar.tml">
+
+ <source><![CDATA[
+<table class="navigation" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+
+ <tr>
+ <t:loop source="pageNames" value="pageName">
+ <td class="${tabClass}">
+ <t:pagelink page="pageName">${pageName}</t:pagelink>
+ </td>
+ </t:loop>
+ </tr>
+
+</table>]]></source>
+
+ <p>
+ We are assuming that the NavBar component
+ has a pageNames property (possibly a parameter). The Loop will
+ iterate over those page names and store each into its value parameter.
+ </p>
+
+ <p>Often, the value parameter will be bound to a writable property of the container,
+ but here we are using the "var:" binding prefix to store the page name into
+ a temporary render variable.
+ </p>
+
+
+ </subsection>
+
+
+ <subsection name="NavBar.java">
+
+ <source><![CDATA[
+public class NavBar
+{
+ @Parameter(defaultPrefix="literal", required=true)
+ private String _pages;
+
+ @Inject
+ private ComponentResources _resources;
+
+ private String _pageName;
+
+ public String getPageName() { return _pageName; }
+
+ public void setPageName(String pageName) { _pageName = pageName; }
+
+ public String[] getPageNames()
+ {
+ return _pages.split(",");
+ }
+
+ public String getTabClass()
+ {
+ if (_pageName.equalsIgnoreCase(_resources.getPageName())
+ return "current";
+
+ return null;
+ }
+}
+]]></source>
+
+ <p>
+ The component converts its pages parameter into the pageNames property
+ by splitting it at the commas. It tracks the current pageName of the loop
+ not just to generate the links, but to calculate the CSS class of each
+ <td> element on the fly. This way we can give the tab corresponding
+ to the current page a special look or highlight.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ <section name="Invisible Instrumentation">
+
+ <p>We can fold together the Loop component and the <td> element:</p>
+
+ <subsection name="NavBar.tml">
+
+ <source><![CDATA[
+<table class="navigation" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+
+ <tr>
+ <td t:type="loop" source="pageNames" value="pageName" class="${tabClass}">
+ <t:pagelink page="pageName">${pageName}</t:pagelink>
+ </td>
+ </tr>
+
+</table>]]></source>
+
+ <p>Using the
+ <code>t:type="loop"</code>
+ attribute, the other way to identify a template
+ element as a component, allows the Loop component to render the element's tag,
+ the <td> on each iteration, along with informal parameters (the class attribute). This is
+ called<em>invisible instrumentation</em>, and it is more concise and more
+ editor/preview friendly than Tapestry's typical markup.
+ </p>
+ </subsection>
+ </section>
+
+ <section name="Forms and Loops Example">
+
+ <p>
+ Tapestry form control element components (TextField, etc.) work inside loops. However,
+ some additional configuration is needed to make this work efficiently.
+ </p>
+
+ <p>
+ With no extra configuration, each value object will be serialized into the form (if
+ you view the rendered markup, you'll see a hidden form field containing serialized data needed by
+ Tapestry to process the form). This can become very bloated, or may not work if the objects being
+ iterated
+ are not serializable.
+ </p>
+
+ <p>
+ The typical case is database driven; you are editting objects from a database and need
+ those objects back when the form is submitted. All that should be stored
+ on the client is the
+ <em>ids</em>
+ of those objects. Thats what the encoder
+ parameter is for.
+ </p>
+
+ <subsection name="EditOrder.tml">
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+
+ <h1>Edit Order Quantities</h1>
+
+ <t:form>
+
+ <t:errors/>
+
+ <t:loop source="items" value="item" encoder="encoder">
+ <div class="line-item">
+ <t:label for="quantity">${item.product.name}</t:label>
+ <t:textfield t:id="quantity" value="item.quantity"/>
+ </div>
+ </t:loop>
+
+ <input type="submit" value="Update"/>
+ </t:form>
+ </body>
+</html>]]></source>
+
+ <p>
+ The TextField component is rendered multiple times, once
+ for each LineItem in the Order.
+ </p>
+ </subsection>
+
+ <subsection name="EditOrder.java">
+ <source><![CDATA[
+public class EditOrder
+{
+ @Inject
+ private OrderDAO _orderDAO;
+
+ private final PrimaryKeyEncoder<Long,LineItem> _encoder = new PrimaryKeyEncoder<Long,LineItem>()
+ {
+ public Long toKey(LineItem value) { return value.getId(); }
+
+ public void prepareForKeys(List<Long> keys) { }
+
+ public LineItem toValue(Long key)
+ {
+ return _orderDAO.getLineItem(key);
+ }
+ };
+
+ @Persist
+ private long _orderId;
+
+ private LineItem _item;
+
+ public PrimaryKeyEncoder getEncoder() { return _encoder ; }
+
+ public List<LineItem> getItems()
+ {
+ return _orderDAO.getLineItemsForOrder(_orderId);
+ }
+
+ public LineItem getItem() { return _item; }
+
+ public void setLineItem(LineItem item) { _item = item; }
+}]]></source>
+
+ <p>
+ Here, we expect the OrderDAO service to do most of the work,
+ and we create a wrapper around it, in the form of the
+ PrimeryKeyEncoder instance.
+ </p>
+
+ <p>
+ We've glossed over a few issues here, including how to handle
+ the case that a particular item has been deleted or changed
+ between the render request and the form submission.
+ </p>
+
+ <p>
+ Accounding for those situations would largely be encapsulated inside
+ the PrimeryKeyEncoder instance.
+ </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/Radio.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Radio.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Radio.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Radio.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,110 @@
+<document>
+ <body>
+ <section name="Examples">
+ <p>
+ Radio components are always used in conjunction with
+ a RadioGroup component. The RadioComponent defines the property
+ that will be read and updated, and the individual Radio
+ components determine what value will be assigned to the property.
+ </p>
+
+ <p>
+ Our example will be part of a page that collects credit card information.
+ We'll just be showing the portions related to
+ a set of radio buttons for choosing the type of credit card.
+ </p>
+
+ <subsection name="CardType.java">
+
+ <source><![CDATA[
+public enum CardType
+{
+ MASTER_CARD, VISA, AMERICAN_EXPRESS, DINERS_CLUB, DISCOVER
+}
+]]></source>
+
+ </subsection>
+
+ <subsection name="Payment.tml (partial)">
+
+ <source><![CDATA[
+
+ <t:radiogroup t:id="type" t:encoder="cardTypeEncoder"/>
+ <t:radio t:id="masterCard"/> <t:label for="masterCard"/>
+ <t:radio t:id="visa"/> <t:label for="visa"/>
+ <t:radio t:id="amex"/> <t:label for="amex"/>
+ <t:radio t:id="dinersClub"/> <t:label for="dinersClub"/>
+ <t:radio t:id="discover"/> <t:label for="discover"/>
+ </t:radiogroup>
+
+ ]]></source>
+
+ <p>
+ The advantage of using radio buttons here, rather than a drop down list,
+ is that we could extend the labels to use a small image of each
+ type of supported card.
+ </p>
+
+ <p>
+ We're once again using the trick of matching the component's id
+ to a property of the containing page. The RadioGroup's value parameter
+ will be bound to the page's type property. Likewise, each of the
+ Radio components will be matched to a property of the page.
+ </p>
+
+ </subsection>
+
+ <subsection name="Payment.java (partial)">
+
+ <source><![CDATA[
+
+public class Payment
+{
+ . . .
+
+ @Persist
+ private CardType _type;
+
+ public ValueEncoder getCardTypeEncoder()
+ {
+ return new EnumValueEncoder(CardType.class);
+ }
+
+ public CardType getType() { return _type; }
+
+ public void setType(CardType type) { _type = type; }
+
+ public CardType getMasterCard() { return CardType.MASTER_CARD; }
+
+ public CardType getVisa() { return CardType.VISA; }
+
+ public CardType getAmex() { return CardType.AMERICAN_EXPRESS; }
+
+ public CardType getDinersClub() { return CardType.DINERS_CLUB; }
+
+ public CardType getDiscover() { return CardType.DISCOVER; }
+
+ . . .
+}]]></source>
+
+
+ <p>
+ We use a number of read-only properties to provide
+ each Radio component with its Enum value, that will
+ ultimately be assigned to the page's type property
+ (if that corresponding Radio component is selected by the user).
+ </p>
+
+ <p>
+ This is far from the only pattern of usage; it is much more likely
+ that you will use a Loop component around a single Radio component
+ than you will use a whole array of Radio components as in this example.
+ </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/RadioGroup.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/RadioGroup.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/RadioGroup.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/RadioGroup.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,10 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ Examples are provided with the documentation of the Radio component.
+ </p>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Select.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Select.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Select.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Select.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,99 @@
+<document>
+ <body>
+ <section name="Simple Example">
+
+ <p>
+ A simple example, selecting one of three strings:
+ </p>
+
+ <subsection name="SelectColor.tml (partial)">
+ <source><![CDATA[
+ Select a color:
+ <t:select t:id="color" model="literal:Red,Blue,Green"/>
+]]></source>
+
+ <p>
+ When the model parameter is a string, it is broken apart at the commas.
+ </p>
+
+ <p>
+ When using this approach, you'll commonly put the list into the message catalog,
+ and reference it using a "message:" binding.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ <section name="Enum Example">
+
+ <p>Working with Enums is, amazingly, even easier (and more so than with the Radio component).</p>
+
+ <subsection name="CardType.java">
+
+ <source><![CDATA[
+public enum CardType
+{
+ MASTER_CARD, VISA, AMERICAN_EXPRESS, DINERS_CLUB, DISCOVER
+}
+]]></source>
+
+ </subsection>
+
+ <subsection name="Payment.tml (partial)">
+
+ <source><![CDATA[
+
+ <t:select t:id="type"/>
+
+ ]]></source>
+
+
+ <p>
+ Here again, Tapestry is binding the value parameter to the type property, based on the component's
+ id.
+ In addition, because the property type of the property in question is an enum, a SelectModel
+ is automatically generated.
+ </p>
+
+ </subsection>
+
+ <subsection name="Payment.java (partial)">
+
+ <source><![CDATA[
+
+public class Payment
+{
+ . . .
+
+ @Persist
+ private CardType _type;
+
+ public CardType getType() { return _type; }
+
+ public void setType(CardType type) { _type = type; }
+
+ . . .
+}]]></source>
+
+
+ </subsection>
+
+ <subsection name="Payment.properties">
+
+ <source><![CDATA[DINERS_CLUB=Diner's Club]]></source>
+
+ <p>
+ Tapestry is able to make very good guesses about the labels to use in the Select component, it
+ <em>humanizes</em>
+ the enum names to user presentable labels: "Master Card", "Visa", etc.
+ However, it doesn't get "Diner's Club" just right, so we provide an override in the page's
+ message catalog.
+ </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/Submit.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Submit.xdoc?rev=616985&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Submit.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/Submit.xdoc Wed Jan 30 17:59:47 2008
@@ -0,0 +1,69 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ The thing to remember is that the Submit component will trigger its "selected" event in the
+ <em>middle</em>
+ of the form submission, before the form triggers its "validate", "success" (or "failure") and "submit"
+ events.
+ Thus the best thing to do is to store in a temporary field what should be done inside the "success"
+ event handler.
+ </p>
+
+ <subsection name="EditUser.tml">
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+
+ <h1>Edit User</h1>
+
+ <t:form>
+
+ <t:errors/>
+
+ <t:beaneditor t:id="user"/>
+
+ <p>
+ <input type="submit" value="Update User"/>
+ <t:submit t:id="delete" value="Delete User"/>
+ </p>
+
+ </t:form>
+</html>]]></source>
+ </subsection>
+
+
+ <subsection name="EditUser.java">
+ <source><![CDATA[
+public class EditUser
+{
+ @Inject
+ private UserDAO _userDAO;
+
+ @Persist
+ private User _user;
+
+ private boolean _deleteUser;
+
+ void onSelectedFromDelete() { _deleteUser = true; }
+
+ Object onSuccess()
+ {
+ if (_deleteUser)
+ _userDAO.delete(user.getId());
+ else
+ _userDAO.update(user);
+
+ return UserList.class;
+ }
+
+ public void setUser(User user) { _user = user; }
+
+ public User getUser() { return _user; }
+}]]></source>
+ </subsection>
+
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/coerce.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/coerce.apt?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/coerce.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/coerce.apt Wed Jan 30 17:59:47 2008
@@ -36,7 +36,7 @@
Contributing new Coercions
TypeCoercer is extensible, you may add new coercions as desired. For example, let's say you have a Money type that represents
- an amount of some currency, and you want to be able to convert between BigDecimal and Money. Further, let's assume that
+ an amount of some currency, and you want to be able to convert from BigDecimal to Money. Further, let's assume that
Money has a constructor that accepts a BigDecimal as its parameter. We'll use a little Tapestry IOC configuration jujitsu to
inform the TypeCoercer about this coercion.
Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/decorator.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/decorator.apt?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/decorator.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/decorator.apt Wed Jan 30 17:59:47 2008
@@ -90,8 +90,9 @@
The values that may be provided to a decorator method are exactly the same as for a builder
method, with one addition: The underlying service will be passed in
- as a parameter of type java.lang.Object. A decorator method must have one
- parameter of type java.lang.Object for this purpose.
+ as a parameter of type java.lang.Object (after type erasure, the <<<T delegate>>> parameter
+ becomes <<<Object delegate>>>). A decorator method must have one
+ parameter for this purpose.
In the above example, the decorator method recieves the core service implementation,
the service interface for the Indexer service, the Log for the Indexer service,
Modified: tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/service.apt
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/service.apt?rev=616985&r1=616984&r2=616985&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/service.apt (original)
+++ tapestry/tapestry5/trunk/tapestry-ioc/src/site/apt/service.apt Wed Jan 30 17:59:47 2008
@@ -465,7 +465,7 @@
* java.lang.String: unique id for the service
- * {{{http://www.slf4j.org/api/org/slf4j/Logger.html}org.slf5j.Logger}}: logger for the service
+ * {{{http://www.slf4j.org/api/org/slf4j/Logger.html}org.slf4j.Logger}}: logger for the service
* java.lang.Class: service interface implemented by the service to be constructed
@@ -576,13 +576,13 @@
*---------------------+-----------------------------------------------------------------------------------------+
| <<Service Id>> | <<Service Interface>> |
*---------------------+-----------------------------------------------------------------------------------------+
-| ClassFactory | {{{../apidocs/org/apache/tapestry/ioc/services/ClassFactory.html}ClassFactory}} |
+| ClassFactory | {{{../apidocs/org/apache/tapestry/ioc/services/ClassFactory.html}ClassFactory}} |
*---------------------+-----------------------------------------------------------------------------------------+
-| LogSource | {{{../apidocs/org/apache/tapestry/ioc/LogSource.html}LogSource}} |
+| LoggerSource | {{{../apidocs/org/apache/tapestry/ioc/LoggerSource.html}LoggerSource}} |
*---------------------+-----------------------------------------------------------------------------------------+
-| RegistryShutdownHub | {{{../apidocs/org/apache/tapestry/ioc/RegistryShutdownHub.html}RegistryShutdownHub}} |
+| RegistryShutdownHub | {{{../apidocs/org/apache/tapestry/ioc/RegistryShutdownHub.html}RegistryShutdownHub}} |
*---------------------+-----------------------------------------------------------------------------------------+
-| ThreadCleanupHub | {{{../apidocs/org/apache/tapestry/ioc/services/ThreadCleanupHub.html}ThreadCleanupHub}} |
+| ThreadCleanupHub | {{{../apidocs/org/apache/tapestry/ioc/services/ThreadCleanupHub.html}ThreadCleanupHub}} |
*---------------------+-----------------------------------------------------------------------------------------+
Consult the JavaDoc for each of these services to identify under what circumstances you'll need to use them.
@@ -606,7 +606,7 @@
return indexer;
}
- public static build(Indexer indexer)
+ public static Indexed build(Indexer indexer)
{
return new FileSystemImpl(indexer);
}
@@ -616,7 +616,7 @@
of them will be created ... let's say its FileSystem. The buildFileSystem() builder
method will be invoked, and a proxy to Indexer will be passed in. Inside the
FileSystemImpl constructor (or at some later date), a method of the Indexer service
- will be invoked, at which point, the builderIndexer() method is invoke. It still receives
+ will be invoked, at which point, the builderIndexer() method is invoked. It still receives
the proxy to the FileSystem service.
If the order is reversed, such that Indexer is built before FileSystem, everything still
@@ -627,7 +627,7 @@
The exception to this rule is a service that depends on itself <during construction>.
This can occur when (indirectly, through other services) building the service
- trys to invoke a method on the service being built. This can happen when the service
+ tries to invoke a method on the service being built. This can happen when the service
implemention's constructor invoke methods on service dependencies passed into it,
or when the service builder method itself does the same. This is actually a very rare
case and difficult to illustrate.