Package org.apache.wicket.markup.html.list

Class ListView<T>

java.lang.Object
org.apache.wicket.Component
org.apache.wicket.MarkupContainer
org.apache.wicket.markup.html.WebMarkupContainer
org.apache.wicket.markup.repeater.AbstractRepeater
org.apache.wicket.markup.html.list.ListView<T>
Type Parameters:
T - type of elements contained in the model's list
All Implemented Interfaces:
Serializable, Iterable<Component>, IEventSink, IEventSource, IFeedbackContributor, IConverterLocator, IMetadataContext<Serializable,Component>, IHeaderContributor, IRequestableComponent, IHierarchical<Component>, IClusterable
Direct Known Subclasses:
PageableListView, PropertyListView
public abstract class ListView<T> extends AbstractRepeater
A ListView is a repeater that makes it easy to display/work with Lists. However, there are situations where it is necessary to work with other collection types, for repeaters that might work better with non-list or database-driven collections see the org.apache.wicket.markup.repeater package. Also notice that in a list the item's uniqueness/primary key/id is identified as its index in the list. If this is not the case you should either override getListItemModel(IModel, int) to return a model that will work with the item's true primary key, or use a different repeater that does not rely on the list index. A ListView holds ListItem children. Items can be re-ordered and deleted, either one at a time or many at a time.

Example: 

 <tbody>
   <tr wicket:id="rows" class="even">
     <td><span wicket:id="id">Test ID</span></td>
     ...

Though this example is about a HTML table, ListView is not at all limited to HTML tables. Any kind of list can be rendered using ListView.

The related Java code: 

 add(new ListView<UserDetails>("rows", listData)
 {
        public void populateItem(final ListItem<UserDetails> item)
        {
                final UserDetails user = item.getModelObject();
                item.add(new Label("id", user.getId()));
        }
 });

NOTE: When you want to change the default generated markup it is important to realize that the ListView instance itself does not correspond to any markup, however, the generated ListItems do.
This means that methods like Component.setRenderBodyOnly(boolean) and Component.add(org.apache.wicket.behavior.Behavior...) should be invoked on the ListItem that is given in populateItem(ListItem) method.

WARNING: though you can nest ListViews within Forms, you HAVE to set the setReuseItems property to true in order to have validation work properly. By default, setReuseItems is false, which has the effect that ListView replaces all child components by new instances. The idea behind this is that you always render the fresh data, and as people usually use ListViews for displaying read-only lists (at least, that's what we think), this is good default behavior.
However, as the components are replaced before the rendering starts, the search for specific messages for these components fails as they are replaced with other instances. Another problem is that 'wrong' user input is kept as (temporary) instance data of the components. As these components are replaced by new ones, your user will never see the wrong data when setReuseItems is false.

Author:
Jonathan Locke, Juergen Donnerstag, Johan Compagner, Eelco Hillenius
See Also:

  • Constructor Details

  • Method Details

    • getList

      public final List<T> getList()
      Gets the list of items in the listView. This method is final because it is not designed to be overridden. If it were allowed to be overridden, the values returned by getModelObject() and getList() might not coincide.
      Returns:
      The list of items in this list view.

    • getReuseItems

      public boolean getReuseItems()
      If true re-rendering the list view is more efficient if the windows doesn't get changed at all or if it gets scrolled (compared to paging). But if you modify the listView model object, then you must manually call listView.removeAll() in order to rebuild the ListItems. If you nest a ListView in a Form, ALLWAYS set this property to true, as otherwise validation will not work properly.
      Returns:
      Whether to reuse items

    • getStartIndex

      public final int getStartIndex()
      Get index of first cell in page. Default is: 0.
      Returns:
      Index of first cell in page. Default is: 0

    • getViewSize

      public int getViewSize()
      Based on the model object's list size, firstIndex and view size, determine what the view size really will be. E.g. default for viewSize is Integer.MAX_VALUE, if not set via setViewSize(). If the underlying list has 10 elements, the value returned by getViewSize() will be 10 if startIndex = 0.
      Returns:
      The number of items to be populated and rendered.

    • moveDownLink

      public final Link<Void> moveDownLink(String id, ListItem<T> item)
      Returns a link that will move the given item "down" (towards the end) in the listView.
      Parameters:
      id - Name of move-down link component to create
      item -
      Returns:
      The link component

    • moveUpLink

      public final Link<Void> moveUpLink(String id, ListItem<T> item)
      Returns a link that will move the given item "up" (towards the beginning) in the listView.
      Parameters:
      id - Name of move-up link component to create
      item -
      Returns:
      The link component

    • removeLink

      public final Link<Void> removeLink(String id, ListItem<T> item)
      Returns a link that will remove this ListItem from the ListView that holds it.
      Parameters:
      id - Name of remove link component to create
      item -
      Returns:
      The link component

    • setList

      public ListView<T> setList(List<T> list)
      Sets the model as the provided list and removes all children, so that the next render will be using the contents of the model.
      Parameters:
      list - The list for the new model. The list must implement Serializable.
      Returns:
      This for chaining

    • setReuseItems

      public ListView<T> setReuseItems(boolean reuseItems)
      If true re-rendering the list view is more efficient if the windows doesn't get changed at all or if it gets scrolled (compared to paging). But if you modify the listView model object, than you must manually call listView.removeAll() in order to rebuild the ListItems. If you nest a ListView in a Form, always set this property to true, as otherwise validation will not work properly.
      Parameters:
      reuseItems - Whether to reuse the child items.
      Returns:
      this

    • setStartIndex

      public ListView<T> setStartIndex(int startIndex)
      Set the index of the first item to render
      Parameters:
      startIndex - First index of model object's list to display
      Returns:
      This

    • setViewSize

      public ListView<T> setViewSize(int size)
      Define the maximum number of items to render. Default: render all.
      Parameters:
      size - Number of items to display
      Returns:
      This

    • getListItemModel

      protected IModel<T> getListItemModel(IModel<? extends List<T>> listViewModel, int index)
      Subclasses may provide their own ListItemModel with extended functionality. The default ListItemModel works fine with mostly static lists where index remains valid. In cases where the underlying list changes a lot (many users using the application), it may not longer be appropriate. In that case your own ListItemModel implementation should use an id (e.g. the database' record id) to identify and load the list item model object.
      Parameters:
      listViewModel - The ListView's model
      index - The list item index
      Returns:
      The ListItemModel created

    • newItem

      protected ListItem<T> newItem(int index, IModel<T> itemModel)
      Create a new ListItem for list item at index.
      Parameters:
      index -
      itemModel - object in the list that the item represents
      Returns:
      ListItem

    • onPopulate

      protected final void onPopulate()
      Description copied from class: AbstractRepeater
      Callback to let the repeater know it should populate itself with its items.
      Specified by:
      onPopulate in class AbstractRepeater
      See Also:

    • onBeginPopulateItem

      protected void onBeginPopulateItem(ListItem<T> item)
      Comes handy for ready made ListView based components which must implement populateItem() but you don't want to lose compile time error checking reminding the user to implement abstract populateItem().
      Parameters:
      item -

    • populateItem

      protected abstract void populateItem(ListItem<T> item)
      Populate a given item.

      be careful to add any components to the list item. So, don't do: 

       add(new Label("foo", "bar"));
      but: 
       item.add(new Label("foo", "bar"));

      Parameters:
      item - The item to populate

    • renderChild

      protected final void renderChild(Component child)
      Description copied from class: AbstractRepeater
      Render a single child. This method can be overridden to modify how a single child component is rendered.
      Overrides:
      renderChild in class AbstractRepeater
      Parameters:
      child - Child component to be rendered
      See Also:

    • renderItem

      protected void renderItem(ListItem<?> item)
      Render a single item.
      Parameters:
      item - The item to be rendered

    • renderIterator

      protected Iterator<Component> renderIterator()
      Description copied from class: AbstractRepeater
      Returns an iterator for the collection of child components to be rendered. Users can override this to change order of rendered children.
      Specified by:
      renderIterator in class AbstractRepeater
      Returns:
      iterator over child components to be rendered
      See Also:

    • getModel

      public final IModel<? extends List<T>> getModel()
      Gets model
      Returns:
      model

    • setModel

      public final void setModel(IModel<? extends List<T>> model)
      Sets model
      Parameters:
      model -

    • getModelObject

      public final List<T> getModelObject()
      Gets model object
      Returns:
      model object

    • setModelObject

      public final void setModelObject(List<T> object)
      Sets model object
      Parameters:
      object -