You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bo...@apache.org on 2014/03/10 02:07:52 UTC
git commit: Fixed TAP5-2298 ("Any" component lacks any useful
documentation)
Repository: tapestry-5
Updated Branches:
refs/heads/master 01a478c12 -> 88f6a1922
Fixed TAP5-2298 ("Any" component lacks any useful documentation)
Project: http://git-wip-us.apache.org/repos/asf/tapestry-5/repo
Commit: http://git-wip-us.apache.org/repos/asf/tapestry-5/commit/88f6a192
Tree: http://git-wip-us.apache.org/repos/asf/tapestry-5/tree/88f6a192
Diff: http://git-wip-us.apache.org/repos/asf/tapestry-5/diff/88f6a192
Branch: refs/heads/master
Commit: 88f6a1922d432eea768b67730a1a3829d69b7e36
Parents: 01a478c
Author: Bob Harner <bo...@apache.org>
Authored: Sun Mar 9 20:09:40 2014 -0400
Committer: Bob Harner <bo...@apache.org>
Committed: Sun Mar 9 21:03:11 2014 -0400
----------------------------------------------------------------------
.../tapestry5/corelib/components/Any.java | 60 +++++++++++++++++++-
.../corelib/mixins/RenderClientId.java | 9 ++-
2 files changed, 66 insertions(+), 3 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/88f6a192/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Any.java
----------------------------------------------------------------------
diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Any.java b/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Any.java
index d68f896..3f7b359 100644
--- a/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Any.java
+++ b/tapestry-core/src/main/java/org/apache/tapestry5/corelib/components/Any.java
@@ -22,7 +22,60 @@ import org.apache.tapestry5.ioc.annotations.Inject;
import org.apache.tapestry5.services.javascript.JavaScriptSupport;
/**
- * Renders an arbitrary element including informal parameters.
+ * Turns any arbitrary (X)HTML element into a component. The element's start and end
+ * tags are rendered, including any informal parameters and possibly an id
+ * attribute. The id is provided by {@link JavaScriptSupport#allocateClientId(String)}
+ * (so it will be unique on the client side) and is available after the component
+ * renders using {@link #getClientId()}. The Any component has no template of its
+ * own but does render its body, if any.
+ * <p>
+ * Some common uses are:
+ * <ul>
+ *
+ * <li>Applying a mixin to an ordinary HTML element. For example,
+ * the following turns an <i>img</i> element into a component that, via the
+ * {@link org.apache.tapestry5.corelib.mixins.RenderNotification RenderNotification} mixin, triggers event
+ * notifications when it enters the BeginRender and EndRender phases:
+ *
+ * <pre><img t:type="any" t:mixins="renderNotification"></pre>
+ *
+ * And the following renders a <i>td</i> element with the
+ * {@link org.apache.tapestry5.corelib.mixins.NotEmpty NotEmpty} mixin to ensure
+ * that a non-breaking space (&nbsp;) is rendered if the td element would
+ * otherwise be empty:
+ *
+ * <pre><td t:type="any" t:mixins="NotEmpty"></pre>
+ * </li>
+ *
+ * <li>Providing a dynamically-generated client ID for an HTML element
+ * in a component rendered in a loop or zone (or more than once in a page), for
+ * use from JavaScript. (The component class will typically use
+ * {@link org.apache.tapestry5.annotations.InjectComponent InjectComponent}
+ * to get the component, then call {@link #getClientId()} to retrieve the ID.)
+ *
+ * <pre><table t:type="any" id="clientId"></pre>
+ *
+ * As an alternative to calling getClientId, you can use the
+ * {@link org.apache.tapestry5.corelib.mixins.RenderClientId RenderClientId}
+ * mixin to force the id attribute to appear in the HTML:
+ *
+ * <pre><table t:type="any" t:mixins="RenderClientId"></pre>
+ * </li>
+ *
+ * <li>Dynamically outputting a different HTML element depending on
+ * the string value of a property. For example, the following renders an element
+ * identified by the "element" property in the corresponding component class:
+ *
+ * <pre><t:any element="prop:element" ... ></pre>
+ * </li>
+ *
+ * <li>As the base component for a new custom component, especially convenient
+ * when the new component should support informal parameters or needs a dynamically
+ * generated client ID:
+ *
+ * <pre>public class MyComponent extends Any { ... }
+ * </li>
+ * </ul>
*
* @tapestrydoc
*/
@@ -30,7 +83,10 @@ import org.apache.tapestry5.services.javascript.JavaScriptSupport;
public class Any implements ClientElement
{
/**
- * The element to be rendered.
+ * The name of the element to be rendered, typically one of the standard (X)HTML
+ * elements, "div", "span", "a", etc., although practically any string will be
+ * accepted. The default comes from the template, or is "div" if the template
+ * does not specify an element.
*/
@Parameter(defaultPrefix = BindingConstants.LITERAL)
private String element;
http://git-wip-us.apache.org/repos/asf/tapestry-5/blob/88f6a192/tapestry-core/src/main/java/org/apache/tapestry5/corelib/mixins/RenderClientId.java
----------------------------------------------------------------------
diff --git a/tapestry-core/src/main/java/org/apache/tapestry5/corelib/mixins/RenderClientId.java b/tapestry-core/src/main/java/org/apache/tapestry5/corelib/mixins/RenderClientId.java
index 871367f..23a2fdb 100644
--- a/tapestry-core/src/main/java/org/apache/tapestry5/corelib/mixins/RenderClientId.java
+++ b/tapestry-core/src/main/java/org/apache/tapestry5/corelib/mixins/RenderClientId.java
@@ -19,7 +19,14 @@ import org.apache.tapestry5.annotations.AfterRender;
import org.apache.tapestry5.ClientElement;
/**
- * Forces a client element to render its client id by ensuring that {@link org.apache.tapestry5.ClientElement#getClientId()} is called.
+ * Forces a client element to render its client id by ensuring that
+ * {@link org.apache.tapestry5.ClientElement#getClientId() ClientElement#getClientId()}
+ * is called. This is sometimes needed because, by design, most components (those that
+ * implement {@link ClientElement}) only render a client-side ID if their getClientId
+ * method is called sometime during the server-side DOM render.
+ * <p/>
+ * See the {@link org.apache.tapestry5.corelib.components.Any Any} component
+ * for an example of use.
*
* @tapestrydoc
*/