Anchor


1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   *
16   * $Header:$
17   */
18  package org.apache.beehive.netui.tags.html;
19  
20  import org.apache.beehive.netui.tags.ByRef;
21  import org.apache.beehive.netui.tags.rendering.AbstractHtmlState;
22  import org.apache.beehive.netui.tags.rendering.TagRenderingBase;
23  import org.apache.beehive.netui.tags.rendering.WriteRenderAppender;
24  
25  import javax.servlet.http.HttpServletRequest  ;
26  import javax.servlet.jsp.JspException  ;
27  
28  /**
29   * <p>
30   * Generates a URL-encoded hyperlink to a specified URI.
31   * Also adds support for URL re-writing and JavaScript-based form submission.
32   * An anchor must have one of the following attributes to correctly create the hyperlink:
33   * <ul>
34   * <li>action - an action invoked by clicking the hyperlink.</li>
35   * <li>href - a URL to go to</li>
36   * <li>linkName - an internal place in the page to move to</li>
37   * <li>clientAction - the action to run on the client</li>
38   * <li>tagId - the ID of the tag</li>
39   * <li>formSubmit - indicates whether or not the enclosing Form should be submitted</li>
40   * </ul>
41   * </p>
42   * @jsptagref.tagdescription <p>
43   * Generates an anchor that can link to another document or invoke an action method in the Controller file.
44   * The &lt;netui:anchor> tag also supports JavaScript-based form submission and URL re-writing.
45   * <p>
46   * An anchor must have one of the following attributes to correctly create the hyperlink:
47   * <blockquote>
48   * <ul>
49   * <li><code>action</code> - the action method invoked by clicking the hyperlink</li>
50   * <li><code>href</code> - the URL to go to</li>
51   * <li><code>linkName</code> - an internal place in the page to move to</li>
52   * <li><code>clientAction</code> - the action to run on the client</li>
53   * <li><code>tagId</code> - the ID of the tag</li>
54   * <li><code>formSubmit</code> - indicates whether or not the enclosing Form should be submitted</li>
55   * </ul>
56   * </blockquote>
57   * </p>
58   * @example <b>Submitting Form Data</b>
59   * <p>In this sample, clicking on this anchor submits the form data and invokes the method
60   * <code>submitForm</code>.
61   * <pre>
62   *      &lt;netui:form action="formSubmit">
63   *          Firstname:
64   *          &lt;netui:textBox dataSource="actionForm.firstname"/>
65   *          Lastname:
66   *          &lt;netui:textBox dataSource="actionForm.lastname"/>
67   *          &lt;netui:anchor formSubmit="true">Submit&lt;/netui:anchor>
68   *      &lt;/netui:form></pre>
69   * <p>If the <code>formSubmit</code> attribute is set to <code>true</code> and no
70   * <code>onClick</code> attribute is set, the following JavaScript function will be written to the HTML page.
71   * This JavaScript function will be referenced by the <code>onclick</code> attribute of the generated anchor tag.</p>
72   * <pre>
73   *  function anchor_submit_form(netuiName, newAction)
74   *  {
75   *    for (var i=0; i&lt;document.forms.length; i++) {
76   *       if (document.forms[i].id == netuiName) {
77   *          document.forms[i].method = "POST";
78   *          document.forms[i].action = newAction;
79   *          document.forms[i].submit();
80   *       }
81   *     }
82   *  }</pre>
83   * <p> The JavaScript function will be invoked by the generated HTML anchor tag as follows:
84   * <pre>
85   * &lt;a HREF="../../../../../../../WebApp/tagSamples/anchor/formSubmit.do"
86   *       onClick='anchor_submit_form("Netui_Form_0","/WebApp/tagSamples/anchor/formSubmit.do");return false;'>Submit&lt;/a></pre>
87   * <p>
88   * <b>Custom JavaScript Functions</b>
89   * </p>
90   * <p>It is possible to write a custom <code>onClick</code> JavaScript event handler that would
91   * do additional work, for example form validation, and still POST the form correctly.  To
92   * accomplish this, add the custom JavaScript method to the page:
93   * <pre>
94   * function SubmitFromAnchor()
95   * {
96   *   // implement custom logic here
97   *
98   *   for(var i=0; i&lt;document.forms.length; i++)
99   *   {
100  *     // submit to the action /aWebapp/formPost.do
101  *     if (document.forms[i].action == "/aWebapp/formPost.do")
102  *     {
103  *       document.forms[i].method="POST";
104  *       document.forms[i].action="/aWebapp/formPost.do";
105  *       document.forms[i].submit();
106  *     }
107  *   }
108  * }</pre>
109  * Then reference the JavaScript method from the &lt;netui:anchor> tag:
110  * <pre>
111  * &lt;netui:anchor formSubmit="true" onClick="SubmitFromAnchor(); return false;"&gt;Submit&lt;/netui:anchor&gt;</pre>
112  * @netui:tag name="anchor" description="Generates a URL-encoded hyperlink to a specified URI."
113  * @see Attribute
114  * @see java.lang.String
115  */
116 public class Anchor extends AnchorBase
117 {
118     private String   _text;         // The body content of this tag (if any).
119     private String   _value;
120 
121     /**
122      * Returns the name of the Tag.
123      */
124     public String   getTagName()
125     {
126         return "Anchor";
127     }
128 
129     /**
130      * This method will return the state associated with the tag.  This is used by this
131      * base class to access the individual state objects created by the tags.
132      * @return a subclass of the <code>AbstractHtmlState</code> class.
133      */
134     public AbstractHtmlState getState()
135     {
136         return _state;
137     }
138 
139     /**
140      * Sets the onClick javascript event.
141      * @param onclick the onClick event.
142      * @jsptagref.attributedescription The onClick JavaScript event.
143      * @jsptagref.databindable false
144      * @jsptagref.attributesyntaxvalue <i>string_onClick</i>
145      * @netui:attribute required="false" rtexprvalue="true"
146      * description="The onClick JavaScript event."
147      */
148     public void setOnClick(String   onclick)
149     {
150         _state.registerAttribute(AbstractHtmlState.ATTR_JAVASCRIPT, ONCLICK, setNonEmptyValueAttribute(onclick));
151         // Jira 299
152         //_state.onClick = setNonEmptyValueAttribute(onclick);
153     }
154 
155     /**
156      * Set a client action to run on the client.  When set on an anchor, a NetUI JavaScript action
157      * will be run.  This attribute may not be set if <code>href</code> or <code>action</code> is set.
158      * @param action an action to run on the client.
159      * @jsptagref.attributedescription The action (NetUI JavaScript) to run on the client.
160      * @jsptagref.databindable false
161      * @jsptagref.attributesyntaxvalue <i>string_clientAction</i>
162      * @netui:attribute required="false" rtexprvalue="true" description="The client action."
163      * description="The action (NetUI JavaScript) to run on the client."
164      */
165     public void setClientAction(String   action)
166             throws JspException  
167     {
168         _clientAction = setRequiredValueAttribute(action, "clientAction");
169     }
170 
171     /**
172      * Sets the link name of the Anchor.  The link name is treated as a fragment
173      * identifier and may or may not contain the "#" character.  If it does, the
174      * link name will not be qualified into a ScriptContainer.  If the link name
175      * does not contain the "#" the normal tagId qualification will take place
176      * to produce the actual fragment identifier.
177      * @param linkName the link name for the Anchor.
178      * @jsptagref.attributedescription An internal place on the page to go to.
179      * @jsptagref.databindable false
180      * @jsptagref.attributesyntaxvalue <i>string_linkName</i>
181      * @netui:attribute required="false"  rtexprvalue="true"
182      * description="An internal place on the page to go to."
183      */
184     public void setLinkName(String   linkName)
185             throws JspException  
186     {
187         _linkName = setRequiredValueAttribute(linkName, "linkName");
188     }
189 
190     /**
191      * Sets <code>charset</code> attribute for the anchor.
192      * @param charSet the window target.
193      * @jsptagref.attributedescription The character set.
194      * @jsptagref.databindable false
195      * @jsptagref.attributesyntaxvalue <i>string_charset</i>
196      * @netui:attribute required="false"  rtexprvalue="true"
197      * description="The character set."
198      */
199     public void setCharSet(String   charSet)
200     {
201         _state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, CHARSET, charSet);
202     }
203 
204     /**
205      * Sets <code>type</code> attribute for the anchor.
206      * @param type the window target.
207      * @jsptagref.attributedescription The type.
208      * @jsptagref.databindable false
209      * @jsptagref.attributesyntaxvalue <i>string_type</i>
210      * @netui:attribute required="false"  rtexprvalue="true"
211      * description="The type."
212      */
213     public void setType(String   type)
214     {
215         _state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, TYPE, type);
216     }
217 
218     /**
219      * Sets <code>hreflang</code> attribute for the anchor.
220      * @param hreflang the window target.
221      * @jsptagref.attributedescription The HREF lang.
222      * @jsptagref.databindable false
223      * @jsptagref.attributesyntaxvalue <i>string_hreflang</i>
224      * @netui:attribute required="false"  rtexprvalue="true"
225      * description="The HREF lang."
226      */
227     public void setHrefLang(String   hreflang)
228     {
229         _state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, HREFLANG, hreflang);
230     }
231 
232     /**
233      * Sets <code>rel</code> attribute for the anchor.
234      * @param rel the window target.
235      * @jsptagref.attributedescription The relationship between the current document and the target Url.
236      * @jsptagref.databindable false
237      * @jsptagref.attributesyntaxvalue <i>string_rel</i>
238      * @netui:attribute required="false"  rtexprvalue="true"
239      * description="The rel."
240      */
241     public void setRel(String   rel)
242     {
243         _state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, REL, rel);
244     }
245 
246     /**
247      * Sets <code>rev</code> attribute for the anchor.
248      * @param rev the window target.
249      * @jsptagref.attributedescription Describes a reverse link from the anchor specified to the current document.
250      * @jsptagref.databindable false
251      * @jsptagref.attributesyntaxvalue <i>string_rev</i>
252      * @netui:attribute required="false" rtexprvalue="true"
253      * description="The rev."
254      */
255     public void setRev(String   rev)
256     {
257         _state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, REV, rev);
258     }
259 
260 
261     /**
262      * Sets the window target.
263      * @param target the window target.
264      * @jsptagref.attributedescription The window target.
265      * @jsptagref.databindable false
266      * @jsptagref.attributesyntaxvalue <i>string_action</i>
267      * @netui:attribute required="false"  rtexprvalue="true"
268      * description="The window target."
269      */
270     public void setTarget(String   target)
271     {
272         _state.registerAttribute(AbstractHtmlState.ATTR_GENERAL, TARGET, target);
273     }
274 
275     /**
276      * This will set the text of the anchor.  If there is body content, this
277      * will override that value.
278      * @param value the text of the anchor.
279      * @jsptagref.attributedescription Set the text of the anchor, overriding the body content.
280      * @jsptagref.databindable false
281      * @jsptagref.attributesyntaxvalue <i>string_value</i>
282      * @netui:attribute required="false"  rtexprvalue="true"
283      * description="Set the text of the anchor overriding the body content"
284      */
285     public void setValue(String   value)
286     {
287         _value = setNonEmptyValueAttribute(value);
288     }
289 
290     /**
291      * Prepare the hyperlink for rendering
292      * @throws JspException if a JSP exception has occurred
293      */
294     public int doStartTag() throws JspException  
295     {
296         if (hasErrors())
297             return SKIP_BODY;
298         return EVAL_BODY_BUFFERED;
299     }
300 
301     /**
302      * Save the body content of the Anchor.
303      * @throws JspException if a JSP exception has occurred
304      */
305     public int doAfterBody() throws JspException  
306     {
307         if (bodyContent != null && _value == null) {
308             String   value = bodyContent.getString().trim();
309             bodyContent.clearBody();
310             if (value.length() > 0)
311                 _text = value;
312         }
313         return SKIP_BODY;
314     }
315 
316     /**
317      * Render the hyperlink.
318      * @throws JspException if a JSP exception has occurred
319      */
320     public int doEndTag() throws JspException  
321     {
322         // report errors that may have occurred when the required attributes are being set
323         if (hasErrors())
324             return reportAndExit(EVAL_PAGE);
325 
326         if (_value != null) {
327             _text = _value;
328         }
329         
330         // build the anchor into the results
331         ByRef script = new ByRef();
332 
333         WriteRenderAppender writer = new WriteRenderAppender(pageContext);
334         HttpServletRequest   request = (HttpServletRequest  ) pageContext.getRequest();
335         TagRenderingBase trb = TagRenderingBase.Factory.getRendering(TagRenderingBase.ANCHOR_TAG, request);
336 
337         if (!createAnchorBeginTag(request, script, trb, writer, REQUIRED_ATTR)) {
338             if (!script.isNull())
339                 write(script.getRef().toString());
340             return reportAndExit(EVAL_PAGE);
341         }
342 
343         if (_text != null)
344             write(_text);
345 
346         assert(trb != null) : "trb is null";
347         trb.doEndTag(writer);
348 
349         if (!script.isNull())
350             write(script.getRef().toString());
351 
352         // Render the remainder to the output stream
353         localRelease();
354         return EVAL_PAGE;
355     }
356 
357 }
358
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags