net.sourceforge.stripes.tag
Class FormTag

java.lang.Object
  extended by net.sourceforge.stripes.tag.StripesTagSupport
      extended by net.sourceforge.stripes.tag.HtmlTagSupport
          extended by net.sourceforge.stripes.tag.FormTag
All Implemented Interfaces:
BodyTag, DynamicAttributes, IterationTag, JspTag, Tag, TryCatchFinally, ParameterizableTag

public class FormTag
extends HtmlTagSupport
implements BodyTag, TryCatchFinally, ParameterizableTag

Form tag for use with the Stripes framework. Supports all of the HTML attributes applicable to the form tag, with one exception: due to JSP attribute naming restrictions accept-charset is specified as acceptcharset (but will be rendered correctly in the output HTML).

Author:
Tim Fennell

Field Summary
 
Fields inherited from class net.sourceforge.stripes.tag.StripesTagSupport
pageContext, parentTag
 
Fields inherited from interface javax.servlet.jsp.tagext.BodyTag
EVAL_BODY_BUFFERED, EVAL_BODY_TAG
 
Fields inherited from interface javax.servlet.jsp.tagext.IterationTag
EVAL_BODY_AGAIN
 
Fields inherited from interface javax.servlet.jsp.tagext.Tag
EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE
 
Constructor Summary
FormTag()
           
 
Method Summary
 void addParameter(String name, Object valueOrValues)
          Appends a parameter to the "action" attribute of the form tag.
protected  String buildAction()
          Builds the action attribute, including the context path and any parameters.
 int doAfterBody()
          Just returns SKIP_BODY so that the body is included only once.
 void doCatch(Throwable throwable)
          Rethrows the passed in throwable in all cases.
 int doEndTag()
          Writes things out in the following order: The form open tag Hidden fields for the form name and source page The buffered body content The form close tag
 void doFinally()
          Used to ensure that the form is always removed from the tag stack so that there is never any confusion about tag-parent hierarchies.
 void doInitBody()
          No-op method.
 int doStartTag()
          Does sanity checks and returns EVAL_BODY_BUFFERED.
 String getAccept()
           
 String getAcceptcharset()
           
 String getAction()
           
protected  ActionBean getActionBean()
          Fetches the ActionBean associated with the form if one is present.
protected  Class<? extends ActionBean> getActionBeanClass()
          Lazily looks up and returns the type of action bean the form will submit to.
protected  String getActionBeanUrlBinding()
          Get the URL binding for the form's ActionBean from the ActionResolver.
 Object getBeanclass()
          Corresponding getter for 'beanclass', will always return null.
 String getEnctype()
          Gets the form encoding.
 String getFocus()
          Gets the name of the field that should receive focus when the form is rendered.
 String getMethod()
          Gets the HTTP method to use when the form is submitted.
 String getName()
           
 String getOnreset()
           
 String getOnsubmit()
           
 Set<String> getRegisteredFields()
          Gets the set of all field names for which fields have been referred within the form up until the point of calling this method.
 String getTarget()
           
 boolean isPartial()
          Gets the flag that indicates if this is a partial form.
protected  boolean isWizard()
          Returns true if the ActionBean this form posts to represents a Wizard action bean and false in all other situations.
 void registerField(InputTagSupport tag)
          Used by nested tags to notify the form that a field with the specified name has been written to the form.
 void setAccept(String accept)
           
 void setAcceptcharset(String acceptCharset)
           
 void setAction(String action)
          Sets the action for the form.
 void setBeanclass(Object beanclass)
          Sets the 'action' attribute by inspecting the bean class provided and asking the current ActionResolver what the appropriate URL is.
 void setEnctype(String enctype)
          Sets the form encoding.
 void setFocus(String focus)
          Sets the name of the field that should receive focus when the form is rendered.
protected  void setFocusOnFieldIfRequired(InputTagSupport tag)
          Checks to see if the field should receive focus either because it is the named field for receiving focus, because it is the first field in the form (and first field focus was specified), or because it is the first field in error.
 void setMethod(String method)
          Sets the HTTP method to use when the form is submitted.
 void setName(String name)
           
 void setOnreset(String onreset)
           
 void setOnsubmit(String onsubmit)
           
 void setPartial(boolean partial)
          Sets the flag that indicates if this is a partial form.
 void setTarget(String target)
           
protected  void writeFieldsPresentHiddenField(JspWriter out)
          In general writes out a hidden field notifying the server exactly what fields were present on the page.
protected  void writeWizardFields()
          Writes out hidden fields for all fields that are present in the request but are not explicitly present in this form.
 
Methods inherited from class net.sourceforge.stripes.tag.HtmlTagSupport
evaluateExpression, get, getAccesskey, getAttributes, getBodyContent, getBodyContentAsString, getCssClass, getDir, getId, getLang, getOnblur, getOnchange, getOnclick, getOndblclick, getOnfocus, getOnkeydown, getOnkeypress, getOnkeyup, getOnmousedown, getOnmousemove, getOnmouseout, getOnmouseover, getOnmouseup, getOnselect, getStyle, getTabindex, getTitle, release, set, setAccesskey, setBodyContent, setClass, setCssClass, setDir, setDynamicAttribute, setId, setLang, setOnblur, setOnchange, setOnclick, setOndblclick, setOnfocus, setOnkeydown, setOnkeypress, setOnkeyup, setOnmousedown, setOnmousemove, setOnmouseout, setOnmouseover, setOnmouseup, setOnselect, setStyle, setTabindex, setTitle, toString, writeAttributes, writeCloseTag, writeOpenTag, writeSingletonTag
 
Methods inherited from class net.sourceforge.stripes.tag.StripesTagSupport
getActionBeanType, getActionBeanUrl, getPageContext, getParent, getParentTag, getTagStack, popPageContextAttributes, pushPageContextAttributes, setPageContext, setParent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface javax.servlet.jsp.tagext.BodyTag
setBodyContent
 
Methods inherited from interface javax.servlet.jsp.tagext.Tag
getParent, release, setPageContext, setParent
 

Constructor Detail

FormTag

public FormTag()
Method Detail

setAction

public void setAction(String action)
Sets the action for the form. If the form action begins with a slash, and does not already contain the context path, then the context path of the web application will get prepended to the action before it is set. In general actions should be specified as "absolute" paths within the web application, therefore allowing them to function correctly regardless of the address currently shown in the browser's address bar.

Parameters:
action - the action path, relative to the root of the web application

getAction

public String getAction()

getActionBeanUrlBinding

protected String getActionBeanUrlBinding()
Get the URL binding for the form's ActionBean from the ActionResolver.


getActionBeanClass

protected Class<? extends ActionBean> getActionBeanClass()
Lazily looks up and returns the type of action bean the form will submit to.


setBeanclass

public void setBeanclass(Object beanclass)
                  throws StripesJspException
Sets the 'action' attribute by inspecting the bean class provided and asking the current ActionResolver what the appropriate URL is.

Parameters:
beanclass - the String FQN of the class, or a Class representing the class
Throws:
StripesJspException - if the URL cannot be determined for any reason, most likely because of a mis-spelled class name, or a class that's not an ActionBean

getBeanclass

public Object getBeanclass()
Corresponding getter for 'beanclass', will always return null.


setFocus

public void setFocus(String focus)
Sets the name of the field that should receive focus when the form is rendered.


getFocus

public String getFocus()
Gets the name of the field that should receive focus when the form is rendered.


isPartial

public boolean isPartial()
Gets the flag that indicates if this is a partial form.


setPartial

public void setPartial(boolean partial)
Sets the flag that indicates if this is a partial form.


setEnctype

public void setEnctype(String enctype)
Sets the form encoding.


getEnctype

public String getEnctype()
Gets the form encoding.


setMethod

public void setMethod(String method)
Sets the HTTP method to use when the form is submitted.


getMethod

public String getMethod()
Gets the HTTP method to use when the form is submitted.


setAccept

public void setAccept(String accept)

getAccept

public String getAccept()

setAcceptcharset

public void setAcceptcharset(String acceptCharset)

getAcceptcharset

public String getAcceptcharset()

setName

public void setName(String name)

getName

public String getName()

setTarget

public void setTarget(String target)

getTarget

public String getTarget()

setOnreset

public void setOnreset(String onreset)

getOnreset

public String getOnreset()

setOnsubmit

public void setOnsubmit(String onsubmit)

getOnsubmit

public String getOnsubmit()

doStartTag

public int doStartTag()
               throws JspException
Does sanity checks and returns EVAL_BODY_BUFFERED. Everything else of interest happens in doEndTag.

Specified by:
doStartTag in interface Tag
Specified by:
doStartTag in class StripesTagSupport
Throws:
JspException

doInitBody

public void doInitBody()
                throws JspException
No-op method.

Specified by:
doInitBody in interface BodyTag
Throws:
JspException

doAfterBody

public int doAfterBody()
                throws JspException
Just returns SKIP_BODY so that the body is included only once.

Specified by:
doAfterBody in interface IterationTag
Throws:
JspException

doEndTag

public int doEndTag()
             throws JspException
Writes things out in the following order:

All of this is done in doEndTag to allow form elements to modify the form tag itself if necessary. A prime example of this is the InputFileTag, which needs to ensure that the form method is POST and the enctype is correct.

Specified by:
doEndTag in interface Tag
Specified by:
doEndTag in class StripesTagSupport
Throws:
JspException

doCatch

public void doCatch(Throwable throwable)
             throws Throwable
Rethrows the passed in throwable in all cases.

Specified by:
doCatch in interface TryCatchFinally
Throws:
Throwable

doFinally

public void doFinally()
Used to ensure that the form is always removed from the tag stack so that there is never any confusion about tag-parent hierarchies.

Specified by:
doFinally in interface TryCatchFinally

writeFieldsPresentHiddenField

protected void writeFieldsPresentHiddenField(JspWriter out)
                                      throws IOException

In general writes out a hidden field notifying the server exactly what fields were present on the page. Exact behaviour depends upon whether or not the current form is a wizard or not. When the current form is not a wizard this method examines the form tag to determine what fields present in the form might not get submitted to the server (e.g. checkboxes, selects), writes out a hidden field that contains the names of all those fields so that we can detect non-submission when the request comes back.

In the case of a wizard form the value output is the full list of all fields that were present on the page. This is done because the list is used to drive required field validation knowing that in a wizard required fields may be spread across several pages.

In both cases the value is encrypted to stop the user maliciously spoofing the value.

Parameters:
out - the output writer into which the hidden tag should be written
Throws:
IOException - if the writer throws one

getActionBean

protected ActionBean getActionBean()
Fetches the ActionBean associated with the form if one is present. An ActionBean will not be created (and hence not present) by default. An ActionBean will only be present if the current request got bound to the same ActionBean as the current form uses. E.g. if we are re-showing the page as the result of an error, or the same ActionBean is used for a "pre-Action" and the "post-action".

Returns:
ActionBean the ActionBean bound to the form if there is one

isWizard

protected boolean isWizard()
Returns true if the ActionBean this form posts to represents a Wizard action bean and false in all other situations. If the form cannot determine the ActionBean being posted to for any reason it will return false.


writeWizardFields

protected void writeWizardFields()
                          throws JspException
Writes out hidden fields for all fields that are present in the request but are not explicitly present in this form. Excludes any fields that have special meaning to Stripes and are not really application data. Uses the stripes:wizard-fields tag to do the grunt work.

Throws:
JspException

registerField

public void registerField(InputTagSupport tag)
Used by nested tags to notify the form that a field with the specified name has been written to the form.

Parameters:
tag - the input field tag being registered

setFocusOnFieldIfRequired

protected void setFocusOnFieldIfRequired(InputTagSupport tag)
Checks to see if the field should receive focus either because it is the named field for receiving focus, because it is the first field in the form (and first field focus was specified), or because it is the first field in error.

Parameters:
tag - the input tag being registered with the form

getRegisteredFields

public Set<String> getRegisteredFields()
Gets the set of all field names for which fields have been referred within the form up until the point of calling this method. If this is called during doEndTag it will contain all field names, if it is called during the body of the tag it will only contain the input elements which have been processed up until that point.

Returns:
Set - the set of field names seen so far

addParameter

public void addParameter(String name,
                         Object valueOrValues)
Appends a parameter to the "action" attribute of the form tag. For clean URLs the value will be embedded in the URL if possible. Otherwise, it will be added to the query string.

Specified by:
addParameter in interface ParameterizableTag
Parameters:
name - the parameter name
valueOrValues - the parameter value(s)
See Also:
ParameterizableTag.addParameter(String, Object)

buildAction

protected String buildAction()
Builds the action attribute, including the context path and any parameters.

Returns:
the action attribute


? Copyright 2005-2006, Stripes Development Team.