Package com.orchestranetworks.ui

Class UIBeanEditor

  • Direct Known Subclasses:
    UIBeanEditorV4
    @Deprecated
public abstract class UIBeanEditor
extends Object
    Deprecated.
    From 5.8.0, please use the new API UICustomWidget instead.
    Abstract class for customizing UI beans on master data. A UI bean can display an element differently and/or modify its value.

    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: 

     <xs:annotation>
   <xs:appinfo>
     <osd:uiBean class="com.foo.MyUIBean" />
   </xs:appinfo>
 </xs:annotation>
    where com.foo.MyUIBean is the fully qualified name of a class implementing this interface. The declaration may also use parameters: 
     <osd:uiBean class="com.foo.MyUIBean">
        <param1>...</param1>
        <param2>...</param2>
 </osd:uiBean>
    where 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

    1. 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(...) and setParam2(...)). Then, one of the methods addFor... is called.
    2. 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 Detail

      • UIBeanEditor

        public UIBeanEditor()
        Deprecated.

    • Method Detail

      • addForDisplay

        public abstract 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.

        If the current element is an aggregated list, the method addList(UIResponseContext) is invoked first.

      • addForDisplayInTable

        public 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.

        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:
        addForDisplay(UIResponseContext)

      • addForEdit

        public 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.

        If the current element is an aggregated list, the method addList(UIResponseContext) is first invoked.

      • addForEditInTable

        public 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.

        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.

        See Also:
        addForDisplayInTable(UIResponseContext), addForEdit(UIResponseContext)

      • addForNull

        public 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.

        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 class UICSSClasses.TEXT.VALUE_ND.

        See Also:
        getMessageForSettingNull(UIResponseContext), getMessageForSettingValue(UIResponseContext)

      • addForNullInTable

        public 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.

        Default implementation displays nothing (an empty cell).

        Since:
        5.2.3

      • getMessageForSettingNull

        public UserMessage getMessageForSettingNull​(UIResponseContext aResponse)
        Deprecated.
        Returns the message to display in the user interface when setting the value of the associated element to null .

        Default implementation returns a standard message for this action.

      • getMessageForSettingValue

        public UserMessage 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.

        Default implementation returns a standard message for this action.

      • shallValidateInput

        public boolean shallValidateInput​(UIRequestContext aRequest)
        Deprecated.
        Returns true if the user input associated with this editor will be validated; returns false 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:

        1. This method is invoked and decides whether the remaining steps below are to be invoked (it can also itself perform validation tasks).
        2. 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 the UIResponseContext.addUI...() methods.
        3. If this method returns true: the method validateInput() is invoked. It can, for example, perform user interface-specific checks.
        4. The constraints defined by data model nodes are executed, potentially adding their own error messages.
        5. 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:
        validateInput(UIRequestContext)

      • validateInput

        public void validateInput​(UIRequestContext aRequest)
        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 returned true, and after the container has automatically validated the input associated with each UI bean that has been added via one of the UIResponseContext.addUI...() methods.

        Default implementation does nothing.

        See Also:
        shallValidateInput(UIRequestContext)

      • validateInputList

        public void validateInputList​(UIRequestContext aRequest)
        Deprecated.
        Does the same thing as validateInput 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:
        addList(UIResponseContext), validateInput(UIRequestContext)