Package com.orchestranetworks.ui

# Class UITableFilter

java.lang.Object
com.orchestranetworks.ui.UITableFilter

public abstract class UITableFilter extends Object
Abstract class for implementing a user interface filter on a table.

### Definition in the data model

Filters are specified in the same parent element as `osd:table`, for example:

>      <xs:annotation>
>        <xs:appinfo>
>          <osd:table>...</osd:table>
>          <osd:uiFilter class="com.foo.MyUIFilter1">
>            <label>Label of filter 1</label>
>          </osd:uiFilter>
>          <osd:uiFilter class="com.foo.MyUIFilter2">
>            <label>Default label of filter 2</label>
>            <label xml:lang="fr">Libellé en français du filtre 2</label>
>          </osd:uiFilter>
>        <xs:appinfo>
>      </xs:annotation>

where `com.foo.MyUIFilter1` and `com.foo.MyUIFilter2` are the fully qualified name of classes implementing this interface. The declaration may also use parameters:

>      <osd:uiFilter class="com.foo.MyUIFilter3">
>          <param1>...</param1>
>          <param2>...</param2>
>      </osd:uiFilter>

where `param1` and `param2` are JavaBean properties of `com.foo.MyUIFilter3` class.

For more information, see the JavaBean specification.

### Life cycle

1. When the data model is loaded, the declaration is checked:

   Each specified filter class is instantiated through its default constructor and, if defined, the JavaBean property setters are called (in the example above, `setParam1(...)` and `setParam2(...)`).

2. For each EBX® user interface session, the instantiation and initialization process described above is performed. Each HTTP session maintains its own filter instances. Consequently, when the user performs interactions, each filter is able to keep its own state (the user selection) throughout the session.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UITableFilter()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `addForEdit(UITableFilterResponseContext aResponse)`
  Adds HTML or DHTML to the filter pane, to allow the user to set the filter.
  `void`
  `addForPrint(UITableFilterResponseContext aResponse)`
  Deprecated.
  Use `addForEdit(UITableFilterResponseContext)` instead.
  `UserMessage`
  `getLabel()`
  Returns the label of this filter.
  `abstract void`
  `handleApply(UITableFilterRequestContext aContext)`
  Handles the request when the "Apply filter" button is selected.
  `void`
  `handleReset()`
  This method is invoked when the "Reset" button is selected or when a custom view is applied to the table.
  `void`
  `handleSelect(UITableFilterRequestContext aContext)`
  Deprecated.
  From v5.0.0, all filters are displayed on the screen.
  `boolean`
  `hasFilterToApply()`
  If this method returns `true`, a check box is displayed in the filter title bar, allowing the user to easily apply or remove this filter.
  `boolean`
  `isResetButtonEnabled()`
  Returns whether the "Reset" button is to be displayed.
  `void`
  `setLabel(UserMessage aUserMessage)`
  `final void`
  `setLabel(String aLabel)`
  Sets the default label of this filter.
  `final void`
  `setLabel(Locale aLocale, String aLabel)`
  Sets the label of this filter for the specified locale.
  `final void`
  `setLabelUserMessage(UserMessageString aUserMessage)`
  Sets the labels of this filter for the specified locales by looking in the `UserMessageString`.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### UITableFilter

    public UITableFilter()

- ## Method Details

  - ### addForEdit

    public abstract void addForEdit(UITableFilterResponseContext aResponse)
    Adds HTML or DHTML to the filter pane, to allow the user to set the filter.

    When this method is called, the container has already added a `<form ...>` tag. After this method has returned, a closing `</form>` tag is added. Therefore, the implementation of this method only needs to insert the HTML components within.

    ##### Example

    The following code adds a checkbox:

         aResponse.add("<input type=\"checkbox\" name=\"item\" style=\"border: 0;\" value=\"P4\" ");
         if (selection.contains("P4"))
                aResponse.add(" checked");
         aResponse.add("> Label of P4<br>");

    ##### Constraints

    - HTML conformance – The HTML specified is already enclosed in an HTML form by the container.
    - Avoid any name conflicts with EBX® user interface – For an HTML component, its name and its id must use neither the name `requestID`
    , nor a name beginning with `onw` (in lower or upper case).

  - ### addForPrint

    @Deprecated public void addForPrint(UITableFilterResponseContext aResponse)
    Deprecated.
    Use `addForEdit(UITableFilterResponseContext)` instead.
    Adds HTML content for displaying information about the current filter's settings on a printable page.

    The default implementation redirects to `addForEdit(UITableFilterResponseContext)`. For production use, it is recommended to implement this method appropriately.

  - ### handleApply

    public abstract void handleApply(UITableFilterRequestContext aContext)
    Handles the request when the "Apply filter" button is selected.

    The implementation of this method should:

    1. Take into account the HTTP parameters included in the request (specified by the implementation of `addForEdit(UITableFilterResponseContext)`);
    2. Set the state of this instance accordingly;
    3. Build the appropriate filter and call `UITableFilterRequestContext.setTableFilter(AdaptationFilter)`.

  - ### handleSelect

    @Deprecated public void handleSelect(UITableFilterRequestContext aContext)
    Deprecated.
    From v5.0.0, all filters are displayed on the screen.
    Handles the request when this filter is selected from the list of filters.

    The implementation of this method should take into account the internal state of this instance in order to build the appropriate `AdaptationFilter` and set it by calling `UITableFilterRequestContext.setTableFilter(AdaptationFilter)`.

    Default implementation does nothing.

  - ### isResetButtonEnabled

    public boolean isResetButtonEnabled()
    Returns whether the "Reset" button is to be displayed. By clicking the "Reset" button, the method `handleReset()` is called.

    Default returned value is `false`, to be overridden if necessary.

    Returns:
      `true` if the "Reset" button is to be displayed, `false` otherwise.
    See Also:
      - `handleReset()`

  - ### handleReset

    public void handleReset()
    This method is invoked when the "Reset" button is selected or when a custom view is applied to the table. The presence of the "Reset" button depends on the method `isResetButtonEnabled()`.

    Default implementation does nothing. If overridden, this method should reset this instance to its initial state.

    See Also:
      - `isResetButtonEnabled()`

  - ### hasFilterToApply

    public boolean hasFilterToApply()
    If this method returns `true`, a check box is displayed in the filter title bar, allowing the user to easily apply or remove this filter. Thus, it is recommended to return `false` if no filtering is defined by the user interface.

    Default returned value is `true`, to be overridden if necessary.

    Returns:
      `true` if the filter has criteria to apply, `false` otherwise.
    Since:
      5.2.0

  - ### getLabel

    public UserMessage getLabel()
    Returns the label of this filter.

  - ### setLabel

    public final void setLabel(Locale aLocale, String aLabel)
    Sets the label of this filter for the specified locale.

  - ### setLabelUserMessage

    public final void setLabelUserMessage(UserMessageString aUserMessage)
    Sets the labels of this filter for the specified locales by looking in the `UserMessageString`.

  - ### setLabel

    public final void setLabel(String aLabel)
    Sets the default label of this filter.

  - ### setLabel

    public void setLabel(UserMessage aUserMessage)