org.olat.core.gui.components.form.flexible
Interface FormItem

All Superinterfaces:

FormBaseComponentIdProvider

All Known Subinterfaces:

Cancel, DateChooser, FileElement, FormItemContainer, FormLink, FormMultipartItem, InlineElement, InlineIntegerElement, InlineTextElement, IntegerElement, MultipleSelectionElement, Reset, RichTextElement, SelectionElement, SingleSelection, SpacerElement, StaticTextElement, Submit, TextElement

All Known Implementing Classes:

AbstractTextElement, FileElementImpl, FlexiTableElementImpl, FormCancel, FormItemImpl, FormLayoutContainer, FormLinkImpl, FormReset, FormSubmit, IntegerElementImpl, JSDateChooser, MultipleSelectionElementImpl, MultiSelectionTree, RichTextElementImpl, SingleSelectionImpl, SpacerElementImpl, StaticTextElementImpl, TextAreaElementImpl, TextElementImpl

public interface FormItem
extends FormBaseComponentIdProvider

Summary:

setting panels content is optional and params can always be null

• setXyzKey(String i18nKey, String[] params)
• setErrorComponent(FormItem quickFixWizard)

accessing different panels within velocity of a form item:

• $r.render("formElementName_LABEL")
• $r.render("formElementName_ERROR")
• $r.render("formElementName_EXAMPLE")

find out about form item attributes by querying it from the velocity page with:

• $f.isMandatory("formElementName")
• $f.hasError("formElementName")
• $f.hasExample("formElementName")
• $f.hasLabel("formElementName")

whereas $f. is the FormDecorator instance in the velocity.

Description:

Each implemented form item consists of 4 panels appearing as div's in the html rendered page. They belong together in a logical way, but are layoutable, e.g. placeable anywhere within a velocity page. The following figure illustrates the logical composition.

• the Element panel
  The form element panel holds for example one or more checkboxes, a dropdownbox, an input field, ... any other html form element, a link!, a custom element!
• the Label panel
  textlabel for the element
• the Error panel
  Either a textlabel as error text or another form element. This form element can then start a subworkflow explaining the error or for fixing the error.
• the Example panel
  example text, explaing an input format or how to proceed with the shown element.

The following figure shows a concrete example of a yes-no switch, the form element is labeled "Depending on date". The screenshot is taken in debug mode mini which is available in development mode only. SingleSelectionImpl is the FormItem implemenation in this case.

The java code to create the above yes-no-switch looks as follows. Please note the anonymous class creation style, with a initializer block. This helps grouping the code:

• 519: dateSwitch is the name of the element in the velocity container
• 521/522: form.easy.dateSwitch is the i18n key for labeling, and the label is made visible.
• 523/524: sets the i18n keys for yes and no, and selects no as default
• 528: add an onclick listener, so you get informed if yes or no is clicked
• 529: final step of adding the form element to form (layout), it is then available in the velocity page layouting the form under the name dateSwitch

The form item goes to a velocity page under defined name, e.g. dateSwitch, and the corresponding logical panels are accessed with the following convention:

• form element name_LABEL
• form element name_ERROR
• form element name_EXAMPLE

It is very common that a layout needs information about whether a form item has an error, example, label or is mandatory. This information is available through a FormDecorator which can be accessed for example as $f.hasError("dateSwitch").

The FormItem is aggregated within FormItemContainer and both together form the composite pattern.
They play together with the Component and Container

Initial Date: 24.11.2006

Author:

patrickb

Field Summary

static java.lang.String	ERRORC
static java.lang.String	EXAMPLEC
static java.lang.String	LABELC

Fields inherited from interface org.olat.core.gui.components.form.flexible.FormBaseComponentIdProvider

DISPPREFIX

Method Summary

void	addActionListener(Controller listener, int events)
void	clearError() error is resolved, e.g.
void	doDispatchFormRequest(UserRequest ureq) called if this component is dispatched, e.g.
void	evalFormRequest(UserRequest ureq) called if just the form values must be remembered for the next render process.
int	getAction()
java.util.List	getActionListenersFor(int event)
Component	getComponent() The elements panel to be rendered by the GUI Framework.
Component	getErrorC() a complex "error" message, or a helper wizard to fix the error may be
java.lang.String	getErrorText() This method is used by a form infrastructure provider.
Component	getExampleC() translated example text, wrapped in component
java.lang.String	getExampleText() This method is used by a form infrastructure provider.
Component	getLabelC() label panel of the form item, null if no label provided/rendered
java.lang.String	getLabelText() label panel of the form item, null if no label provided/rendered
java.lang.String	getName() The form item's name within an manageing form container.
Form	getRootForm() a form item always has a root container where it belongs to.
Translator	getTranslator()
java.lang.Object	getUserObject()
boolean	hasError()
boolean	hasExample()
boolean	hasFocus() true if this element tries to get focus.
boolean	hasLabel()
boolean	isEnabled() true if item is marked as editable.
boolean	isMandatory() true if the form item should contain a (valid) value.
boolean	isVisible() true if form item was marked visible.
void	reset() reset the data in the field to a initial/predefined value.
void	setEnabled(boolean isEnabled) item is enabled/disabled, e.g.
void	setErrorComponent(FormItem errorFormItem, FormLayouter container) a complex "error" message, or a helper wizard to fix the error. It must be a form item itself, that starting the fixing workflow let the surrounding form evaluate (intermediate save values). Typically a FormLink is used here to start a workflow in a modal dialog. Use showError(true) for the visibility of the error.
void	setErrorKey(java.lang.String errorKey, java.lang.String[] params) Sets the i18n key for this form item's error message and displays the error message if showErro(true) is set.
void	setExampleKey(java.lang.String exampleKey, java.lang.String[] params) key for example with params to fill
void	setFocus(boolean hasFocus) true if the element should (try to) get focus, false is default
void	setLabel(java.lang.String labelkey, java.lang.String[] params) Key to be translated with the form translator and placed in the label panel.
FormItem	setLabelComponent(FormItem labelComponent, FormItemContainer formLayout) see setErrorComponent for comments
void	setMandatory(boolean isMandatory) Shows a mandatory icon next to this form item.
void	setRootForm(Form rootForm)
void	setTranslator(Translator translator)
void	setUserObject(java.lang.Object userObject)
void	setVisible(boolean isVisible) item, label, example, error get not visible
void	showError(boolean show)
void	showExample(boolean show)
void	showLabel(boolean show)
void	validate(java.util.List validationResults) validate the data in the field, create error messages or update any component.

Methods inherited from interface org.olat.core.gui.components.form.flexible.FormBaseComponentIdProvider

getFormDispatchId

Field Detail

ERRORC

static final java.lang.String ERRORC

See Also:

Constant Field Values

EXAMPLEC

static final java.lang.String EXAMPLEC

See Also:

Constant Field Values

LABELC

static final java.lang.String LABELC

See Also:

Constant Field Values

Method Detail

evalFormRequest

void evalFormRequest(UserRequest ureq)

called if just the form values must be remembered for the next render process. Do not validate data and create error messages.

This method must be implemented by a specialised form item provider.

Parameters:

ureq -

dispatchIDs -

nextPos -

validate

void validate(java.util.List validationResults)

validate the data in the field, create error messages or update any component.

This method must be implemented by a specialised form item provider.

reset

void reset()

reset the data in the field to a initial/predefined value. This method is called if in a form a reset request is issued. It is the counterpart to the validate call which

setFocus

void setFocus(boolean hasFocus)

true if the element should (try to) get focus, false is default

Parameters:

hasFocus -

hasFocus

boolean hasFocus()

true if this element tries to get focus.

Returns:

doDispatchFormRequest

void doDispatchFormRequest(UserRequest ureq)

called if this component is dispatched, e.g. was clicked (double clicked, ...)

Please note, that the caller is not the GUI Framework but the form items manageing class. A default and exemplary implemention is Form.

This method must be implemented by a specialised form item provider.

Parameters:

ureq -

dispatchIDs -

nextPos -

getName

java.lang.String getName()

The form item's name within an manageing form container. This has nothing to do with a name displayed on the screen to the user.
The default implementation FormItemImpl uses the name to make the element available in the velocity container.

This method is used by a form infrastructure provider.

Returns:

getComponent

Component getComponent()

The elements panel to be rendered by the GUI Framework.

Returns:

getRootForm

Form getRootForm()

a form item always has a root container where it belongs to. The root container is responsible for the opening and closing HTML FORM tag.

This method must be implemented by a specialised form item provider.

Returns:

getLabelC

Component getLabelC()

label panel of the form item, null if no label provided/rendered

This method is used by a form infrastructure provider.

Returns:

getLabelText

java.lang.String getLabelText()

label panel of the form item, null if no label provided/rendered

This method is used by a form infrastructure provider.

Returns:

setLabel

void setLabel(java.lang.String labelkey,
              java.lang.String[] params)

Key to be translated with the form translator and placed in the label panel.

Parameters:

labelkey - i18n key

params - i18n key parameters

setLabelComponent

FormItem setLabelComponent(FormItem labelComponent,
                           FormItemContainer formLayout)

see setErrorComponent for comments

Parameters:

labelComponent -

layout -

isMandatory

boolean isMandatory()

true if the form item should contain a (valid) value.

Returns:

setMandatory

void setMandatory(boolean isMandatory)

Shows a mandatory icon next to this form item. This is only a GUI cue, it does not activate any validators. It is in the developer's responsibility to validate the form.

Parameters:

isMandatory - Whether this form item should have a mandatory icon.

setErrorKey

void setErrorKey(java.lang.String errorKey,
                 java.lang.String[] params)

Sets the i18n key for this form item's error message and displays the error message if showErro(true) is set.

Parameters:

errorKey - i18n key for the error message.

params - Additional error message contents.

setErrorComponent

void setErrorComponent(FormItem errorFormItem,
                       FormLayouter container)

a complex "error" message, or a helper wizard to fix the error.
It must be a form item itself, that starting the fixing workflow let the surrounding form evaluate (intermediate save values).
Typically a FormLink is used here to start a workflow in a modal dialog.
Use showError(true) for the visibility of the error.

Parameters:

errorFormItem -

container - the container containing the form item which has the error

getErrorC

Component getErrorC()

a complex "error" message, or a helper wizard to fix the error may be

This method is used by a form infrastructure provider. null

getErrorText

java.lang.String getErrorText()

This method is used by a form infrastructure provider.

Returns:

getExampleC

Component getExampleC()

translated example text, wrapped in component

This method is used by a form infrastructure provider.

Returns:

getExampleText

java.lang.String getExampleText()

This method is used by a form infrastructure provider.

Returns:

setExampleKey

void setExampleKey(java.lang.String exampleKey,
                   java.lang.String[] params)

key for example with params to fill

Parameters:

exampleKey, - null to clear example

params, - may be null

setTranslator

void setTranslator(Translator translator)

Parameters:

translator -

getTranslator

Translator getTranslator()

Returns:

setVisible

void setVisible(boolean isVisible)

item, label, example, error get not visible

Parameters:

isVisible -

isVisible

boolean isVisible()

true if form item was marked visible.

setEnabled

void setEnabled(boolean isEnabled)

item is enabled/disabled, e.g. editable/read only in contrast to setVisible this does NOT DISABLE label, example, error!

Parameters:

isEnabled -

isEnabled

boolean isEnabled()

true if item is marked as editable.

Returns:

hasError

boolean hasError()

Returns:

hasLabel

boolean hasLabel()

Returns:

hasExample

boolean hasExample()

Returns:

setRootForm

void setRootForm(Form rootForm)

Parameters:

rootForm -

showLabel

void showLabel(boolean show)

Parameters:

show -

showError

void showError(boolean show)

Parameters:

show -

clearError

void clearError()

error is resolved, e.g. hasError() should return false and the error component gets invisible (and resetted)

showExample

void showExample(boolean show)

Parameters:

show -

addActionListener

void addActionListener(Controller listener,
                       int events)

Parameters:

listener -

events -

getActionListenersFor

java.util.List getActionListenersFor(int event)

Parameters:

event -

Returns:

getAction

int getAction()

Returns:

setUserObject

void setUserObject(java.lang.Object userObject)

Parameters:

userObject -

getUserObject

java.lang.Object getUserObject()

Returns: