001: /*
002: * Copyright (c) 2002-2006 by OpenSymphony
003: * All rights reserved.
004: */
005: package com.opensymphony.webwork.components;
006:
007: import com.opensymphony.xwork.util.OgnlValueStack;
008: import com.opensymphony.webwork.WebWorkException;
009:
010: import java.io.Writer;
011:
012: /**
013: * <!-- START SNIPPET: javadoc -->
014: * <p>This tag can be used to parameterize other tags.</p>
015: * The include tag and bean tag are examples of such tags.
016: * <p/>
017: * The parameters can be added with or without a name as key.
018: * If the tag provides a name attribute the parameters are added using the
019: * {@link Component#addParameter(String, Object) addParamter} method.
020: * For unnamed parameters the Tag must implement the {@link UnnamedParametric} interface defined in
021: * this class (e.g. The TextTag does this).
022: * <p/>
023: * This tag has the following two paramters.
024: * <!-- START SNIPPET: params -->
025: * <ul>
026: * <li>name (String) - the name of the parameter</li>
027: * <li>value (Object) - the value of the parameter</li>
028: * </ul>
029: * <!-- END SNIPPET: params -->
030: * <p/>
031: * <b>Note:</b>
032: * When you declare the param tag, the value can be defined in either a <tt>value</tt> attribute or
033: * as text between the start and end tag. WebWork behaves a bit different according to these two situations.
034: * This is best illustrated using an example:
035: * <br/><param name="color">blue</param> <-- (A) -->
036: * <br/><param name="color" value="blue"/> <-- (B) -->
037: * <br/>In the first situation (A) the value would be evaluated to the stack as a <tt>java.lang.String</tt> object.
038: * And in situation (B) the value would be evaluated to the stack as a <tt>java.lang.Object</tt> object.
039: * <br/>For more information see <a href="http://jira.opensymphony.com/browse/WW-808">WW-808</a>.
040: * <!-- END SNIPPET: javadoc -->
041: *
042: * <p/> <b>Examples</b>
043: * <!-- START SNIPPET: example -->
044: * <pre>
045: * <ui:component>
046: * <ui:param name="key" value="[0]"/>
047: * <ui:param name="value" value="[1]"/>
048: * <ui:param name="context" value="[2]"/>
049: * </ui:component>
050: * </pre>
051: * <!-- END SNIPPET: example -->
052: * <p/>
053: * <!-- START SNIPPET: exampledescription -->
054: * where the key will be the identifier and the value the result of an OGNL expression run against the current
055: * OgnlValueStack.
056: * <!-- END SNIPPET: exampledescription -->
057: * <p/>
058: * This second example demonstrates how the text tag can use parameters from this param tag.
059: * <!-- START SNIPPET: example2 -->
060: * <pre>
061: * <ww:text name="cart.total.cost">
062: * <ww:param value="#session.cartTotal"/>
063: * </ww:text>
064: * </pre>
065: * <!-- END SNIPPET: example2 -->
066: * <p/>
067: *
068: * @author Rickard �berg (rickard@dreambean.com)
069: * @author Rene Gielen
070: * @author tm_jee
071: * @version $Revision: 2647 $
072: * @since 2.2
073: *
074: * @see Include
075: * @see Bean
076: * @see Text
077: *
078: * @ww.tag name="param" tld-body-content="JSP" tld-tag-class="com.opensymphony.webwork.views.jsp.ParamTag"
079: * description="Parametrize other tags"
080: */
081: public class Param extends Component {
082: protected String name;
083: protected String value;
084:
085: public Param(OgnlValueStack stack) {
086: super (stack);
087: }
088:
089: public boolean end(Writer writer, String body) {
090: Component component = findAncestor(Component.class);
091: if (value != null) {
092: if (component instanceof UnnamedParametric) {
093: ((UnnamedParametric) component)
094: .addParameter(findValue(value));
095: } else {
096: String name = findString(this .name);
097:
098: if (name == null) {
099: throw new WebWorkException(
100: "No name found for following expression: "
101: + name);
102: }
103:
104: Object value = findValue(this .value);
105: component.addParameter(name, value);
106: }
107: } else {
108: if (component instanceof UnnamedParametric) {
109: ((UnnamedParametric) component).addParameter(body);
110: } else {
111: component.addParameter(findString(name), body);
112: }
113: }
114:
115: return super .end(writer, "");
116: }
117:
118: public boolean usesBody() {
119: return true;
120: }
121:
122: /**
123: * Name of Parameter to set
124: * @ww.tagattribute required="false" type="String"
125: */
126: public void setName(String name) {
127: this .name = name;
128: }
129:
130: /**
131: * Value expression for Parameter to set
132: * @ww.tagattribute required="false" default="The value of evaluating provided name against stack"
133: */
134: public void setValue(String value) {
135: this .value = value;
136: }
137:
138: /**
139: * Tags can implement this to support nested param tags without the <tt>name</tt> attribute.
140: * <p/>
141: * The {@link Text TextTag} uses this approach. For unnamed parameters an example is given in the class
142: * javadoc for {@link Param ParamTag}.
143: */
144: public interface UnnamedParametric {
145:
146: /**
147: * Adds the given value as a parameter to the outer tag.
148: * @param value the value
149: */
150: public void addParameter(Object value);
151: }
152:
153: }
|