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 - Model object type

All Implemented Interfaces:

Serializable, IClusterable, IConverterLocator

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.IBehavior[]) 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

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.wicket.Component

Component.ComponentModelChange, Component.EnabledChange, Component.IVisitor<T extends Component>, Component.VisibilityChange

Field Summary

Fields inherited from class org.apache.wicket.Component

ENABLE, FLAG_CONFIGURED, FLAG_INITIALIZED, FLAG_REMOVING_FROM_HIERARCHY, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED6, FLAG_RESERVED7, 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.
Iterator<? extends ListItem<T>>	iterator()
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) 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

onBeforeRender, onRender

Methods inherited from class org.apache.wicket.markup.html.WebMarkupContainer

getMarkupType, getWebPage, getWebRequest

Methods inherited from class org.apache.wicket.MarkupContainer

add, addOrReplace, autoAdd, autoAdd, contains, findMarkupStream, get, get, getAssociatedMarkupStream, getMarkupStream, hasAssociatedMarkup, internalAdd, isTransparentResolver, iterator, newMarkupResourceStream, onAfterRenderChildren, onComponentTagBody, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderComponentTagBody, renderNext, replace, setDefaultModel, setMarkupStream, size, swap, toString, toString, visitChildren, visitChildren

Methods inherited from class org.apache.wicket.Component

add, addStateChange, afterRender, beforeRender, callOnBeforeRenderIfNotVisible, checkComponentTag, checkComponentTagAttribute, checkHierarchyChange, configure, continueToOriginalDestination, debug, detach, detachBehaviors, detachModel, detachModels, determineVisibility, error, exceptionMessage, fatal, findPage, findParent, findParentWithAssociatedMarkup, getAjaxRegionMarkupId, getApplication, getBehaviors, getBehaviors, getBehaviorsRawList, getClassRelativePath, getComponentBorder, getConverter, getConverter, getDefaultModel, getDefaultModelObject, getDefaultModelObjectAsString, getDefaultModelObjectAsString, getEscapeModelStrings, getFeedbackMessage, getFlag, getFlag, getId, getInnermostModel, getInnermostModel, getLocale, getLocalizer, getMarkupAttributes, getMarkupId, getMarkupId, getMarkupIdImpl, getMetaData, getModelComparator, getOutputMarkupId, getOutputMarkupPlaceholderTag, getPage, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getResponse, getSession, getSizeInBytes, getStatelessHint, getString, getString, getString, getStyle, getVariation, hasBeenRendered, hasErrorMessage, hasFeedbackMessage, info, initModel, internalAttach, internalDetach, internalOnAttach, internalOnDetach, internalOnModelChanged, isActionAuthorized, isAncestorOf, isAttached, isBehaviorAccepted, isEnableAllowed, isEnabled, isEnabledInHierarchy, isIgnoreAttributeModifier, isRenderAllowed, isStateless, isVersioned, isVisibilityAllowed, isVisible, isVisibleInHierarchy, locateMarkupStream, markAttached, markRendering, modelChanged, modelChanging, onAfterRender, onAttach, onBeginRequest, onComponentTag, onConfigure, onDetach, onEndRequest, onInitialize, onModelChanged, onModelChanging, onRemove, prepareForRender, prepareForRender, redirectToInterceptPage, remove, remove, render, render, renderComponent, renderComponent, renderComponentTag, rendered, renderHead, renderPlaceholderTag, replaceComponentTagBody, replaceWith, sameInnermostModel, sameInnermostModel, setAuto, setComponentBorder, setDefaultModelObject, setEnabled, setEscapeModelStrings, setFlag, setFlag, setIgnoreAttributeModifier, setMarkupId, setMarkupIdImpl, setMetaData, setOutputMarkupId, setOutputMarkupPlaceholderTag, setRedirect, setRenderBodyOnly, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisibilityAllowed, setVisible, urlFor, urlFor, urlFor, urlFor, urlFor, urlFor, 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, ALLWAYS 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)

Create a new ListItem for list item at index.

Parameters:

index -

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()

iterator

public Iterator<? extends ListItem<T>> iterator()

Overrides:

iterator in class MarkupContainer

Returns:

Iterator that iterates through children in the order they were added

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 -