com.arsdigita.bebop.form
Class Widget

java.lang.Object
  extended bycom.arsdigita.bebop.Completable
      extended bycom.arsdigita.bebop.SimpleComponent
          extended bycom.arsdigita.bebop.TextStylable
              extended bycom.arsdigita.bebop.BlockStylable
                  extended bycom.arsdigita.bebop.form.Widget
All Implemented Interfaces:
BebopConstants, Cloneable, Component, Lockable
Direct Known Subclasses:
Date, DateTime, Deditor, FileUpload, Hidden, ImageSubmit, OptionGroup, Password, Reset, Submit, TextArea, TextField, Time

public abstract class Widget
extends BlockStylable
implements Cloneable, BebopConstants

A class representing a widget in the graphical representation of a form.

A widget may correspond to a standard HTML form element, or to a more specific element or set of elements, such as a date widget that allows input of month, day and year (and possibly time as well).

This class and its subclasses provide methods to set all element attributes except for VALUE, which is typically dependent on the request. At the time of a request, a widget object merges a dynamically specified value or set of values with its own set of persistent attributes to render the final HTML for the widget. Other dynamic attributes may be associated with the form component via a WidgetPeer associated with the widget.

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/form/Widget.java#13 $
Author:
Karl Goldstein, Uday Mathur, Rory Solomon

Nested Class Summary
static interface Widget.ValidationGuard
          Inner interface used to determine if the validation listeners should be run for this widget or not.
 
Field Summary
static String versionId
           
 
Fields inherited from class com.arsdigita.bebop.BlockStylable
ABSBOTTOM, ABSMIDDLE, BASELINE, BOTTOM, CENTER, FULL_WIDTH, INSERT, LEFT, MIDDLE, RIGHT, TEXTTOP, TOP
 
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
protected Widget(ParameterModel model)
          Constructs a new widget.
protected Widget(String name)
          Constructs a new widget.
 
Method Summary
 void addError(GlobalizedMessage mesg)
          Adds an error to be displayed with this parameter.
 void addError(String error)
          Adds an error to be displayed with this parameter.
 void addPrintListener(PrintListener listener)
          Adds a print listener for this widget.
 void addValidationListener(ParameterListener listener)
           
 Object clone()
          Clones a component.
protected  ParameterListener createParameterListener()
           
protected  Widget firePrintEvent(PageState state)
           
protected  void fireValidation(ParameterEvent evt)
           
protected  void generateErrors(PageState state, Element parent)
          Generates the XML for the given widget
protected  void generateWidget(PageState state, Element parent)
          Generates the DOM for the given widget
 void generateXML(PageState state, Element parent)
           This method creates the DOM for the widget.
 String getDefaultValue()
          Gets the default value in the parameter model for this element.
protected  String getElementTag()
          The XML tag.
protected  Iterator getErrors(PageState ps)
           
 Form getForm()
          Gets the Form Object for this Widget.
 String getName()
           
protected  ParameterData getParameterData(PageState ps)
           
 ParameterModel getParameterModel()
          Allows access to underlying parameterModel.
protected abstract  String getType()
          Returns a string naming the type of this widget.
 Object getValue(PageState ps)
          Get the value associated with this widget in the request described by ps.
abstract  boolean isCompound()
          Returns true if the widget consists of multiple HTML elements.
 boolean isPassIn()
          The "pass in" property determines whether the value for this parameter is generally passed in from the outside.
 void register(Form form, FormModel model)
          Registers the ParameterModel of this Widget with the containing Form.
 void removePrintListener(PrintListener listener)
          Remove a previously added print listener.
 void removeValidationListener(ParameterListener listener)
           
 void respond(PageState state)
          Respond to an incoming request by calling respond on the form to which the widget belongs.
 void setDefaultValue(Object value)
          Sets the default value in the parameter model for this element.
 void setDisabled()
          Marks this widget as disabled, which has the effect of preventing the widget's value being submitted with the form, and will typically cause the widget to be 'grayed out' on the form.
 void setForm(Form form)
          Sets the Form Object for this Widget.
 void setHint(String hint)
          Sets a popup hint for the widget
 void setOnBlur(String javascriptCode)
          Sets the ONBLUR attribute for the HTML tags that compose this element.
 void setOnChange(String javascriptCode)
          Sets the ONCHANGE attribute for the HTML tags that compose this element.
 void setOnFocus(String javascriptCode)
          Sets the ONFOCUS attribute for the HTML tags that compose this element.
 void setOnKeyUp(String javascriptCode)
          Sets the ON_KEY_UP attribute for the HTML tags that compose this element.
 void setOnSelect(String javascriptCode)
          Sets the ONSELECT attribute for the HTML tags that compose this element.
 void setParameterModel(ParameterModel parameterModel)
          The ParameterModel is normally set via the constructors.
 void setPassIn(boolean v)
          Set whether this parameter should be treated as a "pass in" parameter.
 void setPrintListener(PrintListener listener)
          Set the print listener for this widget.
 void setReadOnly()
          Marks this widget as readonly, which has the effect of preventing the user from modifying the widget's contents.
 void setValidateInvisible(boolean value)
           
 void setValidationGuard(Widget.ValidationGuard guard)
          Specify a Widget.ValidationGuard implementation to use to determine if this widget should run its validation listeners.
 void setValue(PageState ps, Object value)
          Set the value of the parameter associated with this widget to a new value.
 String toString()
           
 boolean validateInvisible()
           
 
Methods inherited from class com.arsdigita.bebop.BlockStylable
setBorder, setBorder, setBorderColor, setHorizontalAlignment, setMargin, setMargin, setPadding, setPadding, setVerticalAlignment
 
Methods inherited from class com.arsdigita.bebop.TextStylable
setBackgroundColor, setColor
 
Methods inherited from class com.arsdigita.bebop.SimpleComponent
children, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, lock, register, 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
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values
Constructor Detail

Widget

protected Widget(String name)
Constructs a new widget.


Widget

protected Widget(ParameterModel model)
Constructs a new widget.

Each new widget is associated with a ParameterModel describing the data object(s) submitted from the widget.

Method Detail

isCompound

public abstract boolean isCompound()
Returns true if the widget consists of multiple HTML elements.


getType

protected abstract String getType()
Returns a string naming the type of this widget. Must be implemented by subclasses


createParameterListener

protected ParameterListener createParameterListener()

setValidateInvisible

public void setValidateInvisible(boolean value)

validateInvisible

public boolean validateInvisible()

fireValidation

protected void fireValidation(ParameterEvent evt)
                       throws FormProcessException
Throws:
FormProcessException

addValidationListener

public void addValidationListener(ParameterListener listener)

removeValidationListener

public void removeValidationListener(ParameterListener listener)

addPrintListener

public void addPrintListener(PrintListener listener)
                      throws TooManyListenersException,
                             IllegalArgumentException
Adds a print listener for this widget. Only one print listener can be set for a widget, since the PrintListener is expected to modify the target of the PrintEvent.

Parameters:
listener - the print listener
Throws:
IlegalArgumentException - listener is null
TooManyListenersException - a print listener has previously been added
IllegalArgumentException

setPrintListener

public void setPrintListener(PrintListener listener)
                      throws IllegalArgumentException
Set the print listener for this widget. Since there can only be one print listener for a widget, this lets you just set it and avoid writing a try/catch block for "TooManyListenersException". Any existing listener will be overwritten.

Parameters:
listener - the print listener
Throws:
IlegalArgumentException - listener is null
IllegalArgumentException

removePrintListener

public void removePrintListener(PrintListener listener)
                         throws IllegalArgumentException
Remove a previously added print listener. If listener is not the listener that has been added with addPrintListener, an IllegalArgumentException will be thrown.

Parameters:
listener - the listener that had been added with addPrintListener
Throws:
IllegalArgumentException - listener is not the currently registered print listener or is null.

register

public void register(Form form,
                     FormModel model)
Registers the ParameterModel of this Widget with the containing Form. This method is used by the Bebop framework and should not be used by application developers.

Specified by:
register in interface Component
Overrides:
register in class SimpleComponent

setForm

public void setForm(Form form)
Sets the Form Object for this Widget. This method will throw an exception if the _form pointer is already set. To explicity change the m_form pointer the developer must first call setForm(null)

Parameters:
form - The Form Object for this Widget
Throws:
IllegalStateException - if form already set.

getForm

public Form getForm()
             throws RuntimeException
Gets the Form Object for this Widget. Throws an exception if the Widget doesn't belong to a form.

Returns:
the Form Object for this Widget.
Throws:
RuntimeException

setOnFocus

public void setOnFocus(String javascriptCode)
Sets the ONFOCUS attribute for the HTML tags that compose this element.


setOnBlur

public void setOnBlur(String javascriptCode)
Sets the ONBLUR attribute for the HTML tags that compose this element.


setOnSelect

public void setOnSelect(String javascriptCode)
Sets the ONSELECT attribute for the HTML tags that compose this element.


setOnChange

public void setOnChange(String javascriptCode)
Sets the ONCHANGE attribute for the HTML tags that compose this element.


setOnKeyUp

public void setOnKeyUp(String javascriptCode)
Sets the ON_KEY_UP attribute for the HTML tags that compose this element.


setDefaultValue

public void setDefaultValue(Object value)
Sets the default value in the parameter model for this element. This is a static property and this method should not be invoked at request time (not even in a PrintListener).


setReadOnly

public void setReadOnly()
Marks this widget as readonly, which has the effect of preventing the user from modifying the widget's contents. This method can only be called on unlocked widgets.


setDisabled

public void setDisabled()
Marks this widget as disabled, which has the effect of preventing the widget's value being submitted with the form, and will typically cause the widget to be 'grayed out' on the form. This method can only be called on unlocked widgets.


setHint

public void setHint(String hint)
Sets a popup hint for the widget


getDefaultValue

public String getDefaultValue()
Gets the default value in the parameter model for this element.


getName

public String getName()

isPassIn

public final boolean isPassIn()
The "pass in" property determines whether the value for this parameter is generally passed in from the outside. If this property is true, the model always tries to get the parameter value from the request, no matter whether the request is the initial request or a submission of the form to which the widget belongs.

If this property is false, the parameter value is only read from the request if it is a submission of the form containing the widget.

By default, this property is false.

Returns:
true if an attempt should always be made to retrieve the parameter value from the request.

setPassIn

public final void setPassIn(boolean v)
Set whether this parameter should be treated as a "pass in" parameter. This is a static property of the ParameterModel and this method should not be invoked at request-time.

Parameters:
v - true if this parameter is a pass in parameter.
See Also:
isPassIn()

setParameterModel

public final void setParameterModel(ParameterModel parameterModel)
The ParameterModel is normally set via the constructors. This method is only rarely needed. Please note that the previous ParameterModel and all its listeners will be lost.


getParameterModel

public final ParameterModel getParameterModel()
Allows access to underlying parameterModel. The ParameterModel contains static (request-independent) properties of a Widget such as its name, default value and its listeners. The ParameterModel can not be modified once Page.lock() has been invoked (not even in a PrintListener). This is done after the Page has been built, normally at server startup.


generateXML

public void generateXML(PageState state,
                        Element parent)

This method creates the DOM for the widget. The method is called by the Bebop framework and should not be invoked by application developers.

The method first fires the print event allowing application developers to set certain properties of the Widget at request time in a PrintListener. The methods generateWidget and generateErrors will then be invoked to generate either of the following

<bebop:formErrors message=...> </bebop:formErrors>

<bebop:formWidget name=... type=... value=... [onXXX=...]> </bebop:formWidget>

Specified by:
generateXML in interface Component
Overrides:
generateXML in class SimpleComponent

firePrintEvent

protected Widget firePrintEvent(PageState state)

getElementTag

protected String getElementTag()
The XML tag.

Returns:
The tag to be used for the top level DOM element generated for this type of Widget.

generateWidget

protected void generateWidget(PageState state,
                              Element parent)
Generates the DOM for the given widget

Generates DOM fragment:

<bebop:formWidget name=... type=... value=... [onXXX=...]> </bebop:formWidget>


generateErrors

protected void generateErrors(PageState state,
                              Element parent)
Generates the XML for the given widget

Generates XML fragment:

<bebop:formErrors message=... id=name> </bebop:formErrors>


getValue

public Object getValue(PageState ps)
Get the value associated with this widget in the request described by ps. The type of the returned object depends on the ParameterModel underlying this widget. This method is typically called in a FormProcessListener to access the value that was submitted for a Widget in the Form.

Parameters:
ps - describes the request currently being processed

setValue

public void setValue(PageState ps,
                     Object value)
              throws IllegalStateException
Set the value of the parameter associated with this widget to a new value. The exact type of value depends on the ParameterModel underlying the widget. This method is typically called in a FormInitListener to initialize the value of a Widget in the Form at request time.

Throws:
IllegalStateExeption - the form to which the widget belongs has not been processed yet.
IllegalStateException

getErrors

protected Iterator getErrors(PageState ps)

getParameterData

protected ParameterData getParameterData(PageState ps)
Returns:
the parameter value for this widget

respond

public void respond(PageState state)
             throws javax.servlet.ServletException
Respond to an incoming request by calling respond on the form to which the widget belongs. This method is called by the Bebop framework and should not be invoked by application developers. It is somewhat questionable that this method should ever be called, rather than having Form.respond() called directly.

Specified by:
respond in interface Component
Overrides:
respond in class SimpleComponent
Parameters:
state - the current page state
Throws:
javax.servlet.ServletException

clone

public Object clone()
             throws CloneNotSupportedException
Description copied from class: SimpleComponent
Clones a component. The clone is not locked and has its own set of attributes.

Overrides:
clone in class SimpleComponent
Returns:
the clone of a component.
Throws:
CloneNotSupportedException

setValidationGuard

public void setValidationGuard(Widget.ValidationGuard guard)
Specify a Widget.ValidationGuard implementation to use to determine if this widget should run its validation listeners.

Parameters:
guard - the Widget.ValidationGuard.

addError

public void addError(GlobalizedMessage mesg)
Adds an error to be displayed with this parameter.

Parameters:
mesg - A GlobalizedMessage that will resolve to the error for the user.

addError

public void addError(String error)
Adds an error to be displayed with this parameter.

Parameters:
error - A string showing the error to the user.

toString

public String toString()


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