View Javadoc

1   /*
2    * $Id: Param.java 651946 2008-04-27 13:41:38Z apetrelli $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  package org.apache.struts2.components;
23  
24  import java.io.Writer;
25  
26  import org.apache.struts2.views.annotations.StrutsTag;
27  import org.apache.struts2.views.annotations.StrutsTagAttribute;
28  import org.apache.struts2.StrutsException;
29  
30  import com.opensymphony.xwork2.util.ValueStack;
31  
32  /***
33   * <!-- START SNIPPET: javadoc -->
34   * <p>This tag can be used to parameterize other tags.</p>
35   * The include tag and bean tag are examples of such tags.
36   * <p/>
37   * The parameters can be added with or without a name as key.
38   * If the tag provides a name attribute the parameters are added using the
39   * {@link Component#addParameter(String, Object) addParamter} method.
40   * For unnamed parameters the Tag must implement the {@link UnnamedParametric} interface defined in
41   * this class (e.g. The TextTag does this).
42   * <p/>
43   * This tag has the following two paramters.
44   * <!-- START SNIPPET: params -->
45   * <ul>
46   *      <li>name (String) - the name of the parameter</li>
47   *      <li>value (Object) - the value of the parameter</li>
48   * </ul>
49   * <!-- END SNIPPET: params -->
50   * <p/>
51   * <b>Note:</b>
52   * When you declare the param tag, the value can be defined in either a <tt>value</tt> attribute or
53   * as text between the start and end tag. Struts behaves a bit different according to these two situations.
54   * This is best illustrated using an example:
55   * <br/>&lt;param name="color"&gt;blue&lt;/param&gt; &lt;-- (A) --&gt;
56   * <br/>&lt;param name="color" value="blue"/&gt; &lt;-- (B) --&gt;
57   * <br/>In the first situation (A) the value would be evaluated to the stack as a <tt>java.lang.String</tt> object.
58   * And in situation (B) the value would be evaluated to the stack as a <tt>java.lang.Object</tt> object.
59   * <br/>For more information see <a href="http://jira.opensymphony.com/browse/WW-808">WW-808</a>.
60   * <!-- END SNIPPET: javadoc -->
61   *
62   * <p/> <b>Examples</b>
63   * <!-- START SNIPPET: example -->
64   * <pre>
65   * &lt;ui:component&gt;
66   *  &lt;ui:param name="key"     value="[0]"/&gt;
67   *  &lt;ui:param name="value"   value="[1]"/&gt;
68   *  &lt;ui:param name="context" value="[2]"/&gt;
69   * &lt;/ui:component&gt;
70   * </pre>
71   * <!-- END SNIPPET: example -->
72   * <p/>
73   * <!-- START SNIPPET: exampledescription -->
74   * where the key will be the identifier and the value the result of an OGNL expression run against the current
75   * ValueStack.
76   * <!-- END SNIPPET: exampledescription -->
77   * <p/>
78   * This second example demonstrates how the text tag can use parameters from this param tag.
79   * <!-- START SNIPPET: example2 -->
80   * <pre>
81   * &lt;s:text name="cart.total.cost"&gt;
82   *     &lt;s:param value="#session.cartTotal"/&gt;
83   * &lt;/s:text&gt;
84   * </pre>
85   * <!-- END SNIPPET: example2 -->
86   * <p/>
87   *
88   * @see Include
89   * @see Bean
90   * @see Text
91   *
92   */
93  @StrutsTag(name="param", tldTagClass="org.apache.struts2.views.jsp.ParamTag", description="Parametrize other tags")
94  public class Param extends Component {
95      protected String name;
96      protected String value;
97  
98      public Param(ValueStack stack) {
99          super(stack);
100     }
101 
102     public boolean end(Writer writer, String body) {
103         Component component = findAncestor(Component.class);
104         if (value != null) {
105             if (component instanceof UnnamedParametric) {
106                 ((UnnamedParametric) component).addParameter(findValue(value));
107             } else {
108                 String name = findString(this.name);
109 
110                 if (name == null) {
111                     throw new StrutsException("No name found for following expression: " + name);
112                 }
113 
114                 Object value = findValue(this.value);
115                 component.addParameter(name, value);
116             }
117         } else {
118             if (component instanceof UnnamedParametric) {
119                 ((UnnamedParametric) component).addParameter(body);
120             } else {
121                 component.addParameter(findString(name), body);
122             }
123         }
124 
125         return super.end(writer, "");
126     }
127 
128     public boolean usesBody() {
129         return true;
130     }
131 
132     @StrutsTagAttribute(description="Name of Parameter to set")
133     public void setName(String name) {
134         this.name = name;
135     }
136 
137     @StrutsTagAttribute(description="Value expression for Parameter to set", defaultValue="The value of evaluating provided name against stack")
138     public void setValue(String value) {
139         this.value = value;
140     }
141     
142     /***
143      * Tags can implement this to support nested param tags without the <tt>name</tt> attribute.
144      * <p/>
145      * The {@link Text TextTag} uses this approach. For unnamed parameters an example is given in the class
146      * javadoc for {@link Param ParamTag}.
147      */
148     public interface UnnamedParametric {
149 
150         /***
151          * Adds the given value as a parameter to the outer tag.
152          * @param value  the value
153          */
154         public void addParameter(Object value);
155     }
156 
157 }