org.wings
Class SForm

java.lang.Object
  org.wings.SComponent
      org.wings.SContainer
          org.wings.SForm

All Implemented Interfaces:

Serializable, Cloneable, LowLevelEventListener, Renderable

Direct Known Subclasses:

SWindow

public class SForm
extends SContainer
implements LowLevelEventListener

Container in which you need to wrap HTML input fields (ie. STextField) to work correctly.

The browser uses this object/tag to identify how (POST or GET) and where to send an request originating from any input inside this form.

Note:Please be aware, that some components render differently if placed inside a SForm.

Author:

Armin Haaf

See Also:

Serialized Form

Field Summary

protected String	actionCommand
static String	ENC_TYPE_MULTIPART_FORM Multipart form encoding.
static String	ENC_TYPE_TEXT_PLAIN Default Form encoding type.
protected EventListenerList	listenerList
static String	URL_ENCODING URL form encoding.

Fields inherited from class org.wings.SComponent

DONE_RENDERING, dynamicStyles, enabled, propertyChangeSupport, SELECTOR_ALL, START_RENDERING, visible, WHEN_FOCUSED_OR_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_IN_FOCUSED_FRAME

Constructor Summary

SForm()
Create a standard form component.

SForm(SLayoutManager layout)
Create a standard form component.

SForm(URL action)
Create a standard form component but redirects the request to the passed URL.

Method Summary

void	addActionListener(ActionListener listener) Add a listener for Form events.
static void	addArmedComponent(LowLevelEventListener component) Register a components to be subject to fire component events in a later phase of the request processing.
SComponent	addComponent(SComponent c, Object constraint, int index) Adds a component to the container with the given constraint at the given index.
static void	clearArmedComponents() clear armed components.
protected void	fireActionPerformed(String pActionCommand) Fire a ActionEvent at each registered listener.
static void	fireEvents() This method fires the low level events for all "armed" components of this thread (http session) in an ordered manner: forms buttons / clickables "regular" components This order derives out of the assumption, that a user first modifies regular components before he presses the button submitting his changes.
void	fireFinalEvents() Internal event trigger used by CGs.
void	fireIntermediateEvents() fire events which describes a "in progress" state change, like TreeWillExpand, or ListSelectionEvent with getIsAdjusting() true, ...
URL	getAction()
String	getActionCommand()
FormCG	getCG() Return the look and feel delegate.
SButton	getDefaultButton()
String	getEncodingType() Get the current encoding type, as set with setEncodingType(String).
RequestURL	getRequestURL() The URL under which this component is accessible for the browser.
boolean	isEpochCheckEnabled() Asks the low-level event listener if epoch checking should be perfomed on it.
boolean	isPostMethod() Returns, whether this form is transmitted via POST (true) or GET (false).
void	processLowLevelEvent(String action, String[] values) Deliver low level/http events (parameters).
void	registerFileChooser(SFileChooser fileChooser)
void	removeActionListener(ActionListener listener) Remove a form action listener, that has been added in addActionListener(ActionListener)
void	setAction(URL action)
void	setActionCommand(String actionCommand) A SForm fires an event each time it was triggered (i.e.
void	setCG(FormCG cg)
void	setDefaultButton(SButton defaultButton) Set the default button activated upon enter.
void	setEncodingType(String type) Set the encoding of this form.
void	setEpochCheckEnabled(boolean epochCheckEnabled)
void	setPostMethod(boolean postMethod) Set, whether this form is to be transmitted via POST (true) or GET (false).
void	unregisterFileChooser(SFileChooser fileChooser)

Methods inherited from class org.wings.SContainer

add, add, add, add, addComponent, addComponent, addComponent, addContainerListener, addNotify, clone, fireContainerEvent, getComponent, getComponentCount, getComponentList, getComponents, getConstraintAt, getConstraintList, getLayout, invite, inviteEachComponent, isShowingChildren, processContainerEvent, remove, remove, removeAll, removeContainerListener, removeNotify, setCG, setLayout, setParentFrame, updateCG

Methods inherited from class org.wings.SComponent

addComponentListener, addDynamicStyle, addEventListener, addParentFrameListener, addPropertyChangeListener, addPropertyChangeListener, addRenderListener, addScriptListener, addStyle, fireComponentChangeEvent, fireKeyEvents, fireRenderEvent, getActionMap, getBackground, getBorder, getClientProperty, getComponentPopupMenu, getDynamicStyle, getDynamicStyles, getFocusTraversalIndex, getFont, getForeground, getHorizontalAlignment, getInputMap, getInputMap, getListenerCount, getListenerList, getListeners, getLowLevelEventId, getName, getParent, getParentFrame, getPreferredSize, getResidesInForm, getScriptListenerList, getScriptListeners, getSession, getShowAsFormComponent, getStyle, getToolTipText, getVerticalAlignment, isDifferent, isEnabled, isFocusOwner, isRecursivelyVisible, isReloadForced, isUpdatePossible, isVisible, paramString, processComponentEvent, processKeyEvents, putClientProperty, reload, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, reloadIfChange, removeComponentListener, removeDynamicStyle, removeEventListener, removeParentFrameListener, removePropertyChangeListener, removePropertyChangeListener, removeRenderListener, removeScriptListener, removeStyle, requestFocus, scrollRectToVisible, setActionMap, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributes, setBackground, setBorder, setCG, setComponentPopupMenu, setDynamicStyles, setEnabled, setFocusTraversalIndex, setFont, setForeground, setHorizontalAlignment, setInputMap, setInputMap, setName, setNameRaw, setParent, setPreferredSize, setReloadForced, setShowAsFormComponent, setStyle, setToolTipText, setVerticalAlignment, setVisible, toString, update, write

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.wings.LowLevelEventListener

getLowLevelEventId, getName, isEnabled

Field Detail

ENC_TYPE_TEXT_PLAIN

public static final String ENC_TYPE_TEXT_PLAIN

Default Form encoding type. See setEncodingType(String).

See Also:

Constant Field Values

ENC_TYPE_MULTIPART_FORM

public static final String ENC_TYPE_MULTIPART_FORM

Multipart form encoding. Needed for file uploads. See setEncodingType(String).

See Also:

Constant Field Values

URL_ENCODING

public static final String URL_ENCODING

URL form encoding. See setEncodingType(String).

See Also:

Constant Field Values

listenerList

protected final EventListenerList listenerList

actionCommand

protected String actionCommand

Constructor Detail

SForm

public SForm()

Create a standard form component.

SForm

public SForm(URL action)

Create a standard form component but redirects the request to the passed URL. Use this i.e. to address other servlets.

Parameters:

action - The target URL.

SForm

public SForm(SLayoutManager layout)

Create a standard form component.

Parameters:

layout - The layout to apply to this container.

See Also:

SContainer

Method Detail

setActionCommand

public void setActionCommand(String actionCommand)

A SForm fires an event each time it was triggered (i.e. pressing asubmit button inside)

Parameters:

actionCommand - The action command to place insiside the ActionEvent

getActionCommand

public String getActionCommand()

See Also:

setActionCommand(String)

setDefaultButton

public void setDefaultButton(SButton defaultButton)

Set the default button activated upon enter. The button is triggered if you press enter inside a form to submit it.

Parameters:

defaultButton - A button which will be rendered invisible. If null enter key pressed will be catched by the wings framework.

getDefaultButton

public SButton getDefaultButton()

See Also:

setDefaultButton(SButton)

addActionListener

public void addActionListener(ActionListener listener)

Add a listener for Form events. A Form event is always triggered, when a form has been submitted. Usually, this happens, whenever a submit button is pressed or some other mechanism triggered the posting of the form. Other mechanisms are

• Java Script submit() event
• If a form contains a single text input, then many browsers submit the form, if the user presses RETURN in that field. In that case, the submit button will not receive any event but only the form.
• The SFileChooser will trigger a form event, if the file size exceeded the allowed size. In that case, even if the submit button has been pressed, no submit-button event will be triggered. (For details, see SFileChooser).

Form events are guaranteed to be triggered after all Selection-Changes and Button ActionListeners.

removeActionListener

public void removeActionListener(ActionListener listener)

Remove a form action listener, that has been added in addActionListener(ActionListener)

fireActionPerformed

protected void fireActionPerformed(String pActionCommand)

Fire a ActionEvent at each registered listener.

addArmedComponent

public static void addArmedComponent(LowLevelEventListener component)

Register a components to be subject to fire component events in a later phase of the request processing. SForm will call LowLevelEventListener.fireIntermediateEvents() and later LowLevelEventListener.fireFinalEvents() in a later phase of the request. The calls on the components will be ordered dependend on their type.

Parameters:

component - The component to callback for event firing in a later phase of the request

See Also:

fireEvents()

clearArmedComponents

public static void clearArmedComponents()

clear armed components. This is usually not necessary, since sessions clear clear their armed components. But if there was some Exception, it might well be, that this does not happen.

fireEvents

public static void fireEvents()

This method fires the low level events for all "armed" components of this thread (http session) in an ordered manner:

• forms
• buttons / clickables
• "regular" components

This order derives out of the assumption, that a user first modifies regular components before he presses the button submitting his changes. Otherwise button actions would get fired before the edit components fired their events.

setPostMethod

public void setPostMethod(boolean postMethod)

Set, whether this form is to be transmitted via POST (true) or GET (false). The default, and this is what you usually want, is POST.

isPostMethod

public boolean isPostMethod()

Returns, whether this form is transmitted via POST (true) or GET (false).

Default is true.

Returns:

true if form postedt via POST, false if via GET (false).

setEncodingType

public void setEncodingType(String type)

Set the encoding of this form. This actually is an HTML interna that bubbles up here. By default, the encoding type of any HTML-form is application/x-www-form-urlencoded, and as such, needn't be explicitly set with this setter. However, if you've included a file upload element (as represented by SFileChooser) in your form, this must be set to multipart/form-data, since only then, files are transmitted correctly. In 'normal' forms without file upload, it is not necessary to set it to multipart/form-data; actually it enlarges the data to be transmitted, so you probably don't want to do this, then.

Parameters:

type - the encoding type; one of multipart/form-data, application/x-www-form-urlencoded or null to detect encoding.

getEncodingType

public String getEncodingType()

Get the current encoding type, as set with setEncodingType(String). If no encoding type was set, this method detects the best encoding type. This can be expensive, so if you can, set the encoding type.

Returns:

string containing the encoding type. This is something like multipart/form-data, application/x-www-form-urlencoded .. or 'null' by default.

registerFileChooser

public void registerFileChooser(SFileChooser fileChooser)

unregisterFileChooser

public void unregisterFileChooser(SFileChooser fileChooser)

setAction

public void setAction(URL action)

getAction

public URL getAction()

getRequestURL

public RequestURL getRequestURL()

Description copied from class: SComponent

The URL under which this component is accessible for the browser. This is equivalent to the URL of the component's root frame, as this is the node externalized to the browser via the ReloadResource externalizer.

Overrides:

getRequestURL in class SComponent

Returns:

The HTTP URL where this component can be accessed.

processLowLevelEvent

public void processLowLevelEvent(String action,
                                 String[] values)

Description copied from interface: LowLevelEventListener

Deliver low level/http events (parameters). The name-value-pairs of the HTTPRequest are considered low level events.

Specified by:

processLowLevelEvent in interface LowLevelEventListener

Overrides:

processLowLevelEvent in class SComponent

Parameters:

action - the name-value-pair's name

values - the name-value-pair's values

fireIntermediateEvents

public void fireIntermediateEvents()

Description copied from interface: LowLevelEventListener

fire events which describes a "in progress" state change, like TreeWillExpand, or ListSelectionEvent with getIsAdjusting() true, ...

Specified by:

fireIntermediateEvents in interface LowLevelEventListener

fireFinalEvents

public void fireFinalEvents()

Description copied from class: SComponent

Internal event trigger used by CGs. This Method is called internal and should not be called directly

Specified by:

fireFinalEvents in interface LowLevelEventListener

Overrides:

fireFinalEvents in class SComponent

isEpochCheckEnabled

public boolean isEpochCheckEnabled()

Description copied from interface: LowLevelEventListener

Asks the low-level event listener if epoch checking should be perfomed on it. If true the Dispatcher will ignore request originating from old views (typically iniated by triggering browser back and clicking somewhere.)

Specified by:

isEpochCheckEnabled in interface LowLevelEventListener

Returns:

true if epoch checking should be perfomed, false if all request for this component should be processed.

See Also:

LowLevelEventListener.isEpochCheckEnabled()

setEpochCheckEnabled

public void setEpochCheckEnabled(boolean epochCheckEnabled)

See Also:

LowLevelEventListener.isEpochCheckEnabled()

addComponent

public SComponent addComponent(SComponent c,
                               Object constraint,
                               int index)

Description copied from class: SContainer

Adds a component to the container with the given constraint at the given index.

Overrides:

addComponent in class SContainer

Parameters:

c - the component to add

index - the index of the component

Returns:

the added component

setCG

public void setCG(FormCG cg)

getCG

public FormCG getCG()

Description copied from class: SComponent

Return the look and feel delegate.

Overrides:

getCG in class SComponent

Returns:

the componet's cg