com.holonplatform.vaadin.flow.components

## Interface ItemListing<T,P>

- Type Parameters:
    `T` - Item type
    `P` - Item property type
  All Superinterfaces:
    HasComponent, com.vaadin.flow.component.HasElement, ItemSet, Selectable<T>, Serializable
  All Known Subinterfaces:
    BeanListing<T>, PropertyListing

      public interface ItemListing<T,P>
      extends ItemSet, Selectable<T>, HasComponent

  A component to display a set of items as tabular data, using the item properties as column ids.
  Since:
    5.2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `ItemListing.EditorCancelListener<T,P>` An event listener for editor cancel events.
    `static interface` | `ItemListing.EditorCloseListener<T,P>` An event listener for editor close events.
    `static interface` | `ItemListing.EditorComponentGroup<P,T>` A `BoundComponentGroup` which represents the listing item editor `Input`s and their property bindings.
    `static interface` | `ItemListing.EditorOpenListener<T,P>` An event listener for editor open events.
    `static interface` | `ItemListing.EditorSaveListener<T,P>` An event listener for editor save events.
    `static interface` | `ItemListing.ItemEditorEvent<T,P>` Editor event.
    `static interface` | `ItemListing.ItemListingCell` An `ItemListing` section row cell handler.
    `static interface` | `ItemListing.ItemListingRow<P>` An `ItemListing` section row handler.
    `static interface` | `ItemListing.ItemListingSection<P,R extends ItemListing.ItemListingRow<P>>` `ItemListing` section handler for header and footer configuration.

    - ### Nested classes/interfaces inherited from interface com.holonplatform.vaadin.flow.components.Selectable

      `Selectable.SelectionEvent<T>, Selectable.SelectionListener<T>, Selectable.SelectionMode`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addAdditionalItem(T item)` Add an additional item to the listing.
    `void` | `cancelEditing()` If the listing `isEditable()`, closes the editor discarding any unsaved changes.
    `void` | `editItem(T item)` If the listing `isEditable()`, opens the editor interface for the provided item.
    `List<T>` | `getAdditionalItems()` Get the current additional items, if any.
    `Optional<String>` | `getColumnHeader(P property)` Get the header text of the column identified by given property id, if available.
    `List<com.vaadin.flow.data.provider.QuerySortOrder>` | `getColumnSorts()` Get the current column sorts, if any.
    `com.vaadin.flow.data.provider.DataProvider<T,?>` | `getDataProvider()` Get the `DataProvider` used by this item listing as data source.
    `Optional<ItemListing.ItemListingSection<P,? extends ItemListing.ItemListingRow<P>>>` | `getFooter()` Get the item listing footer section rows handler, if available.
    `Optional<ItemListing.ItemListingSection<P,? extends ItemListing.ItemListingRow<P>>>` | `getHeader()` Get the item listing header section rows handler, if available.
    `List<P>` | `getVisibleColumns()` Gets the listing visible columns, in the order thay are displayed.
    `boolean` | `isEditable()` Gets whether this listing is editable.
    `Optional<T>` | `isEditing()` Checks whether the listing is in edit mode.
    `boolean` | `isFrozen()` Get whether the listing is frozen.
    `boolean` | `isItemDetailsVisible(T item)` Gets whether the row details component for given `item` is visible.
    `void` | `refreshEditingItem()` If the listing `isEditable()`, refreshes the editor components for the current item being edited, if any.
    `void` | `refreshItem(T item)` Refresh given item in data source
    `boolean` | `removeAdditionalItem(T item)` Remove an additional item from the listing.
    `void` | `removeAdditionalItems()` Remove all the additional items from the listing.
    `boolean` | `saveEditingItem()` If the listing `isEditable()`, saves the item which is currently in editing, if any.
    `void` | `setColumnVisible(P property, boolean visible)` Show or hide the column which corresponds to given `property` id.
    `void` | `setFrozen(boolean frozen)` Set whether the listing is frozen.
    `void` | `setItemDetailsVisible(T item, boolean visible)` Set whether to show the row details component for given `item`.
    `void` | `setSelectionMode(Selectable.SelectionMode selectionMode)` Set the listing selection mode
    `default void` | `sort(ItemSort<P>... sorts)` Sort the listing using given `ItemSort` directives.
    `void` | `sort(List<ItemSort<P>> sorts)` Sort the listing using given `ItemSort` directives.

    - ### Methods inherited from interface com.holonplatform.vaadin.flow.components.ItemSet

      `refresh`

    - ### Methods inherited from interface com.holonplatform.vaadin.flow.components.Selectable

      `addSelectionListener, deselect, deselectAll, getFirstSelectedItem, getSelectedItems, getSelectionMode, isSelected, select`

    - ### Methods inherited from interface com.holonplatform.vaadin.flow.components.HasComponent

      `create, getComponent, getElement, hasEnabled, hasLabel, hasSize, hasStyle, hasValidation, isVisible, setVisible`

- - ### Method Detail

    - #### getVisibleColumns

          List<P> getVisibleColumns()

      Gets the listing visible columns, in the order thay are displayed.
      Returns:
        The listing visible columns references, represented using the property id

    - #### setColumnVisible

          void setColumnVisible(P property,
                                boolean visible)

      Show or hide the column which corresponds to given `property` id.
      Parameters:
        `property` - The property which represents the column (not null)
        `visible` - `true` to show the column, `false` to hide it
      Throws:
        `IllegalArgumentException` - If the specified property is not bound to any column

    - #### getColumnHeader

          Optional<String> getColumnHeader(P property)

      Get the header text of the column identified by given property id, if available.
      Parameters:
        `property` - The column property id (not null)
      Returns:
        Optional header text of the column identified by given property id
      Since:
        5.2.2

    - #### isItemDetailsVisible

          boolean isItemDetailsVisible(T item)

      Gets whether the row details component for given `item` is visible.
      Parameters:
        `item` - Item to check whether the row details component is visible (not null)
      Returns:
        `true` if row details component is visible for given item, `false` otherwise

    - #### setItemDetailsVisible

          void setItemDetailsVisible(T item,
                                     boolean visible)

      Set whether to show the row details component for given `item`.
      Parameters:
        `item` - Item for which to show or hide the row details (not null)
        `visible` - `true` to show the row details component, `false` to hide it

    - #### sort

          default void sort(ItemSort<P>... sorts)

      Sort the listing using given `ItemSort` directives.
      Parameters:
        `sorts` - The item sorts to apply

    - #### sort

          void sort(List<ItemSort<P>> sorts)

      Sort the listing using given `ItemSort` directives.
      Parameters:
        `sorts` - The item sorts to apply

    - #### setSelectionMode

          void setSelectionMode(Selectable.SelectionMode selectionMode)

      Set the listing selection mode
      Parameters:
        `selectionMode` - The selection mode to set (not null)

    - #### refreshItem

          void refreshItem(T item)

      Refresh given item in data source
      Parameters:
        `item` - Item to refresh (not null)

    - #### getHeader

          Optional<ItemListing.ItemListingSection<P,? extends ItemListing.ItemListingRow<P>>> getHeader()

      Get the item listing header section rows handler, if available.
      Returns:
        Optional item listing header handler

    - #### getFooter

          Optional<ItemListing.ItemListingSection<P,? extends ItemListing.ItemListingRow<P>>> getFooter()

      Get the item listing footer section rows handler, if available.
      Returns:
        Optional item listing footer handler

    - #### isEditable

          boolean isEditable()

      Gets whether this listing is editable.

      When a listing is editable, the `editItem(Object)` and `cancelEditing()` methods can be used to control item editing.

      Returns:
        Whether this listing is editable

    - #### isEditing

          Optional<T> isEditing()

      Checks whether the listing is in edit mode.
      Returns:
        If the listing is in edit mode, returns the currently item in editing. An empty Optional otherwise.

    - #### editItem

          void editItem(T item)

      If the listing `isEditable()`, opens the editor interface for the provided item.
      Parameters:
        `item` - the item to edit (not null) if already editing a different item in buffered mode
      Throws:
        `IllegalArgumentException` - if the `item` is not in the backing data provider
        `IllegalStateException` - If the listing is not editable

    - #### cancelEditing

          void cancelEditing()

      If the listing `isEditable()`, closes the editor discarding any unsaved changes.
      Throws:
        `IllegalStateException` - If the listing is not editable

    - #### saveEditingItem

          boolean saveEditingItem()

      If the listing `isEditable()`, saves the item which is currently in editing, if any.

      When the listing editor is in buffered mode, this method will validate the item and will save any changes made to the editor fields to the edited item if all validators pass. If the write fails then there will be no events and the editor will stay open.

      A successful write will fire an editor `save` event and close the editor that will fire an editor `close` event .

      NOTE: When the listing editor is not in buffered mode, calling save will have no effect and always return `false`.

      Returns:
        `true` if save succeeded, `false` otherwise
      Throws:
        `IllegalStateException` - If the listing is not editable

    - #### refreshEditingItem

          void refreshEditingItem()

      If the listing `isEditable()`, refreshes the editor components for the current item being edited, if any.

      This is useful when the state of the item is changed while the editor is open.

      Throws:
        `IllegalStateException` - If the listing is not editable

    - #### getDataProvider

          com.vaadin.flow.data.provider.DataProvider<T,?> getDataProvider()

      Get the `DataProvider` used by this item listing as data source.
      Returns:
        The `DataProvider` used as data source
      Since:
        5.2.2

    - #### getColumnSorts

          List<com.vaadin.flow.data.provider.QuerySortOrder> getColumnSorts()

      Get the current column sorts, if any.
      Returns:
        The current column sorts, empty if none
      Since:
        5.2.3

    - #### isFrozen

          boolean isFrozen()

      Get whether the listing is frozen.

      When the listing is frozen, it never shows any item and no fetch is performed from the data provider.

      Returns:
        Whether the listing is frozen
      Since:
        5.2.2

    - #### setFrozen

          void setFrozen(boolean frozen)

      Set whether the listing is frozen.

      When the listing is frozen, it never shows any item and no fetch is performed from the data provider.

      When the `ItemSet.refresh()` method is called, the frozen state is automatically set to `false`.

      Parameters:
        `frozen` - Whether the listing is frozen
      Since:
        5.2.2

    - #### getAdditionalItems

          List<T> getAdditionalItems()

      Get the current additional items, if any.

      Additional items are provided in addition to the ones returned by the concrete data provider, for example from a backend service. They are always provided before any other item, and do not take part in filters and sorts.

      Returns:
        The additional items, in the order they were added. An empty list if none. The list is not modifiable.
      Since:
        5.2.2
      See Also:
        `addAdditionalItem(Object)`

    - #### addAdditionalItem

          void addAdditionalItem(T item)

      Add an additional item to the listing.

      Additional items are provided in addition to the ones returned by the concrete data provider, for example from a backend service. They are always provided before any other item, and do not take part in filters and sorts.

      The additional items should be used, for example, to edit item values before saving into the backend. Then they should be removed from the listing.

      NOTE: Additional items are identified in the same way than any other item, using the `DataProvider.getId(Object)` method. So the id providing logic should be consistent with any other item.

      Parameters:
        `item` - The item to add (not null)
      See Also:
        `removeAdditionalItem(Object)`

    - #### removeAdditionalItem

          boolean removeAdditionalItem(T item)

      Remove an additional item from the listing.
      Parameters:
        `item` - The item to remove (not null)
      Returns:
        `true` if given item was an additional item and it's been removed, `false` otherwise
      See Also:
        `addAdditionalItem(Object)`, `removeAdditionalItems()`

    - #### removeAdditionalItems

          void removeAdditionalItems()

      Remove all the additional items from the listing.
      See Also:
        `addAdditionalItem(Object)`

Copyright © 2019 The Holon Platform. All rights reserved.