You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2007/11/26 12:04:35 UTC
svn commit: r598223 - in /myfaces/tomahawk/trunk/core/src/main:
java/org/apache/myfaces/custom/aliasbean/
java/org/apache/myfaces/custom/buffer/ tld/ tld/tomahawk-entities/
Author: skitching
Date: Mon Nov 26 03:04:31 2007
New Revision: 598223
URL: http://svn.apache.org/viewvc?rev=598223&view=rev
Log:
Improve docs for AliasBean, AliasBeansScope, Buffer.
Modified:
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/Alias.java
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBean.java
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBeansScope.java
myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/buffer/Buffer.java
myfaces/tomahawk/trunk/core/src/main/tld/tomahawk-entities/tomahawk_buffer_attributes.xml
myfaces/tomahawk/trunk/core/src/main/tld/tomahawk.tld
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/Alias.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/Alias.java?rev=598223&r1=598222&r2=598223&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/Alias.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/Alias.java Mon Nov 26 03:04:31 2007
@@ -26,6 +26,13 @@
import org.apache.commons.logging.LogFactory;
/**
+ * A helper bean used by both AliasBean and AliasBeansScope components.
+ * <p>
+ * An Alias instance represents a single mapping from a "temporary" bean name
+ * to the real bean that temporary name should reference. When this alias
+ * is "activated" the temporary name is registered and when the alias is
+ * "deactivated" the temporary name is removed.
+ *
* @author Sylvain Vieujot (latest modification by $Author$)
* @version $Revision$ $Date$
*/
@@ -43,11 +50,22 @@
Alias(AliasBean aliasComponent){
this._aliasComponent = aliasComponent;
}
-
+
+ /**
+ * Define the temporary/transient name that will exist while this alias
+ * is "active" (in scope). This is usually a constant string.
+ */
void setAliasBeanExpression(String aliasBeanExpression){
this._aliasBeanExpression = aliasBeanExpression;
}
+ /**
+ * Define the object that will be referenced by the temporary/transient
+ * name while it exists.
+ * <p>
+ * This can be a constant, but is more usually an EL expression. The value is
+ * recalculated each time this alias is "activated".
+ */
void setValueExpression(String valueExpression){
this._valueExpression = valueExpression;
}
@@ -91,7 +109,10 @@
evaluatedExpression = valueVB.getValue(facesContext);
}
}
-
+
+ /**
+ * Activate this alias (ie create the temporary name).
+ */
void make(FacesContext facesContext){
if( _active )
return;
@@ -116,6 +137,9 @@
log.debug("makeAlias: " + _valueExpression + " = " + _aliasBeanExpression);
}
+ /**
+ * Deactivate this alias (ie remove the temporary name).
+ */
void remove(FacesContext facesContext){
_active = false;
if( evaluatedExpression == null )
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBean.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBean.java?rev=598223&r1=598222&r2=598223&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBean.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBean.java Mon Nov 26 03:04:31 2007
@@ -41,20 +41,28 @@
/**
* The aliasBean tag allows you to create a temporary name for a real bean.
* The temporary name exists (is visible) only to the children of the aliasBean.
- * <p/>
- * Suppose you have a block of components you use often but with
- * different beans. The aliasBean allows you to create a separate JSP
- * page (or equivalent) containing these beans, where the value-bindings
- * refer to some fictive bean name. Wherever you wish to use this block
- * you then declare an alias component mapping the fictive name to whatever
- * bean you really want to apply the block to, then use jsp:include
- * (or equivalent) to include the reusable block of components. This makes
- * it possible to have a library of reusable generic subforms.
- * <p/>
+ * <p>
+ * One use of this feature is to pass "parameters" from an including page to an
+ * included one. The included page can use any name it desires for beans it needs to
+ * reference, and the including page can then use aliasBean to make those names
+ * refer to the beans it wishes to "pass" as parameters.
+ * <p>
+ * Suppose you have a block of components you use often but with different beans. You
+ * can create a separate JSP page (or equivalent) containing these beans, where the
+ * value-bindings refer to some fictive bean name. Document these names as the required
+ * "parameters" for this JSP page. Wherever you wish to use this block you then declare
+ * an alias component mapping each of these "parameters" to whatever beans (or literal
+ * values) you really want to apply the block to, then use jsp:include (or equivalent)
+ * to include the reusable block of components.
+ * <p>
* Note, however, that AliasBean does not work for component bindings; JSF1.1
* just has no mechanism available to set up the alias during the "restore view"
* phase while the bindings of its children are being re-established, and then
* remove the alias after the child bindings are done.
+ * <p>
+ * As a special case, if this component's direct parent is an AliasBeansScope
+ * then the alias (temporary name) is active until the end of the parent
+ * component, rather than the end of this component.
*
* @author Sylvain Vieujot (latest modification by $Author$)
* @version $Revision$ $Date$
@@ -67,7 +75,11 @@
public static final String COMPONENT_FAMILY = "javax.faces.Data";
private Alias alias;
+
+ // Indicates whether withinScope has been initialised or not.
private boolean scopeSearched = false;
+
+ // True if this is a direct child of an AliasBeansScope component.
private boolean withinScope;
private transient FacesContext _context = null;
@@ -103,6 +115,11 @@
String valueExpression = alias.getValueExpression();
if (valueExpression != null)
return valueExpression;
+
+ // Normally, this component will have no value, because the setValue method always
+ // passes that data on to the alias instead. However it is possible for someone
+ // to use f:attribute (or other mechanism?) to set the value instead. So when the
+ // alias has no value, look for it there.
ValueBinding vb = getValueBinding("value");
return vb != null ? _ComponentUtils.getStringValue(getFacesContext(), vb) : null;
}
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBeansScope.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBeansScope.java?rev=598223&r1=598222&r2=598223&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBeansScope.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/aliasbean/AliasBeansScope.java Mon Nov 26 03:04:31 2007
@@ -38,6 +38,15 @@
/**
* Holds several aliases that are configured by aliasBean tags.
+ * <p>
+ * The aliasBean tag must enclose all the components that are within the scope
+ * of the alias. When multiple aliasas are defined, this makes the page structure
+ * very clumsy; for example defining 5 aliases means the content must be nested
+ * 5 indentation levels deep. This tag instead allows the content block to be
+ * wrapped in just one AliasBeansScope tag, and then have AliasBean tags with
+ * empty bodies added as direct children of this component. The scope of the AliasBean
+ * tag still starts when the tag begins, but instead of ending when the tag ends
+ * the scope of the nested AliasBean tags extends to the end of this component.
*
* @author Sylvain Vieujot (latest modification by $Author$)
* @version $Revision$ $Date$
Modified: myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/buffer/Buffer.java
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/buffer/Buffer.java?rev=598223&r1=598222&r2=598223&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/buffer/Buffer.java (original)
+++ myfaces/tomahawk/trunk/core/src/main/java/org/apache/myfaces/custom/buffer/Buffer.java Mon Nov 26 03:04:31 2007
@@ -23,6 +23,28 @@
import javax.faces.el.ValueBinding;
/**
+ * A component that renders its child components into an in-memory buffer rather than
+ * render them directly to the response stream.
+ * <p>
+ * Property "into" is an EL expression that specifies where to store a String holding
+ * the results of rendering all the children of this component; this is assigned to
+ * after rendering of this component (and its children) is complete.
+ * <p>
+ * Typically, an h:output tag is then used later in the same page to output the buffer
+ * contents.
+ * <p>
+ * This can be useful with JSF1.1/JSP2.0 to work around the well-known problem where
+ * on first render of a page, a component "A" cannot reference a component "B" which is
+ * defined later in the page because it has not yet been created. A solution is to define
+ * "B" before "A", but wrapped in a Buffer component. Component A can then be rendered
+ * and successfully reference "B" because it now exists. And later in the page, the buffer
+ * contents can then be output, preserving the original layout.
+ * <p>
+ * This can also be useful when rendering the same data block multiple times within a page.
+ * For example, a datatable can be rendered with a datascroller both before and after it;
+ * first render the table into a buffer B1, then render the datascroller into a buffer B2,
+ * then output buffers B2,B1,B2.
+ *
* @author Sylvain Vieujot (latest modification by $Author$)
* @version $Revision$ $Date$
*/
Modified: myfaces/tomahawk/trunk/core/src/main/tld/tomahawk-entities/tomahawk_buffer_attributes.xml
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/tld/tomahawk-entities/tomahawk_buffer_attributes.xml?rev=598223&r1=598222&r2=598223&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/tld/tomahawk-entities/tomahawk_buffer_attributes.xml (original)
+++ myfaces/tomahawk/trunk/core/src/main/tld/tomahawk-entities/tomahawk_buffer_attributes.xml Mon Nov 26 03:04:31 2007
@@ -2,4 +2,9 @@
<name>into</name>
<required>true</required>
<rtexprvalue>false</rtexprvalue>
+ <description>
+ An EL expression that specifies where to store a String holding the results
+ of rendering all the children of this component; this is assigned to after
+ rendering of this component (and its children) is complete.
+ </description>
</attribute>
Modified: myfaces/tomahawk/trunk/core/src/main/tld/tomahawk.tld
URL: http://svn.apache.org/viewvc/myfaces/tomahawk/trunk/core/src/main/tld/tomahawk.tld?rev=598223&r1=598222&r2=598223&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/main/tld/tomahawk.tld (original)
+++ myfaces/tomahawk/trunk/core/src/main/tld/tomahawk.tld Mon Nov 26 03:04:31 2007
@@ -1361,19 +1361,27 @@
<body-content>JSP</body-content>
<description><![CDATA[
<p>
- A tag that defines a new bean (alias) with a given value. This
- allows you to design a subform with a generic (fictive) bean and
- to include it in all the pages where you use it. You just need to
- make an alias mapping the fictive bean name to the real bean before
- including the subform.
+ Defines a new temporary name for an existing bean (or other object). The name
+ is visible only to the children of this tag.
</p>
<p>
- When used within an aliasBeansScope tag, this tag adds the alias to the aliasBeansScope.
- This makes configuration with multiple aliasBeans easier to write.
+ One use of this feature is to pass "parameters" from an including page to an
+ included one. The included page can use any name it desires for beans it needs to
+ reference, and the including page can then use aliasBean to make those names
+ refer to the beans it wishes to "pass" as parameters.
+ </p>
+ <p>
+ When used within an aliasBeansScope tag, this tag adds the alias to the aliasBeansScope;
+ the temporary name then lasts until the end of the parent aliasBeansScope tag rather
+ than just to the end of the aliasBean tag. This makes configuration with multiple
+ aliasBeans easier to write.
</p>
<p>
Unless otherwise specified, all attributes accept static values or EL expressions.
</p>
+ <p>
+ See class org.apache.myfaces.custom.aliasbean.AliasBean for further details.
+ </p>
]]>
</description>
&tomahawk_alias_bean_attributes;
@@ -1383,13 +1391,25 @@
<name>aliasBeansScope</name>
<tag-class>org.apache.myfaces.custom.aliasbean.AliasBeansScopeTag</tag-class>
<body-content>JSP</body-content>
- <description>
- This is like an aliasBean tag, but instead of the alias/value attributes, you configure the aliases
- by adding aliasBean tags in the body.
-
- The aliasBeans should be declared right after this tag.
-
- Unless otherwise specified, all attributes accept static values or EL expressions.
+ <description><![CDATA[
+ <p>Extends the scope of an AliasBean component.</p>
+ <p>
+ The aliasBean tag must enclose all the components that are within the scope
+ of the alias. When multiple aliasas are defined, this makes the page structure
+ very clumsy; for example defining 5 aliases means the content must be nested
+ 5 indentation levels deep. This tag instead allows the content block to be
+ wrapped in just one AliasBeansScope tag, and then have AliasBean tags with
+ empty bodies added as direct children of this component. The scope of the AliasBean
+ tag still starts when the tag begins, but instead of ending when the tag ends
+ the scope of the nested AliasBean tags extends to the end of this component.
+ </p>
+ <p>
+ Unless otherwise specified, all attributes accept static values or EL expressions.
+ </p>
+ <p>
+ See org.apache.myfaces.custom.aliasbean.AliasBeansScopeTag for further details.
+ </p>
+ ]]>
</description>
&faces_id_optional_attribute;
</tag>
@@ -1399,9 +1419,29 @@
<name>buffer</name>
<tag-class>org.apache.myfaces.custom.buffer.BufferTag</tag-class>
<body-content>JSP</body-content>
- <description>
-
- Unless otherwise specified, all attributes accept static values or EL expressions.
+ <description><![CDATA[
+ <p>
+ Renders its child components into an in-memory buffer rather than render them directly to the
+ response stream.
+ </p>
+ <p>
+ Typically, an h:outputText tag is then used later in the same page to output the buffer contents.
+ </p>
+ <p>
+ This can be useful with JSF1.1/JSP2.0 to work around the well-known problem where
+ on first render of a page, a component "A" cannot reference a component "B" which is
+ defined later in the page because it has not yet been created. A solution is to define
+ "B" before "A", but wrapped in a Buffer component. Component A can then be rendered
+ and successfully reference "B" because it now exists. And later in the page, the buffer
+ contents can then be output, preserving the original layout.
+ </p>
+ <p>
+ This can also be useful when rendering the same data block multiple times within a page.
+ For example, a datatable can be rendered with a datascroller both before and after it;
+ first render the table into a buffer B1, then render the datascroller into a buffer B2,
+ then output buffers B2,B1,B2.
+ </p>
+ ]]>
</description>
&tomahawk_buffer_attributes;
</tag>