org.apache.wicket.markup.html.list
Class ListView<T>

java.lang.Object
  extended by org.apache.wicket.Component
      extended by org.apache.wicket.MarkupContainer
          extended by org.apache.wicket.markup.html.WebMarkupContainer
              extended by org.apache.wicket.markup.repeater.AbstractRepeater
                  extended by org.apache.wicket.markup.html.list.ListView<T>
Type Parameters:
T - Model object type
All Implemented Interfaces:
Serializable, Iterable<Component>, IEventSink, IEventSource, IConverterLocator, 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

Field Summary
 
Fields inherited from class org.apache.wicket.Component
ENABLE, FLAG_INITIALIZED, FLAG_REMOVING_FROM_HIERARCHY, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED8, PARENT_PATH, PATH_SEPARATOR, RENDER
 
Constructor Summary
ListView(String id)
           
ListView(String id, IModel<? extends List<? extends T>> model)
           
ListView(String id, List<? extends T> list)
           
 
Method Summary
 List<? extends T> getList()
          Gets the list of items in the listView.
protected  IModel<T> getListItemModel(IModel<? extends List<T>> listViewModel, int index)
          Subclasses may provide their own ListItemModel with extended functionality.
 IModel<? extends List<T>> getModel()
          Gets model
 List<T> getModelObject()
          Gets model object
 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).
 int getStartIndex()
          Get index of first cell in page.
 int getViewSize()
          Based on the model object's list size, firstIndex and view size, determine what the view size really will be.
 Link<Void> moveDownLink(String id, ListItem<T> item)
          Returns a link that will move the given item "down" (towards the end) in the listView.
 Link<Void> moveUpLink(String id, ListItem<T> item)
          Returns a link that will move the given item "up" (towards the beginning) in the listView.
protected  ListItem<T> newItem(int index, IModel<T> itemModel)
          Create a new ListItem for list item at index.
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().
protected  void onPopulate()
          Callback to let the repeater know it should populate itself with its items.
protected abstract  void populateItem(ListItem<T> item)
          Populate a given item.
 Link<Void> removeLink(String id, ListItem<T> item)
          Returns a link that will remove this ListItem from the ListView that holds it.
protected  void renderChild(Component child)
          Render a single child.
protected  void renderItem(ListItem<?> item)
          Render a single item.
protected  Iterator<Component> renderIterator()
          Returns an iterator for the collection of child components to be rendered.
 ListView<T> setList(List<? extends 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.
 void setModel(IModel<? extends List<T>> model)
          Sets model
 void setModelObject(List<T> object)
          Sets model object
 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).
 ListView<T> setStartIndex(int startIndex)
          Set the index of the first item to render
 ListView<T> setViewSize(int size)
          Define the maximum number of items to render.
 
Methods inherited from class org.apache.wicket.markup.repeater.AbstractRepeater
getMarkup, onBeforeRender, onRender
 
Methods inherited from class org.apache.wicket.markup.html.WebMarkupContainer
getWebApplication, getWebPage, getWebRequest, getWebResponse, getWebSession
 
Methods inherited from class org.apache.wicket.MarkupContainer
add, addOrReplace, autoAdd, contains, get, get, getAssociatedMarkup, getAssociatedMarkupStream, getMarkupType, internalAdd, internalInitialize, iterator, iterator, onAfterRenderChildren, onComponentTagBody, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderNext, replace, setDefaultModel, size, swap, toString, toString, visitChildren, visitChildren, visitChildren, visitChildren
 
Methods inherited from class org.apache.wicket.Component
add, addStateChange, afterRender, beforeRender, canCallListenerInterface, checkComponentTag, checkComponentTagAttribute, checkHierarchyChange, clearOriginalDestination, configure, continueToOriginalDestination, debug, detach, detachModel, detachModels, determineVisibility, error, exceptionMessage, fatal, findMarkupStream, findPage, findParent, findParentWithAssociatedMarkup, getAjaxRegionMarkupId, getApplication, getBehaviorById, getBehaviorId, getBehaviors, getBehaviors, getClassRelativePath, getConverter, getDefaultModel, getDefaultModelObject, getDefaultModelObjectAsString, getDefaultModelObjectAsString, getEscapeModelStrings, getFeedbackMessages, getFlag, getId, getInnermostModel, getInnermostModel, getLocale, getLocalizer, getMarkup, getMarkupAttributes, getMarkupId, getMarkupId, getMarkupIdFromMarkup, getMarkupIdImpl, getMarkupSourcingStrategy, getMetaData, getModelComparator, getOutputMarkupId, getOutputMarkupPlaceholderTag, getPage, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getRequestFlag, getResponse, getSession, getSizeInBytes, getStatelessHint, getString, getString, getString, getStyle, getVariation, hasBeenRendered, hasErrorMessage, hasFeedbackMessage, info, initModel, internalOnModelChanged, internalPrepareForRender, internalRenderComponent, isActionAuthorized, isAuto, isBehaviorAccepted, isEnableAllowed, isEnabled, isEnabledInHierarchy, isIgnoreAttributeModifier, isRenderAllowed, isRendering, isStateless, isVersioned, isVisibilityAllowed, isVisible, isVisibleInHierarchy, markRendering, modelChanged, modelChanging, newMarkupSourcingStrategy, onAfterRender, onComponentTag, onConfigure, onDetach, onEvent, onInitialize, onModelChanged, onModelChanging, onReAdd, onRemove, prepareForRender, redirectToInterceptPage, remove, remove, render, renderComponentTag, rendered, renderHead, renderHead, renderHead, renderPlaceholderTag, replaceComponentTagBody, replaceWith, sameInnermostModel, sameInnermostModel, send, setAuto, setDefaultModelObject, setEnabled, setEscapeModelStrings, setFlag, setIgnoreAttributeModifier, setMarkup, setMarkupId, setMarkupIdImpl, setMetaData, setOutputMarkupId, setOutputMarkupPlaceholderTag, setParent, setRenderBodyOnly, setRequestFlag, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisibilityAllowed, setVisible, success, urlFor, urlFor, urlFor, urlFor, urlFor, visitParents, visitParents, warn, wrap
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ListView

public ListView(String id)
See Also:
Component.Component(String)

ListView

public ListView(String id,
                IModel<? extends List<? extends T>> model)
Parameters:
id -
model -
See Also:
Component.Component(String, IModel)

ListView

public ListView(String id,
                List<? extends T> list)
Parameters:
id - See Component
list - List to cast to Serializable
See Also:
Component.Component(String, IModel)
Method Detail

getList

public final List<? extends 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, than 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<? extends 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:
AbstractRepeater.onPopulate()

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:
AbstractRepeater.renderChild(org.apache.wicket.Component)

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:
AbstractRepeater.renderIterator()

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 -


Copyright © 2006–2017 Apache Software Foundation. All rights reserved.