com.arsdigita.bebop
Class Form

java.lang.Object
  extended bycom.arsdigita.bebop.Completable
      extended bycom.arsdigita.bebop.SimpleComponent
          extended bycom.arsdigita.bebop.FormSection
              extended bycom.arsdigita.bebop.Form
All Implemented Interfaces:
BebopConstants, Cloneable, Component, Container, Lockable
Direct Known Subclasses:
AddProcess, AddTask, CategoryForm, ChangePasswordForm, ControlBar, DisplayActions.AddSubnodeForm, DisplayActions.MountInstanceForm, DisplayActions.RemoveNodeForm, DisplayActions.UnmountInstanceForm, DisplayTask, MetaForm, MultiStepForm, NewAction, NewControl, NewSection, PropertiesForm, UserForm, UserRegistrationForm, UserSearchForm

public class Form
extends FormSection
implements BebopConstants

Represents the visual structure of an HTML form. Forms can be constructed with a Container argument to specify the type of layout this form will adhere to. The default is a column panel.

As an example, a form that accepts a first and last name may be set up as follows:

 public class MyForm extends Form
   implements FormProcessListener {

   private Text m_firstName;
   private Text m_lastName;

   public MyForm() {
     super("myform");
     add(new Label("First Name:"));
     m_firstName = new Text("firstName");
     m_firstName.setDefaultValue("John");
     add(m_firstName);

     add(new Label("Last Name:"));
     m_lastName = new Text("lastName");
     m_lastName.setDefaultValue("Doe");
     m_lastName.addValidationListener(new NotNullValidationListener
                                          ("The last name"));
     add(m_lastName);

     add(new Submit("save", "Save"));
     addProcessListener(this);
   }

   public void process(FormSectionEvent e) {
     PageState s = e.getPageState();

     System.out.println("You are " + m_firstName.getValue(s)
                     + " " + m_lastName.getValue(s));
   }
 }
 

This form automatically checks that the user supplied a last name. Only then does it call the process method, which prints the user-supplied values.

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/Form.java#18 $
Author:
Karl Goldstein, Uday Mathur, Stas Freidin, Rory Solomon, David Lutterkort

Field Summary
static String GET
          Constant for specifying a get submission method for this form.
static String POST
          Constant for specifying a post submission method for this form.
static String versionId
           
 
Fields inherited from class com.arsdigita.bebop.FormSection
m_formModel, m_panel
 
Fields inherited from class com.arsdigita.bebop.SimpleComponent
m_attr
 
Fields inherited from interface com.arsdigita.bebop.util.BebopConstants
BEBOP_BORDER, BEBOP_BOXPANEL, BEBOP_CELL, BEBOP_CHECKBOX, BEBOP_CHECKBOXGROUP, BEBOP_COLUMNPANEL, BEBOP_DATE, BEBOP_DATETIME, BEBOP_DHTMLEDITOR, BEBOP_FORMERRORS, BEBOP_FORMWIDGET, BEBOP_GRIDPANEL, BEBOP_LIST, BEBOP_MULTISELECT, BEBOP_OPTION, BEBOP_PAD, BEBOP_PADFRAME, BEBOP_PANELROW, BEBOP_PORTAL, BEBOP_PORTLET, BEBOP_RADIO, BEBOP_RADIOGROUP, BEBOP_SEG_BODY, BEBOP_SEG_HEADER, BEBOP_SEG_PANEL, BEBOP_SEGMENT, BEBOP_SELECT, BEBOP_TABLE, BEBOP_TABLEBODY, BEBOP_TABLEROW, BEBOP_TEXTAREA
 
Fields inherited from interface com.arsdigita.bebop.Component
BEBOP_XML_NS, CLASS, ID, ON_CLICK, STYLE
 
Constructor Summary
Form(String name)
           
Form(String name, Container panel)
          Constructs a new form with the specified name and container.
 
Method Summary
protected  void addMagicTag()
          Adds a Hidden Tag to this form so that our controller can determine if this is an initial request.
 void excludeParameterFromExport(ParameterModel model)
          TODO
protected  void generateErrors(PageState ps, Element parent)
           
 void generateXML(PageState s, Element parent)
          Writes the output to a DOM to be used with the XSLT template to produce the appropriate output.
protected  Element generateXMLSansState(PageState s, Element parent)
          Generates the XML representing the form and its widgets, but not the state information from s.
 String getAction()
          Returns the URL for the form's action attribute.
 FormData getFormData(PageState state)
          Returns the form data constructed by the process method for the request described by state.
 String getName()
          Gets the name attribute for this form.
protected  boolean getProcessInvisible()
          Returns true if form processing is turned on when the form is invisible.
 boolean isRedirecting()
          Determine whether or not this Form will redirect after its process listeners are fired.
 FormData process(PageState state)
          Processes this form, creating a FormData object.
 void register(Page p)
          Adds this form to the page and traverses the components contained in this form, collecting parameterModels and Listeners into this form's FormModel.
 void respond(PageState state)
          Responds to the request by processing this form with the HTTP request given in state.
 void setAction(String action)
          Sets the URL for the form's action attribute.
 void setEncType(String encType)
          Sets the enctype attribute used in the form element.
protected  void setFormData(PageState state, FormData data)
          Protected access to set the formdata request local
 void setMethod(String method)
          Sets the HTTP method used to submit the form.
 void setName(String name)
          Sets the name attribute for the form.
 void setOnReset(String javascriptCode)
          Sets the ONRESET attribute used in the FORM element.
 void setOnSubmit(String javascriptCode)
          Sets the onSubmit attribute used in the form element.
protected  void setProcessInvisible(boolean processInvisible)
          Turns form processing on/off when the form is invisible.
 void setRedirecting(boolean isRedirecting)
          Setting the redirecting flag will cause the Form to clear the control event and redirect back to the current URL, after firing all process listeners.
 String toString()
          Converts to a String.
protected  void traverse()
          Traverses the components contained in this form, collecting parameterModels and Listeners into this form's FormModel.
 
Methods inherited from class com.arsdigita.bebop.FormSection
add, add, addCancelListener, addInitListener, addProcessListener, addSubmissionListener, addValidationListener, children, contains, createInitListener, createProcessListener, createSubmissionListener, createValidationListener, fireCancel, fireInit, fireProcess, fireSubmitted, fireValidate, forwardInit, forwardProcess, forwardSubmission, forwardValidation, get, getModel, getPanel, indexOf, isEmpty, lock, register, removeCancelListener, removeInitListener, removeProcessListener, removeSubmissionListener, removeValidationListener, size
 
Methods inherited from class com.arsdigita.bebop.SimpleComponent
clone, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, setAttribute, setClassAttr, setIdAttr, setKey, setMetaDataAttribute, setStyleAttr, setVisible
 
Methods inherited from class com.arsdigita.bebop.Completable
addCompletionListener, fireCompletionEvent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.arsdigita.bebop.Component
getClassAttr, getIdAttr, getKey, getStyleAttr, isVisible, setClassAttr, setIdAttr, setKey, setStyleAttr, setVisible
 
Methods inherited from interface com.arsdigita.util.Lockable
isLocked
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

GET

public static final String GET
Constant for specifying a get submission method for this form. See the W3C HTML specification for a description of what this attribute does.

See Also:
Constant Field Values

POST

public static final String POST
Constant for specifying a post submission method for this form. See the W3C HTML specification for a description of what this attribute does.

See Also:
Constant Field Values
Constructor Detail

Form

public Form(String name)

Form

public Form(String name,
            Container panel)
Constructs a new form with the specified name and container. At the time of at the time of creation, instantiates a new form model for the form and replaces the default ColumnPanel with the specified container as the implicit container of the components.

Parameters:
name - the name of the form
panel - the implicit container that will hold the components
Method Detail

generateXML

public void generateXML(PageState s,
                        Element parent)
Writes the output to a DOM to be used with the XSLT template to produce the appropriate output. If the form is not visible, no output is generated.

Generates a DOM fragment:

 <bebop:form action=%url; %bebopAttr;>
   .. XML for panel ..
   .. XML for page state ..
 </bebop:form>
 

Specified by:
generateXML in interface Component
Overrides:
generateXML in class FormSection
Parameters:
s - the page state used to determine the values of form widgets and page state attributes
parent - the XML element to which the form adds its XML representation
See Also:
PageState.generateXML(com.arsdigita.xml.Element)

generateXMLSansState

protected Element generateXMLSansState(PageState s,
                                       Element parent)
Generates the XML representing the form and its widgets, but not the state information from s.

Parameters:
s - represents the curent request
Returns:
the top-level element for the form

generateErrors

protected void generateErrors(PageState ps,
                              Element parent)

isRedirecting

public boolean isRedirecting()

Determine whether or not this Form will redirect after its process listeners are fired.


setRedirecting

public void setRedirecting(boolean isRedirecting)

Setting the redirecting flag will cause the Form to clear the control event and redirect back to the current URL, after firing all process listeners. Doing so means that a user reload will not cause the form to be resubmitted. The default value for this flag is false.


respond

public void respond(PageState state)
             throws javax.servlet.ServletException
Responds to the request by processing this form with the HTTP request given in state.

Specified by:
respond in interface Component
Overrides:
respond in class FormSection
Parameters:
state - represents the current request
Throws:
javax.servlet.ServletException
See Also:
process(...)

setName

public void setName(String name)
Sets the name attribute for the form.

Parameters:
name - the name for the form

getName

public String getName()
Gets the name attribute for this form.

Returns:
the name for this form.

setEncType

public void setEncType(String encType)
Sets the enctype attribute used in the form element. No encoding type is specified by default.

Parameters:
encType - the encoding type

setOnSubmit

public void setOnSubmit(String javascriptCode)
Sets the onSubmit attribute used in the form element. No onsubmit handler is specified by default.

Parameters:
javascriptCode - the javascript code associated with this attribute

setOnReset

public void setOnReset(String javascriptCode)
Sets the ONRESET attribute used in the FORM element. No onreset handler is specified by default.

Parameters:
javascriptCode - the javascript code associated with this attribute

setMethod

public void setMethod(String method)
Sets the HTTP method used to submit the form.

Parameters:
method - either GET or POST

getProcessInvisible

protected boolean getProcessInvisible()
Returns true if form processing is turned on when the form is invisible.

Returns:
true if the form listeners should be processed even when the form is not visible on the page, false otherwise

setProcessInvisible

protected void setProcessInvisible(boolean processInvisible)
Turns form processing on/off when the form is invisible.

Parameters:
processInvisible - true if the form listeners should be processed even when the form is not visible on the page

setAction

public void setAction(String action)
Sets the URL for the form's action attribute. This is the URL to which submissions will be sent when the user clicks a submit button on the form. By default, the action is null, instructing the form to set the action to the URL of the page in which it is used. If the action is set to a different URL, none of the listeners registered with this form will be run.

Parameters:
action - the URL to submit this form to

getAction

public final String getAction()
Returns the URL for the form's action attribute.

Returns:
the URL to which to submit this form.
See Also:
setAction

process

public FormData process(PageState state)
                 throws FormProcessException
Processes this form, creating a FormData object. Runs the right set of init, validation, and process listeners, depending on whether this is an initial request to the form and whether the form submission was valid. Submission listeners are always run.

Overrides:
process in class FormSection
Parameters:
state - represents the current request
Returns:
the values extracted from the HTTP request contained in state.
Throws:
FormProcessException
See Also:
getFormData(com.arsdigita.bebop.PageState)

getFormData

public FormData getFormData(PageState state)
Returns the form data constructed by the process method for the request described by state. Processes the form if it has not already been processed.

Parameters:
state - describes the current request
Returns:
the values extracted from the HTTP request contained in state, or null if the form has not been processed yet.

addMagicTag

protected void addMagicTag()
Adds a Hidden Tag to this form so that our controller can determine if this is an initial request.


traverse

protected void traverse()
Traverses the components contained in this form, collecting parameterModels and Listeners into this form's FormModel.


register

public void register(Page p)
Adds this form to the page and traverses the components contained in this form, collecting parameterModels and Listeners into this form's FormModel.

Specified by:
register in interface Component
Overrides:
register in class SimpleComponent
Parameters:
p - page in which to register this form

excludeParameterFromExport

public void excludeParameterFromExport(ParameterModel model)
TODO


toString

public String toString()
Converts to a String.

Returns:
a human-readable representation of this.

setFormData

protected void setFormData(PageState state,
                           FormData data)
Protected access to set the formdata request local



Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC