org.olat.core.gui.components.form.flexible.impl
Class Form

java.lang.Object
  org.olat.core.logging.LogDelegator
      org.olat.core.gui.components.form.flexible.impl.Form

public class Form
extends LogDelegator

Description:

This Form is responsible for creation of the form header and footer. It can not hold form elements. Instead one has to create a form container and put the form elements there. E.g. use FormLayoutContainer or FormVelocityContainer.

This Form is the Component which gets dispatched by the framework. It then dispatches further to the really clicked FormComponent. The Form implements the following phases:

1. let all Formelements evaluate the Formrequest
2. dispatch to the correct FormComponent
3. the dispatched FormComponent may decide to SUBMIT the form, e.g. let all FormComponents validate its input and report error, or taken other actions.
4. during the validatition phase each FormComponent can register an action
5. after the validation, all actions are applied
6. an event is thrown if the form validated or not

FormComponent and FormContainer form the same composite pattern as already used for the core.Component and core.Container, and take notice that the FormComponent itself is also a core.Component!
As a consequence of this, each element which want to live inside of a form must be a FormComponent but has also a Component side to the rendering framework.

The goals of the new form infrastructure are

• to allow complete freedom for layouting forms.
• easy-migration path for existing forms
• easy-usage for developers
• easy-layouting for designers
• allow subworkflows in forms without loosing form input
• allow AJAX features for form elements (completion, on blur etc.)

Some extra care had to be taken to fullfill these requirements and still beeing compliant with the already existing AJAX component replacement.
It was decided that a FormComponent consist of

• Formelement, e.g. input field, radio button, select box, a link!
• Label for the Formelement
• Error for the Formelement
• Example for the Formelement

Multipart and file upload

Since release 6.1 the form infrastructure does also support multipart form data (file uploads). The form switches to the multipart mode as soon as a form element of type FormMultipartItem is added. In this case, all file uploads and form parameters are parsed by the form class and added to the requestParams and requestMultipartFiles maps. If no multipart element is in the form, the normal non-multipart way is used (less overhead, stability).

Therefore it is important to always use the form.getParameter() methods and not the getParameter() methods from the user request directly. Normally you don't have to deal with this because the implemented form elements already take care of this issue.

All submitted files are saved to a temporary location in the userdata/tmp/ directory. During the dispatch phase in evalFormRequest() this files can be access using the getMultipartFilesSet() and getMultipartFile() methods. The files must be moved to another location within the execution of the evalFormRequest() because at the end of the method call, the temporary files will be removed. The temporary files have a random file name, use the getMultipartFileName() to retrieve the original file name.

When using the FileElement this is all already encapsulated, see the documentation there.

Initial Date: 27.11.2006

Author:

patrickb

Field Summary

static java.lang.String	FORM_UNDEFINED
static java.lang.String	FORMCMD
static java.lang.String	FORMID
static int	REQUEST_ERROR_FILE_EMPTY
static int	REQUEST_ERROR_GENERAL
static int	REQUEST_ERROR_NO_ERROR
static int	REQUEST_ERROR_UPLOAD_LIMIT_EXCEEDED

Method Summary

void	addListener(Controller listener) add another listener then the default listener, which is added at construction time.
void	addSubFormListener(FormBasicController formBasicController)
static Form	create(java.lang.String name, FormItemContainer formLayout, Controller listener) create a new form, where the caller is attached as component listener.
void	evalFormRequest(UserRequest ureq)
void	fireFormEvent(UserRequest ureq, FormEvent event)
int	getAction()
java.lang.String	getDispatchFieldId()
java.lang.String	getEventFieldId()
java.lang.String	getFormName()
Container	getInitialComponent()
int	getLastRequestError() Check if there was an error while parsing this request.
long	getReplayableDispatchID(Component comp) Get the replayableID for a component, for use only in urlReplay mode.
java.io.File	getRequestMultipartFile(java.lang.String key) Return the multipart file for this key
java.lang.String	getRequestMultipartFileMimeType(java.lang.String key) Return the multipart file mime type (content type) for this key:
java.lang.String	getRequestMultipartFileName(java.lang.String key) Return the multipart file name for this key:
java.util.Set<java.lang.String>	getRequestMultipartFilesSet()
java.lang.String	getRequestParameter(java.lang.String key) Return the form parameter for a certain key.
java.util.Set<java.lang.String>	getRequestParameterSet() Return the form parameter set.
java.lang.String[]	getRequestParameterValues(java.lang.String key) Return the form parameter values for a certain key.
boolean	isDirtyMarking() true if the form should not loose unsubmitted changes, if another link is clicked which throws away the changes.
boolean	isMultipartEnabled()
boolean	isSubmittedAndValid()
void	reset(UserRequest ureq)
void	setDirtyMarking(boolean isDirtyMarking)
void	setMultipartEnabled(boolean multipartEnabled, int multipartUploadMaxSizeKB)
void	submit(UserRequest ureq)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORMCMD

public static final java.lang.String FORMCMD

See Also:

Constant Field Values

FORMID

public static final java.lang.String FORMID

See Also:

Constant Field Values

FORM_UNDEFINED

public static final java.lang.String FORM_UNDEFINED

See Also:

Constant Field Values

REQUEST_ERROR_NO_ERROR

public static final int REQUEST_ERROR_NO_ERROR

See Also:

Constant Field Values

REQUEST_ERROR_GENERAL

public static final int REQUEST_ERROR_GENERAL

See Also:

Constant Field Values

REQUEST_ERROR_FILE_EMPTY

public static final int REQUEST_ERROR_FILE_EMPTY

See Also:

Constant Field Values

REQUEST_ERROR_UPLOAD_LIMIT_EXCEEDED

public static final int REQUEST_ERROR_UPLOAD_LIMIT_EXCEEDED

See Also:

Constant Field Values

Method Detail

create

public static Form create(java.lang.String name,
                          FormItemContainer formLayout,
                          Controller listener)

create a new form, where the caller is attached as component listener. Caller receives form validation success or failure events.

Parameters:

name -

translator -

rootFormContainer - if null the default layout is choosen, otherwise the given layouting container is taken.

listener - the component listener of this form, typically the caller

Returns:

evalFormRequest

public void evalFormRequest(UserRequest ureq)

Parameters:

ureq -

getLastRequestError

public int getLastRequestError()

Check if there was an error while parsing this request. See REQUEST_ERROR_* constants

Returns:

the last error code

submit

public void submit(UserRequest ureq)

Parameters:

ureq -

reset

public void reset(UserRequest ureq)

Parameters:

ureq -

getInitialComponent

public Container getInitialComponent()

addListener

public void addListener(Controller listener)

add another listener then the default listener, which is added at construction time.

Parameters:

listener -

getRequestParameter

public java.lang.String getRequestParameter(java.lang.String key)

Return the form parameter for a certain key. This takes care if a multipart form has been used or a normal form.

LiveCycle scope: only within one call of evalFormRequest() !

Parameters:

key -

Returns:

the value of the parameter with key 'key'

getRequestParameterValues

public java.lang.String[] getRequestParameterValues(java.lang.String key)

Return the form parameter values for a certain key. This takes care if a multipart form has been used or a normal form.
This method is used to retrieve multi-value elements, e.g. radio buttons.
Use the getRequestParameter() to retrieve single value elements, e.g. input type=text elements

Parameters:

key -

Returns:

Array of values for this key

getRequestParameterSet

public java.util.Set<java.lang.String> getRequestParameterSet()

Return the form parameter set. This takes care if a multipart form has been used or a normal form.

LiveCycle scope: only within one call of evalFormRequest() !

Returns:

the Set of parameters

getRequestMultipartFile

public java.io.File getRequestMultipartFile(java.lang.String key)

Return the multipart file for this key

LiveCycle scope: only within one call of evalFormRequest() !

Parameters:

key -

Returns:

getRequestMultipartFileName

public java.lang.String getRequestMultipartFileName(java.lang.String key)

Return the multipart file name for this key:

LiveCycle scope: only within one call of evalFormRequest() !

Parameters:

key -

Returns:

getRequestMultipartFileMimeType

public java.lang.String getRequestMultipartFileMimeType(java.lang.String key)

Return the multipart file mime type (content type) for this key:

LiveCycle scope: only within one call of evalFormRequest() !

Parameters:

key -

Returns:

getRequestMultipartFilesSet

public java.util.Set<java.lang.String> getRequestMultipartFilesSet()

Returns:

The set of multipart file identifyers

getDispatchFieldId

public java.lang.String getDispatchFieldId()

getFormName

public java.lang.String getFormName()

fireFormEvent

public void fireFormEvent(UserRequest ureq,
                          FormEvent event)

getEventFieldId

public java.lang.String getEventFieldId()

Returns:

Returns the eventFieldId.

getAction

public int getAction()

isSubmittedAndValid

public boolean isSubmittedAndValid()

isDirtyMarking

public boolean isDirtyMarking()

true if the form should not loose unsubmitted changes, if another link is clicked which throws away the changes.

Returns:

setDirtyMarking

public void setDirtyMarking(boolean isDirtyMarking)

addSubFormListener

public void addSubFormListener(FormBasicController formBasicController)

setMultipartEnabled

public void setMultipartEnabled(boolean multipartEnabled,
                                int multipartUploadMaxSizeKB)

isMultipartEnabled

public boolean isMultipartEnabled()

getReplayableDispatchID

public long getReplayableDispatchID(Component comp)

Get the replayableID for a component, for use only in urlReplay mode. The replayableID is set the first time this method is called for a particular component.

Parameters:

component -

Returns:

replayableID