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

Class 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:
    BreadCrumbBar.BreadCrumbsListView, 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:
    Serialized Form

    • Method Detail

      • 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

      • 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

      • renderItem

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

      • 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 -