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/29 22:37:19 UTC
svn commit: r616528 - in /tapestry/tapestry5/trunk:
tapestry-component-report/src/main/java/org/apache/tapestry/mojo/
tapestry-core/src/main/java/org/apache/tapestry/corelib/base/
tapestry-core/src/main/java/org/apache/tapestry/corelib/components/ tape...
Author: hlship
Date: Tue Jan 29 13:37:18 2008
New Revision: 616528
URL: http://svn.apache.org/viewvc?rev=616528&view=rev
Log:
TAPESTRY-2076: Start creating extra documentation for each component
Added:
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentEventLink.java
- copied, changed from r614985, tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentActionLink.java
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/ActionLink.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanDisplay.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanEditForm.xdoc
tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/PageLink.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/ActionLink.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanDisplay.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanEditForm.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/EventLink.java
tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/BeanModelSource.java
tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml
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=616528&r1=616527&r2=616528&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 Tue Jan 29 13:37:18 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,9 +18,11 @@
import org.apache.commons.lang.SystemUtils;
import org.apache.maven.artifact.Artifact;
import org.apache.maven.artifact.repository.ArtifactRepository;
+import org.apache.maven.model.Resource;
import org.apache.maven.project.MavenProject;
import org.apache.maven.reporting.AbstractMavenReport;
import org.apache.maven.reporting.MavenReportException;
+import org.apache.tapestry.ioc.internal.util.CollectionFactory;
import static org.apache.tapestry.ioc.internal.util.CollectionFactory.newList;
import static org.apache.tapestry.ioc.internal.util.CollectionFactory.newMap;
import org.apache.tapestry.ioc.internal.util.InternalUtils;
@@ -45,6 +47,15 @@
public class ComponentReport extends AbstractMavenReport
{
/**
+ * Subdirectory containing the component reference pages and index.
+ */
+ private static final String REFERENCE_DIR = "ref";
+
+ private final static String[] PARAMETER_HEADERS = {"Name", "Type", "Flags", "Default", "Default Prefix",
+ "Description"};
+
+
+ /**
* Identifies the application root package.
*
* @parameter
@@ -127,12 +138,12 @@
return "Component Reference";
}
+
public String getOutputName()
{
- return "component-parameters";
+ return REFERENCE_DIR + "/index";
}
- private static final String REFERENCE_DIR = "ref";
/**
* Generates the report; this consist of the index page
@@ -145,7 +156,7 @@
{
Map<String, ClassDescription> descriptions = runJavadoc();
- getLog().info("Executing ComponentReport ...");
+ getLog().info("Generating reference pages ...");
try
{
@@ -153,6 +164,9 @@
refDir.mkdirs();
+
+ List<File> docSearchPath = createDocSearchPath();
+
Sink sink = getSink();
sink.section1();
@@ -165,12 +179,12 @@
{
sink.listItem();
- sink.link(REFERENCE_DIR + "/" + className + ".html");
+ sink.link(className + ".html");
sink.text(className);
sink.link_();
- writeClassDescription(descriptions, refDir, sink, className);
+ writeClassDescription(descriptions, refDir, docSearchPath, sink, className);
sink.listItem_();
@@ -185,8 +199,28 @@
}
}
- private void writeClassDescription(Map<String, ClassDescription> descriptions, File refDir, Sink sink,
- String className) throws Exception
+ private List<File> createDocSearchPath()
+ {
+ List<File> result = CollectionFactory.newList();
+
+ for (String sourceRoot : (List<String>) project.getCompileSourceRoots())
+ {
+ result.add(new File(sourceRoot));
+ }
+
+
+ for (Resource r : (List<Resource>) project.getResources())
+ {
+ String dir = r.getDirectory();
+
+ result.add(new File(dir));
+ }
+
+ return result;
+ }
+
+ private void writeClassDescription(Map<String, ClassDescription> descriptions, File refDir,
+ List<File> docSearchPath, Sink sink, String className) throws Exception
{
Element root = new Element("document");
@@ -211,34 +245,21 @@
Collections.reverse(parents);
-
- Element properties = new Element("properties");
- root.appendChild(properties);
-
- Element title = new Element("title");
- properties.appendChild(title);
-
- title.appendChild(String.format("Component Reference: %s", className));
-
// XOM is pretty verbose; it really needs a builder/fluent interface.
+ Element properties = addChild(root, "properties");
+ addChild(properties, "title", String.format("Component Reference: %s", className));
+
Element body = new Element("body");
root.appendChild(body);
-
Element section = addSection(body, className);
- Element para = new Element("p");
- section.appendChild(para);
- para.appendChild(cd.getDescription());
-
- para = new Element("p");
- section.appendChild(para);
+ addChild(section, "p", cd.getDescription());
String javadocURL = String.format("../%s/%s.html", apidocs, className.replace('.', '/'));
- addLink(para, javadocURL, "[JavaDoc]");
-
+ addLink(addChild(section, "p"), javadocURL, "[JavaDoc]");
if (!parents.isEmpty())
{
@@ -247,16 +268,17 @@
for (String name : parents)
{
- Element ul = new Element("ul");
- container.appendChild(ul);
- Element li = new Element("li");
- ul.appendChild(li);
+ Element ul = addChild(container, "ul");
+
+ Element li = addChild(ul, "li");
addLink(li, name + ".html", name);
container = li;
}
+
+ addChild(addChild(container, "ul"), "li", className);
}
@@ -272,25 +294,20 @@
table.appendChild(headerRow);
for (String header : PARAMETER_HEADERS)
- {
addChild(headerRow, "th", header);
- }
-
List<String> flags = newList();
-
for (String name : InternalUtils.sortedKeys(parameters))
{
-
ParameterDescription pd = parameters.get(name);
flags.clear();
+
if (pd.getRequired()) flags.add("Required");
if (!pd.getCache()) flags.add("NOT Cached");
-
Element row = new Element("tr");
table.appendChild(row);
@@ -304,10 +321,18 @@
}
+ addExternalDocumentation(body, docSearchPath, className);
+
+ addChild(body, "hr");
+
+ addLink(addChild(body, "p"), "index.html", "Back to index");
+
Document document = new Document(root);
File outputFile = new File(refDir, className + ".xml");
+ getLog().info(String.format("Writing %s", outputFile));
+
FileOutputStream fos = new FileOutputStream(outputFile);
BufferedOutputStream bos = new BufferedOutputStream(fos);
@@ -319,8 +344,40 @@
writer.close();
}
- private final static String[] PARAMETER_HEADERS = {"Name", "Type", "Flags", "Default", "Default Prefix",
- "Description"};
+ private void addExternalDocumentation(Element body, List<File> docSearchPath, String className)
+ throws ParsingException, IOException
+ {
+ String pathExtension = className.replace(".", SystemUtils.FILE_SEPARATOR) + ".xdoc";
+
+ for (File path : docSearchPath)
+ {
+ File file = new File(path, pathExtension);
+
+ getLog().debug(String.format("Checking for %s", file));
+
+ if (!file.exists()) continue;
+
+ getLog().info(String.format("Reading extra documentation from %s", file));
+
+ Builder builder = new Builder();
+
+ Document doc = builder.build(file);
+
+ // Transfer the nodes inside document/body into our body
+
+ Element incomingBody = doc.getRootElement().getFirstChildElement("body");
+
+ for (int i = 0; i < incomingBody.getChildCount(); i++)
+ {
+ Node incoming = incomingBody.getChild(i).copy();
+
+ body.appendChild(incoming);
+ }
+
+ return;
+ }
+ }
+
private Map<String, ClassDescription> runJavadoc() throws MavenReportException
{
@@ -602,14 +659,19 @@
private Element addLink(Element container, String URL, String text)
{
- Element link = new Element("a");
- container.appendChild(link);
+ Element link = addChild(container, "a", text);
link.addAttribute(new Attribute("href", URL));
- link.appendChild(text);
-
return link;
+ }
+
+ private Element addChild(Element container, String elementName)
+ {
+ Element child = new Element(elementName);
+ container.appendChild(child);
+
+ return child;
}
private Element addChild(Element container, String elementName, String text)
Copied: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentEventLink.java (from r614985, tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentActionLink.java)
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentEventLink.java?p2=tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentEventLink.java&p1=tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentActionLink.java&r1=614985&r2=616528&rev=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentActionLink.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/base/AbstractComponentEventLink.java Tue Jan 29 13:37:18 2008
@@ -22,7 +22,11 @@
import java.util.List;
-public abstract class AbstractComponentActionLink extends AbstractLink
+/**
+ * Base class for link-generating components that are based on a component event request. Such events have an event
+ * context and may also update a {@link org.apache.tapestry.corelib.components.Zone}.
+ */
+public abstract class AbstractComponentEventLink extends AbstractLink
{
/**
* The context for the link (optional parameter). This list of values will be converted into strings and included in
@@ -33,7 +37,7 @@
private List<?> _context;
/**
- * Binding zone turns the link into a an Ajax control that causes the related zone to be updated.
+ * Binding the zone parameter turns the link into a an Ajax control that causes the related zone to be updated.
*/
@Parameter(defaultPrefix = TapestryConstants.LITERAL_BINDING_PREFIX)
private String _zone;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/ActionLink.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/ActionLink.java?rev=616528&r1=616527&r2=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/ActionLink.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/ActionLink.java Tue Jan 29 13:37:18 2008
@@ -17,13 +17,13 @@
import org.apache.tapestry.ComponentResources;
import org.apache.tapestry.Link;
import static org.apache.tapestry.TapestryConstants.ACTION_EVENT;
-import org.apache.tapestry.corelib.base.AbstractComponentActionLink;
+import org.apache.tapestry.corelib.base.AbstractComponentEventLink;
import org.apache.tapestry.ioc.annotations.Inject;
/**
* Component that triggers an action on the server with a subsequent full page refresh.
*/
-public class ActionLink extends AbstractComponentActionLink
+public class ActionLink extends AbstractComponentEventLink
{
@Inject
private ComponentResources _resources;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanDisplay.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanDisplay.java?rev=616528&r1=616527&r2=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanDisplay.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanDisplay.java Tue Jan 29 13:37:18 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,48 +26,51 @@
import org.apache.tapestry.services.ComponentDefaultProvider;
/**
- * Used to display the properties of a bean, using an underlying {@link BeanModel}. The output is a
- * series of <div> elements for the property names and property values.
+ * Used to display the properties of a bean, using an underlying {@link BeanModel}. The output is a series of
+ * <div> elements for the property names and property values. Only properties that have a known data type are
+ * displayed.
+ *
+ * @see org.apache.tapestry.beaneditor.DataType
+ * @see BeanModel
*/
@SupportsInformalParameters
public class BeanDisplay
{
/**
- * The object to be rendered; if not explicitly bound, a default binding to a property whose
- * name matches this component's id will be used.
+ * The object to be rendered; if not explicitly bound, a default binding to a property whose name matches this
+ * component's id will be used.
*/
@Parameter(required = true)
private Object _object;
/**
- * The model that identifies the parameters to be displayed, their order, and every other
- * aspect. If not specified, a default bean model will be created from the type of the object
- * bound to the object parameter.
+ * The model that identifies the parameters to be displayed, their order, and every other aspect. If not specified,
+ * a default bean model will be created from the type of the object bound to the object parameter.
*/
@Parameter
private BeanModel _model;
/**
- * A comma-separated list of property names to be removed from the {@link BeanModel}. The names
- * are case-insensitive.
+ * A comma-separated list of property names to be removed from the {@link BeanModel}. The names are
+ * case-insensitive.
*/
@Parameter(defaultPrefix = "literal")
private String _remove;
/**
- * A comma-separated list of property names indicating the order in which the properties should
- * be presented. The names are case insensitive. Any properties not indicated in the list will
- * be appended to the end of the display order.
+ * A comma-separated list of property names indicating the order in which the properties should be presented. The
+ * names are case insensitive. Any properties not indicated in the list will be appended to the end of the display
+ * order.
*/
@Parameter(defaultPrefix = "literal")
private String _reorder;
/**
- * Where to search for local overrides of property display blocks as block parameters. Further,
- * the container of the overrides is used as the source for overridden validation messages. This
- * is normally the component itself, but when the component is used within a BeanEditForm, it
- * will be the BeanEditForm's block parameter that will be searched.
+ * Where to search for local overrides of property display blocks as block parameters. Further, the container of the
+ * overrides is used as the source for overridden validation messages. This is normally the component itself, but
+ * when the component is used within a BeanEditForm, it will be the BeanEditForm's block parameter that will be
+ * searched.
*/
@Parameter(value = "componentResources")
private ComponentResources _overrides;
@@ -98,9 +101,8 @@
void setupRender()
{
- if (_model == null)
- _model = _modelSource.create(_object.getClass(), false, _overrides
- .getContainerResources());
+ if (_model == null) _model = _modelSource.create(_object.getClass(), false, _overrides
+ .getContainerResources());
if (_remove != null) BeanModelUtils.remove(_model, _remove);
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanEditForm.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanEditForm.java?rev=616528&r1=616527&r2=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanEditForm.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/BeanEditForm.java Tue Jan 29 13:37:18 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,20 +26,16 @@
import org.apache.tapestry.services.ComponentDefaultProvider;
/**
- * A component that creates an entire form editing the properties of a particular bean. Inspired by
- * <a href="http://www.trailsframework.org/">Trails</a> and <a
- * href="http://beanform.sourceforge.net/">BeanForm</a> (both for Tapestry 4). Generates a simple
- * UI for editing the properties of a JavaBean, with the flavor of UI for each property (text field,
- * checkbox, drop down list) determined from the property type, and the order and validation for the
- * properties determined from annotations on the property's getter and setter methods.
+ * A component that creates an entire form editing the properties of a particular bean. Inspired by <a
+ * href="http://www.trailsframework.org/">Trails</a> and <a href="http://beanform.sourceforge.net/">BeanForm</a> (both
+ * for Tapestry 4). Generates a simple UI for editing the properties of a JavaBean, with the flavor of UI for each
+ * property (text field, checkbox, drop down list) determined from the property type, and the order and validation for
+ * the properties determined from annotations on the property's getter and setter methods.
* <p/>
- * You may add <t:parameter>s to the component; when the name matches (case insensitive) the
- * name of a property, then the corresponding Block is renderered, rather than any of the built in
- * property editor blocks. This allows you to override specific properties with your own customized
- * UI, for cases where the default UI is insufficient, or no built-in editor type is appropriate.
- * <p/>
- * This component is likely to change more than any other thing in Tapestry! What's available now is
- * a very limited preview of its eventual functionality.
+ * You may add <t:parameter>s to the component; when the name matches (case insensitive) the name of a property,
+ * then the corresponding Block is renderered, rather than any of the built in property editor blocks. This allows you
+ * to override specific properties with your own customized UI, for cases where the default UI is insufficient, or no
+ * built-in editor type is appropriate.
*
* @see BeanModel
* @see BeanModelSource
@@ -55,27 +51,28 @@
private String _submitLabel;
/**
- * The object to be edited by the BeanEditor. This will be read when the component renders and
- * updated when the form for the component is submitted. Typically, the container will listen
- * for a "prepare" event, in order to ensure that a non-null value is ready to be read or
- * updated.
+ * The object to be edited by the BeanEditor. This will be read when the component renders and updated when the form
+ * for the component is submitted. Typically, the container will listen for a "prepare" event, in order to ensure
+ * that a non-null value is ready to be read or updated. Often, the BeanEditForm can create the object as needed
+ * (assuming a public, no arguments constructor). The object property defaults to a property with the same name as
+ * the component id.
*/
@SuppressWarnings("unused")
@Parameter(required = true)
private Object _object;
/**
- * A comma-separated list of property names to be removed from the {@link BeanModel}. The names
- * are case-insensitive.
+ * A comma-separated list of property names to be removed from the {@link BeanModel}. The names are
+ * case-insensitive.
*/
@SuppressWarnings("unused")
@Parameter(defaultPrefix = "literal")
private String _remove;
/**
- * A comma-separated list of property names indicating the order in which the properties should
- * be presented. The names are case insensitive. Any properties not indicated in the list will
- * be appended to the end of the display order.
+ * A comma-separated list of property names indicating the order in which the properties should be presented. The
+ * names are case insensitive. Any properties not indicated in the list will be appended to the end of the display
+ * order.
*/
@SuppressWarnings("unused")
@Parameter(defaultPrefix = "literal")
@@ -86,15 +83,14 @@
*/
@SuppressWarnings("unused")
@Parameter
- private boolean _clientValidation;
+ private boolean _clientValidation = true;
@Component(parameters = "clientValidation=inherit:clientValidation")
private Form _form;
/**
- * The model that identifies the parameters to be edited, their order, and every other aspect.
- * If not specified, a default bean model will be created from the type of the object bound to
- * the object parameter.
+ * The model that identifies the parameters to be edited, their order, and every other aspect. If not specified, a
+ * default bean model will be created from the type of the object bound to the object parameter.
*/
@SuppressWarnings("unused")
@Parameter
@@ -136,10 +132,9 @@
}
catch (Exception ex)
{
- throw new TapestryException(InternalMessages.failureInstantiatingObject(
- type,
- _resources.getCompleteId(),
- ex), _resources.getLocation(), ex);
+ throw new TapestryException(
+ InternalMessages.failureInstantiatingObject(type, _resources.getCompleteId(), ex),
+ _resources.getLocation(), ex);
}
}
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/EventLink.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/EventLink.java?rev=616528&r1=616527&r2=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/EventLink.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/corelib/components/EventLink.java Tue Jan 29 13:37:18 2008
@@ -18,7 +18,7 @@
import org.apache.tapestry.Link;
import org.apache.tapestry.TapestryConstants;
import org.apache.tapestry.annotations.Parameter;
-import org.apache.tapestry.corelib.base.AbstractComponentActionLink;
+import org.apache.tapestry.corelib.base.AbstractComponentEventLink;
import org.apache.tapestry.ioc.annotations.Inject;
/**
@@ -31,15 +31,20 @@
* This allows slightly shorter URLs but also allows multiple components within the same container to generate identical
* URLs for common actions.
*/
-public class EventLink extends AbstractComponentActionLink
+public class EventLink extends AbstractComponentEventLink
{
/**
- * The name of the event to be triggered in the parent component. An {@link org.apache.tapestry.corelib.components.ActionLink}
- * triggers an "action" event on itself, and EventLink component triggers any arbitrary event on <em>its
- * container</em>.
+ * The name of the event to be triggered in the parent component. Defaults to the id of the component. An {@link
+ * org.apache.tapestry.corelib.components.ActionLink} triggers an "action" event on itself, and EventLink component
+ * triggers any arbitrary event on <em>its container</em>.
*/
- @Parameter(required = true, defaultPrefix = TapestryConstants.LITERAL_BINDING_PREFIX)
+ @Parameter(defaultPrefix = TapestryConstants.LITERAL_BINDING_PREFIX)
private String _event;
+
+ String defaultEvent()
+ {
+ return _resources.getId();
+ }
@Inject
private ComponentResources _resources;
Modified: tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/BeanModelSource.java
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/BeanModelSource.java?rev=616528&r1=616527&r2=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/BeanModelSource.java (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/java/org/apache/tapestry/services/BeanModelSource.java Tue Jan 29 13:37:18 2008
@@ -19,24 +19,21 @@
import org.apache.tapestry.beaneditor.OrderBefore;
/**
- * Used by a component to create a default {@link BeanModel} for a particular bean class. Also
- * provides support to the model by generating validation information for individual fields.
+ * Used by a component to create a default {@link BeanModel} for a particular bean class. Also provides support to the
+ * model by generating validation information for individual fields.
* <p/>
- * <p/>
- * BeanModels are the basis for the {@link org.apache.tapestry.corelib.components.BeanEditor} and
- * {@link org.apache.tapestry.corelib.components.Grid} comopnents.
+ * BeanModels are the basis for the {@link org.apache.tapestry.corelib.components.BeanEditor} and {@link
+ * org.apache.tapestry.corelib.components.Grid} comopnents.
*/
public interface BeanModelSource
{
/**
- * Creates a new model used for editing the indicated bean class. The model will represent all
- * read/write properties of the bean. The order of the properties is defined by the
- * {@link OrderBefore} annotation on the getter or setter methods. The labels for the properties are
- * derived from the property names, but if the component's message catalog has keys of the form
- * <code>propertyName-label</code>, then those will be used instead.
+ * Creates a new model used for editing the indicated bean class. The model will represent all read/write properties
+ * of the bean. The order of the properties is defined by the {@link OrderBefore} annotation on the getter or setter
+ * methods. The labels for the properties are derived from the property names, but if the component's message
+ * catalog has keys of the form <code>propertyName-label</code>, then those will be used instead.
* <p/>
- * Models are <em>mutable</em>, so they are not cached, a fresh instance is created each
- * time.
+ * Models are <em>mutable</em>, so they are not cached, a fresh instance is created each time.
*
* @param beanClass class of object to be edited
* @param filterReadOnlyProperties if true, then properties that are read-only will be skipped (leaving only
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/ActionLink.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/ActionLink.xdoc?rev=616528&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/ActionLink.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/ActionLink.xdoc Tue Jan 29 13:37:18 2008
@@ -0,0 +1,141 @@
+<document>
+ <body>
+
+ <section name="Examples">
+
+ <p>
+ In this example, we are showing part of a page to view and Account object, with an option to
+ delete the Account.
+ </p>
+
+
+ <subsection name="Account.java">
+ <source><![CDATA[
+public class Account
+{
+ private long _id;
+
+ private String _userName;
+
+ // etc., etc., ...
+
+ // Getters and setters omitted ...
+
+}]]></source>
+ </subsection>
+
+ <subsection name="ViewAccount.tml">
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+ <h1>View Account #${account.id}</h1>
+
+ <t:beandisplay object="account"/>
+
+ <p>
+ [<t:actionlink t:id="delete" context="account.id">delete</t:actionlink>
+ </p>
+ </body>
+</html>
+]]></source>
+
+ <p>
+ We store the account's id as
+ <em>event context</em>
+ inside the URL. The accounts id will
+ be part of the URL and will be accessible when the event request is later triggered.
+ </p>
+
+
+ </subsection>
+
+ <subsection name="ViewAccount.java">
+ <source><![CDATA[
+public class ViewAccount
+{
+ @Persist
+ private Account _account;
+
+ @InjectPage
+ private AccountsSummary _accountsSummaryPage;
+
+ @Inject
+ private AccountDAO _accountDAO;
+
+ public Account getAccount() { return _account; }
+
+ Object onActionFromDelete(long accountId)
+ {
+ _accountDAO.delete(accountId);
+
+ _accountsSummaryPage.setMessage(String.format("Account #%d has been deleted.", accountId));
+
+ return _accountsSummaryPage;
+ }
+}
+]]></source>
+
+ <p>
+ The ActionLink component triggers an "action" event, which is matched by the
+ onActionFromDelete() method. A real application might have other action links on the page, for (say)
+ creating new accounts or other operations, thus we use the component's id ("delete")
+ to ensure that the method is only invoked under the expected circumstances.
+ </p>
+
+ <p>
+ Notice how the context (from when the link was rendered) now becomes parameters
+ to the event handler method.
+ </p>
+
+ <p>
+ The AccountDAO (data access object) service is responsible for the work, we
+ then set a message on another page (the field for this message should be persistent) and return
+ the page. Tapestry will send a redirect request to the client to display the page.
+ </p>
+
+
+ </subsection>
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ Rarely, you might need to pass more information in the context. For example, perhaps
+ account id is not enought to uniquely identify the Account object in question - hypothetically,
+ you may need to include a componany id as well as the account id. You can
+ build an object array:
+ </p>
+
+ <source><![CDATA[
+ public Object[] getAccountContext()
+ {
+ return new Object[] { account.companyId, account.id };
+ }
+
+ Object onActionFromDelete(long companyId, long accountId)
+ {
+ _accountDAO.delete(companyId, accountId);
+
+ _accountsSummaryPage.setMessage(String.format("Account #%d has been deleted.", accountId));
+
+ return _accountsSummaryPage;
+ }]]></source>
+
+ <p>
+ In the template, this would be referenced as:
+ </p>
+ <source><![CDATA[
+ <p>
+ [<t:actionlink t:id="delete" context="accountContext">delete</t:actionlink>
+ </p>]]></source>
+
+ <p>
+ This highlights the use of the component class: any complicated processing should be offloaded
+ out of the template and into the class.
+ </p>
+
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanDisplay.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanDisplay.xdoc?rev=616528&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanDisplay.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanDisplay.xdoc Tue Jan 29 13:37:18 2008
@@ -0,0 +1,135 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ The bean to display will be a property of the containing page. In this example we are making
+ the bean a persistent property, but there are other options. Presumably, some other page
+ obtains the bean and invokes the setBean() method.
+ </p>
+
+ <p>
+ You may pass override parameters for specific properties, in which case you have control
+ over how that property will be rendered. As an example, we'll render the lastName as upper-case.
+ </p>
+
+ <subsection name="MyBean.java">
+ <source><![CDATA[
+public class MyBean
+{
+ private long _id;
+
+ private String _firstName;
+
+ private String _lastName;
+
+ private int _age;
+
+ public long getId() { return _id; }
+
+ @NonVisual
+ public void setId(long id) { _id = id; }
+
+ public String getFirstName() { return _firstName; }
+
+ public void setFirstName(String firstName) { _firstName = firstName; }
+
+ public String getLastName() { return _lastName; }
+
+ public void setLastName(String lastName) { _lastName = lastName; }
+
+ public int getAge() { return _age; }
+
+ public void setAge(int age) { _age = age; }
+}]]></source>
+
+ <p>The @NonVisual annotation prevents the id from being displayed.</p>
+
+ </subsection>
+
+ <subsection name="MyPage.java">
+ <source><![CDATA[
+public class MyPage
+{
+ @Persist
+ private MyBean _bean;
+
+ public MyBean getBean()
+ {
+ return _bean;
+ }
+
+ public void setBean(MyBean bean)
+ {
+ _bean = bean;
+ }
+}]]></source>
+
+
+ </subsection>
+
+
+ <subsection name="MyPage.tml">
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+ <h1>My Bean</h1>
+
+ <t:beandisplay object="bean">
+ <t:parameter name="lastname">
+ ${bean.lastname.toUpperCase()}
+ </t:parameter>
+ </t:beandisplay>
+ </body>
+</html>
+]]></source>
+
+ <p>
+ The
+ <code><![CDATA[<t:parameter>]]></code>
+ element
+ is an
+ <em>override</em>
+ for the property. The name is
+ matched against a property of the bean.
+ </p>
+
+ <p>
+ Here we are leveraging the ability to invoke methods as part of a property expression.
+ We are also highlighting Tapestry's case insensitivity ("lastname" vs. "lastName"), though
+ that does not yet apply to method names of beans.
+ </p>
+
+ </subsection>
+
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ You can re-order the properties using the reorder parameter:
+ </p>
+
+ <source><![CDATA[<t:beandisplay object="bean" reorder="lastname,firstname"/>]]></source>
+
+ <p>
+ You can accomplish the same thing by changing the order of the
+ getter methods in the bean class (that sets the default order).
+ </p>
+
+ <p>
+ You can also remove properties with the remove parameter, which is equivalent to the
+ @NonVisual annotation.
+ </p>
+
+ <p>
+ You might find
+ <code><![CDATA[<t:beandisplay object="this"/>]]></code>
+ useful on occasion. It will display all the properties of the current page.
+ </p>
+
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanEditForm.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanEditForm.xdoc?rev=616528&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanEditForm.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/BeanEditForm.xdoc Tue Jan 29 13:37:18 2008
@@ -0,0 +1,212 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ The bean to edit will be a property of the containing page.
+ </p>
+
+ <p>
+ You may pass override parameters for specific properties, in which case you have control
+ over how that property will be editted.
+ </p>
+
+ <subsection name="User.java">
+ <source><![CDATA[
+public class User
+{
+ private long _id;
+
+ private String _firstName;
+
+ private String _lastName;
+
+ private int _age;
+
+ public long getId() { return _id; }
+
+ @NonVisual
+ public void setId(long id) { _id = id; }
+
+ public String getFirstName() { return _firstName; }
+
+ public void setFirstName(String firstName) { _firstName = firstName; }
+
+ public String getLastName() { return _lastName; }
+
+ public void setLastName(String lastName) { _lastName = lastName; }
+
+ public int getAge() { return _age; }
+
+ public void setAge(int age) { _age = age; }
+}]]></source>
+
+ <p>The @NonVisual annotation prevents the id from being displayed.</p>
+
+ </subsection>
+
+
+ <subsection name="CreateUser.tml">
+
+ <p>
+ We are overriding the editor for the age property with a Slider
+ component (rather than the default, which would be a numeric text field).
+ Alas this Slider component does not exist.
+ </p>
+
+ <source><![CDATA[
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_0_0.xsd">
+ <body>
+ <h1>Create New User</h1>
+
+ <t:beaneditform t:id="user" submitlabel="message:create-user">
+ <t:parameter name="age">
+ <t:label for="age"/>
+ <t:slider min="18" max="99" t:id="age" value="user.age"/>
+ </t:parameter>
+ </t:beaneditform>
+ </body>
+</html>
+]]></source>
+
+ <p>
+ Nominally, we should have to bind the object parameterof the BeanEditForm component. However, as
+ a convienience, Tapestry has defaulted the object parameter
+ based on the component id. This works because the CreateUser class
+ includes a property named "user", which matches the BeanEditForm component's id.
+
+ </p>
+
+ <p>
+ When the object to be editted is not a direct property of the page,
+ it will be necessary to bind the object parameter explicitly. For example,
+ <code>object="registration.address"</code>
+ to create or edit the address
+ property of the page's registration property. Component ids may not contain periods,
+ so there's no way to specify this without the object parameter. A best practice is to still
+ explicitly set the component's id, thus:
+ <code><![CDATA[<t:beaneditform t:id="address" object="registration.address"/>]]></code>
+ </p>
+
+ <p>
+ The
+ <code><![CDATA[<t:parameter>]]></code>
+ element
+ is an
+ <em>override</em>
+ for the property. The name is
+ matched against a property of the bean. We need to provide a Label and an appropriate
+ editor component (here, the hypothetical Slider component).
+ </p>
+
+ </subsection>
+
+ <subsection name="CreateUser.properties">
+
+ <source><![CDATA[
+create-user=Create New User
+firstname-label=Given Name
+lastname-label=Family Name]]></source>
+
+ <p>
+ We are using the page's message catalog to supply a messages. Externalizing such messages
+ make them easier to work with, especially for an application that may be localized.
+ </p>
+
+ <p>
+ The
+ <code>create-user</code>
+ key is explicitly referenced (<code>submitlabel="message:create-user"</code>).
+ This becomes the label on the submit button for the generated form.
+ </p>
+
+ <p>
+ The two label keys will be picked up and used as the labels for the corresponding properties
+ (in both the rendered <label> elements, and in any error messages).
+ </p>
+
+ <p>
+ In many cases, common entries can be moved up to an application-wide message catalog. In that case,
+ the page's own message catalog becomes a local override.
+ </p>
+
+
+ </subsection>
+
+ <subsection name="CreateUser.java">
+ <source><![CDATA[
+public class CreateUser
+{
+ @Persist
+ private User _user;
+
+ @Inject
+ private UserDAO _userDAO;
+
+ public User getUser()
+ {
+ return _user;
+ }
+
+ public void setUser(User user)
+ {
+ _user = user;
+ }
+
+ Object onSuccess()
+ {
+ _userDAO.add(_user);
+
+ return UserAdmin.class;
+ }
+}]]></source>
+
+
+ <p>
+ Notice that we don't instantiate the User object ourselves; instead we let the BeanEditForm
+ component
+ do that for us. It's capable of doing so because the User class has the default public no arguments
+ constructor.
+ </p>
+
+ <p>
+ The onSuccess() method is invoked when the form is submitted with no validation errors (although
+ client validation is enabled by default, server-side validation is
+ <em>always</em>
+ enforced).
+ The UserDAO service is used to add the new user.
+ </p>
+
+ <p>
+ Returning a class from an event handler method (<code>UserAdmin.class</code>) will
+ activate the indicated page as the response page. As always, a redirect to to the response page is
+ sent to the client.
+ </p>
+
+ </subsection>
+
+ </section>
+
+ <section name="Notes">
+
+ <p>
+ You can re-order the properties using the reorder parameter:
+ </p>
+
+ <source><![CDATA[<t:beaneditform t:id="user" reorder="lastname,firstname"/>]]></source>
+
+ <p>
+ You can accomplish the same thing by changing the order of the
+ getter methods in the bean class (that sets the default order).
+ </p>
+
+ <p>
+ You can also remove properties with the remove parameter, which is equivalent to the
+ @NonVisual annotation.
+ </p>
+
+
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Added: tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/PageLink.xdoc
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/PageLink.xdoc?rev=616528&view=auto
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/PageLink.xdoc (added)
+++ tapestry/tapestry5/trunk/tapestry-core/src/main/resources/org/apache/tapestry/corelib/components/PageLink.xdoc Tue Jan 29 13:37:18 2008
@@ -0,0 +1,18 @@
+<document>
+ <body>
+ <section name="Examples">
+
+ <p>
+ This will be a set of examples about PageLink.
+ </p>
+
+ </section>
+
+ <section name="Notes">
+ <p>
+ This will be more notes about PageLink.
+ </p>
+ </section>
+
+ </body>
+</document>
\ No newline at end of file
Modified: tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml
URL: http://svn.apache.org/viewvc/tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml?rev=616528&r1=616527&r2=616528&view=diff
==============================================================================
--- tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml (original)
+++ tapestry/tapestry5/trunk/tapestry-core/src/site/site.xml Tue Jan 29 13:37:18 2008
@@ -1,20 +1,20 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
-<!--
- Copyright 2006, 2007 The Apache Software Foundation
-
- Licensed under the Apache License, Version 2.0 (the "License");
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
--->
-
+<!--
+ Copyright 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.
+ 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.
+-->
+
<project name="Tapestry Core">
<bannerLeft>
<name>Tapestry 5</name>
@@ -48,7 +48,7 @@
-->
<menu name="Tapestry Core">
<item name="Introduction" href="/index.html"/>
- <item name="Component Reference" href="component-parameters.html"/>
+ <item name="Component Reference" href="ref/index.html"/>
<item name="Upgrade from Tapestry 4" href="/upgrade.html"/>
<item name="Download" href="http://tapestry.apache.org/download.html"/>
</menu>