Class UIBeanEditor
- Direct Known Subclasses:
UIBeanEditorV4
Definition in the data model
A specific UI bean can be associated with any element declaration that
is a terminal value or under a terminal value
(see SchemaNode.isTerminalValue()
).
The UI bean must be declared under the element
xs:annotation/xs:appinfo
:
where<xs:annotation> <xs:appinfo> <osd:uiBean class="com.foo.MyUIBean" /> </xs:appinfo> </xs:annotation>
com.foo.MyUIBean
is
the fully qualified name of a class implementing this interface.
The declaration may also use parameters:
where<osd:uiBean class="com.foo.MyUIBean"> <param1>...</param1> <param2>...</param2> </osd:uiBean>
param1
and param2
are JavaBean properties
of com.foo.MyUIBean
class.
For more information, see the JavaBean specification.
Data model definition through BeanInfo
declaration
This option is only necessary to avoid repeating the data model declaration
<osd:uiBean class="...">
each time a JavaBean class is referenced in a data model.
When a data model node is associated with a JavaBean (by attribute osd:class="..."
), it is
possible to specify the association between the JavaBean and its default UIBeanEditor once.
This association is declared using the standard BeanInfo
extension class. This class extends
java.beansSimpleBeanInfo
and must implement the following method:
public BeanDescriptor getBeanDescriptor() { return new BeanDescriptor(MyBean.class, UIMyBean.class); }
Life cycle
- When a session of EBX® generates HTTP response including a bean editor,
the specified class is instantiated using its default constructor and the JavaBean property
setters are called (in the example above,
setParam1(...)
andsetParam2(...)
). Then, one of the methodsaddFor...
is called. - When the page generated in the previous step is submitted and the server receives the
corresponding HTTP request, this is the same instance that is responsible
for handling the parameters of the HTTP request, supplying the data context and checking
its integrity. The user input validation steps are detailed in the method
shallValidateInput(UIRequestContext)
.
Multi-threading
EBX® container ensures that an instance of this class is executed by no more than one thread at a given time.
Behavior for aggregated lists
If this editor is applied to a complex node with maxOccurs > 1
,
it is instantiated for the List
and also for each
element (Occurrence
) in the list.
In order to manage a special behavior for the whole List
,
the developer can override the method addList(UIResponseContext)
such as:
public void addList(UIResponseContext aResponse) { aResponse.add("<ol>"); List theList = (List) aResponse.getValue(); if (theList == null || theList.isEmpty()) theList = new ArrayList(3); for (int i = 0; i < theList.size(); i++) { aResponse.add("<li>"); Path occurrencePath = aResponse.getPathForListOccurrence(i); UIWidget bestMatchingWidget = aResponse.newBestMatching(occurrencePath); aResponse.addWidget(bestMatchingWidget); aResponse.add("</li>"); } aResponse.add("</ol>"); }
In this example, the addList
method will draw a simple HTML
ordered list (<ol> <li>
) and build occurrence paths
to each of its elements.
The aResponse.addWidget(...)
of the best matching widget
for each
occurrence will call addForEdit(UIResponseContext)
or addForDisplay(UIResponseContext)
(depending on the current rendering mode)
of the same UI Bean, but instantiated in the occurrence context.
If addList
is not overridden, addForEdit
or addForDisplay
will be called at the list
and occurrence levels for groups,
and at the occurrence level only for fields
(the whole list is managed by default).
Obviously, it is possible to request the default drawing of the whole list by
using the best matching widget in the addList
method such as:
public void addList(UIResponseContext aResponse) { aResponse.addWidget(aResponse.newBestMatching(Path.SELF)); }
In this case, the user only manages the occurrence level with the methods
addForEdit/Display
.
It is possible to manage input validation at list level by implementing
shallValidateInputList(UIRequestContext)
or validateInputList(UIRequestContext)
.
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract void
addForDisplay
(UIResponseContext aResponse) Deprecated.Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the record form, when the element is read-only.void
addForDisplayInTable
(UIResponseContext aResponse) Deprecated.Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the tabular view.abstract void
addForEdit
(UIResponseContext aResponse) Deprecated.Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the record form.void
addForEditInTable
(UIResponseContext aResponse) Deprecated.Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the tabular view.void
addForNull
(UIResponseContext aResponse) Deprecated.Adds HTML or DHTML content to the HTTP response, so as to display the fact that the current value is not defined (null
) in cases when the field is in read-only mode.void
addForNullInTable
(UIResponseContext aResponse) Deprecated.Adds HTML or DHTML content to the HTTP response, used to denote that the current value is not defined (null
) in the cell of the table view in cases when the field is in read-only mode.void
addForPrint
(UIResponseContext aResponse) Deprecated.This method is no longer invoked.void
addList
(UIResponseContext aResponse) Deprecated.Overrides to add HTML or DHTML content to the HTTP response, so as to display or edit the current element's wholeList
within the record form.getMessageForSettingNull
(UIResponseContext aResponse) Deprecated.Returns the message to display in the user interface when setting the value of the associated element tonull
.getMessageForSettingValue
(UIResponseContext aResponse) Deprecated.Returns the message to display in the user interface when editing a value of the associated element; the action is available when the current value is undefined (null
) in the user interface.boolean
shallValidateInput
(UIRequestContext aRequest) Deprecated.Returnstrue
if the user input associated with this editor will be validated; returnsfalse
if the local user input related to the current UI bean is ignored beyond the execution of this method.boolean
shallValidateInputList
(UIRequestContext aRequest) Deprecated.Same asshallValidateInput
for an aggregated list.void
validateInput
(UIRequestContext aRequest) Deprecated.Offers the opportunity to perform custom validation upon user input.void
validateInputList
(UIRequestContext aRequest) Deprecated.Does the same thing asvalidateInput
for an aggregated list.
-
Constructor Details
-
UIBeanEditor
public UIBeanEditor()Deprecated.
-
-
Method Details
-
addForDisplay
Deprecated.Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the record form, when the element is read-only.If the current element is an aggregated list, the method
addList(UIResponseContext)
is invoked first. -
addForDisplayInTable
Deprecated.Adds HTML or DHTML content to the HTTP response, so as to display the current element's value within the tabular view.The default implementation displays a generic "see details" message.
Limitation: the string displayed in the table will not be taken into account by searches and filters.
- See Also:
-
addForEdit
Deprecated.Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the record form.If the current element is an aggregated list, the method
addList(UIResponseContext)
is first invoked. -
addForEditInTable
Deprecated.Adds HTML or DHTML content to HTTP response, so that the end user can edit the current element's value within the tabular view.Note: Since version 5.0.0, this method is no longer invoked due to a limitation. This method may be reenabled in a future version.
Default implementation does not provide an editor, it displays a generic "see details" message.
-
addForNull
Deprecated.Adds HTML or DHTML content to the HTTP response, so as to display the fact that the current value is not defined (null
) in cases when the field is in read-only mode.Default implementation displays a message indicating that the value of the associated node is undefined.
Known limitations:
This method is ignored if this
UIBeanEditor
is:- defined on a node under a terminal node (other than tables),
- displayed in a tabular view.
Note: Since 5.5.0, the default CSS style for
null
has been removed. It is possible to manually set it by using a<span>
with the CSS classUICSSClasses.TEXT.VALUE_ND
. -
addForNullInTable
Deprecated.Adds HTML or DHTML content to the HTTP response, used to denote that the current value is not defined (null
) in the cell of the table view in cases when the field is in read-only mode.Default implementation displays nothing (an empty cell).
- Since:
- 5.2.3
-
addForPrint
Deprecated.This method is no longer invoked. -
addList
Deprecated.Overrides to add HTML or DHTML content to the HTTP response, so as to display or edit the current element's wholeList
within the record form. This method is invoked only if the current element is an aggregated list (that is, a element withmaxOccurs > 1
).The default implementation of this method is the following:
-
If the current element is a group,
it invokes
addForDisplay(UIResponseContext)
oraddForEdit(UIResponseContext)
according to the rendering mode (backward compatibility). -
Otherwise, if the current element is a field, it invokes the
best matching component.
In this case, this will invoke
addForDisplay(UIResponseContext)
oraddForEdit(UIResponseContext)
of this UI Bean for each occurrence.
It is possible to manage input validation by implementing
shallValidateInputList(UIRequestContext)
orvalidateInputList(UIRequestContext)
.- Since:
- 5.2.0
- See Also:
-
If the current element is a group,
it invokes
-
getMessageForSettingNull
Deprecated.Returns the message to display in the user interface when setting the value of the associated element tonull
.Default implementation returns a standard message for this action.
-
getMessageForSettingValue
Deprecated.Returns the message to display in the user interface when editing a value of the associated element; the action is available when the current value is undefined (null
) in the user interface.Default implementation returns a standard message for this action.
-
shallValidateInput
Deprecated.Returnstrue
if the user input associated with this editor will be validated; returnsfalse
if the local user input related to the current UI bean is ignored beyond the execution of this method.More precisely, user input validation is performed in five steps:
- This method is invoked and decides whether the remaining steps below are to be invoked (it can also itself perform validation tasks).
- If this method returns
true
: the container automatically validates the input associated with each "standard UI bean". A standard UI bean is one that has been added to this editor via one of theUIResponseContext.addUI...()
methods. - If this method returns
true
: the methodvalidateInput()
is invoked. It can, for example, perform user interface-specific checks. - The constraints defined by data model nodes are executed, potentially adding their own error messages.
- Finally, if no errors block the submit, the updates done on the context are committed to the current dataspace. If there are errors, the page is redisplayed with the error messages.
Default implementation always returns
true
.- See Also:
-
shallValidateInputList
Deprecated.Same asshallValidateInput
for an aggregated list.- Since:
- 5.2.0
- See Also:
-
validateInput
Deprecated.Offers the opportunity to perform custom validation upon user input. It typically does so by retrieving the HTTP parameter values from the incoming request and checking them, so as to supply the validation context with new converted values. It can also add error messages.This method is only called if the method
shallValidateInput()
has returnedtrue
, and after the container has automatically validated the input associated with each UI bean that has been added via one of theUIResponseContext.addUI...()
methods.Default implementation does nothing.
- See Also:
-
validateInputList
Deprecated.Does the same thing asvalidateInput
for an aggregated list.If new elements in the list must be added, existing elements deleted, or if the order of elements must be changed, then a new list must be created, fed with elements possibly obtained from the context and finally the new list must be set to the context. The following example builds a list with 3 elements, with one element of each element set programmatically (other elements may have been set by built-in UI components), finally the list order is reversed:
List newList = new ArrayList(); for (int i = 0; i < 3; i++) { Path occurrencePath = aRequest.getPathForListOccurrence(i); String valueInform = aRequest .getOptionalRequestParameterValue(aRequest.getWebNameForPath(occurrencePath.add(FIELD_X))); aRequest.getValueContext(occurrencePath.add(FIELD_X)).setNewValue(valueInform); MyBean occ = (MyBean) aRequest.getValue(occurrencePath); newList.add(occ); } Collections.reverse(newList); aRequest.getValueContext().setNewValue(newList);
It is important to note that setting a new list on the validation context will imply that modifications in the sub-context will be ignored for the committed list, however these modifications remain accessible through direct access on the context (by means of a method such as
aContext.getValueContext(occurrencePath.add(FIELD_X))
).- Since:
- 5.2.0
- See Also:
-
UICustomWidget
instead.