wicket.markup.html.list
Class ListView

java.lang.Object
  wicket.Component
      wicket.MarkupContainer
          wicket.markup.html.WebMarkupContainer
              wicket.markup.html.list.ListView

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

PageableListView, PropertyListView

public abstract class ListView
extends WebMarkupContainer

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("rows", listData)
 {
        public void populateItem(final ListItem item)
        {
                final UserDetails user = (UserDetails)item.getModelObject();
                item.add(new Label("id", user.getId()));
        }
 });
 

WARNING: though you can nest ListViews within Forms, you HAVE to set the optimizeItemRemoval property to true in order to have validation work properly. By default, optimizeItemRemoval 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 optimizeItemRemoval is false.

Author:

Jonathan Locke, Juergen Donnerstag, Johan Compagner, Eelco Hillenius

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class wicket.Component

Component.ComponentModelChange, Component.EnabledChange, Component.IVisitor, Component.VisibilityChange

Field Summary

Fields inherited from class wicket.Component

ENABLE, FLAG_RESERVED1, FLAG_RESERVED2, FLAG_RESERVED3, FLAG_RESERVED4, FLAG_RESERVED5, FLAG_RESERVED6, FLAG_RESERVED7, FLAG_RESERVED8, PATH_SEPARATOR, RENDER

Constructor Summary

ListView(java.lang.String id)

ListView(java.lang.String id, IModel model)

ListView(java.lang.String id, java.util.List list)

Method Summary

java.util.List	getList() Gets the list of items in the listView.
protected IModel	getListItemModel(IModel listViewModel, int index) Subclasses may provide their own ListItemModel with extended functionality.
boolean	getOptimizeItemRemoval() Deprecated. Use getReuseItems() instead
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.
protected void	internalOnAttach() THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
Link	moveDownLink(java.lang.String id, ListItem item) Returns a link that will move the given item "down" (towards the end) in the listView.
Link	moveUpLink(java.lang.String id, ListItem item) Returns a link that will move the given item "up" (towards the beginning) in the listView.
protected ListItem	newItem(int index) Create a new ListItem for list item at index.
protected void	onBeginPopulateItem(ListItem 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	onRender(MarkupStream markupStream) Renders this component.
protected abstract void	populateItem(ListItem item) Populate a given item.
Link	removeLink(java.lang.String id, ListItem item) Returns a link that will remove this ListItem from the ListView that holds it.
protected void	renderItem(ListItem item) Render a single item.
Component	setList(java.util.List 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.
Component	setModel(IModel model) Sets the model and removes all current children, so that the next render will be using the contents of the model.
ListView	setOptimizeItemRemoval(boolean reuseItems) Deprecated. Use setReuseItems(boolean) instead
ListView	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	setStartIndex(int startIndex) Set the index of the first item to render
ListView	setViewSize(int size) Define the maximum number of items to render.

Methods inherited from class wicket.markup.html.WebMarkupContainer

getMarkupType, getWebPage

Methods inherited from class wicket.MarkupContainer

add, autoAdd, contains, findMarkupStream, get, getAssociatedMarkupStream, getMarkupStream, internalAdd, internalAttach, internalDetach, isTransparentResolver, iterator, iterator, newMarkupResourceStream, onComponentTagBody, remove, remove, removeAll, renderAll, renderAssociatedMarkup, renderComponentTagBody, replace, setMarkupStream, size, toString, toString, visitChildren, visitChildren

Methods inherited from class wicket.Component

add, addStateChange, checkComponentTag, checkComponentTagAttribute, continueToOriginalDestination, debug, detachBehaviors, detachModel, detachModels, error, exceptionMessage, fatal, findPage, findParent, findParentWithAssociatedMarkup, getApplication, getApplicationPages, getApplicationSettings, getBehaviors, getBehaviors, getClassRelativePath, getConverter, getEscapeModelStrings, getFeedbackMessage, getFlag, getFlag, getId, getLocale, getLocalizer, getMarkupAttributes, getMarkupId, getMetaData, getModel, getModelComparator, getModelObject, getModelObjectAsString, getOutputMarkupId, getPage, getPageFactory, getPageRelativePath, getParent, getPath, getRenderBodyOnly, getRequest, getRequestCycle, getResponse, getSession, getSizeInBytes, getString, getString, getString, getStyle, getVariation, hasErrorMessage, hasFeedbackMessage, info, initModel, internalOnDetach, internalOnModelChanged, isActionAuthorized, isAncestorOf, isBehaviorAccepted, isEnableAllowed, isEnabled, isHeadRendered, isIgnoreAttributeModifier, isRenderAllowed, isVersioned, isVisible, isVisibleInHierarchy, modelChanged, modelChanging, newPage, newPage, onAfterRender, onAttach, onBeforeRender, onBeginRequest, onComponentTag, onDetach, onEndRequest, onModelChanged, onModelChanging, onRender, redirectToInterceptPage, remove, render, render, renderComponent, renderComponent, renderComponentTag, rendered, renderedBehaviors, renderHead, replaceComponentTagBody, replaceWith, resetHeadRendered, sameRootModel, sameRootModel, setAuto, setEnabled, setEscapeModelStrings, setFlag, setFlag, setIgnoreAttributeModifier, setMetaData, setModelObject, setOutputMarkupId, setRedirect, setRenderBodyOnly, setResponsePage, setResponsePage, setResponsePage, setVersioned, setVisible, urlFor, urlFor, urlFor, urlFor, urlFor, visitParents, warn

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ListView

public ListView(java.lang.String id)

See Also:

Component.Component(String)

ListView

public ListView(java.lang.String id,
                IModel model)

See Also:

Component.Component(String, IModel)

ListView

public ListView(java.lang.String id,
                java.util.List list)

Parameters:

id - See Component

list - List to cast to Serializable

See Also:

Component.Component(String, IModel)

Method Detail

getList

public final java.util.List 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.

getOptimizeItemRemoval

public boolean getOptimizeItemRemoval()

Deprecated. Use getReuseItems() instead

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

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 moveDownLink(java.lang.String id,
                               ListItem 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 moveUpLink(java.lang.String id,
                             ListItem 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 removeLink(java.lang.String id,
                             ListItem 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

setOptimizeItemRemoval

public ListView setOptimizeItemRemoval(boolean reuseItems)

Deprecated. Use setReuseItems(boolean) instead

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 items

Returns:

this

setReuseItems

public ListView 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 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 setViewSize(int size)

Define the maximum number of items to render. Default: render all.

Parameters:

size - Number of items to display

Returns:

This

setList

public Component setList(java.util.List 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

setModel

public Component setModel(IModel model)

Sets the model and removes all current children, so that the next render will be using the contents of the model.

Overrides:

setModel in class MarkupContainer

Parameters:

model - The new model

Returns:

This for chaining

See Also:

MarkupContainer.setModel(wicket.model.IModel)

getListItemModel

protected IModel getListItemModel(IModel 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

internalOnAttach

protected void internalOnAttach()

Description copied from class: Component

THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT CALL OR OVERRIDE. Called when a request begins.

Overrides:

internalOnAttach in class Component

See Also:

Component.internalOnAttach()

newItem

protected ListItem newItem(int index)

Create a new ListItem for list item at index.

Parameters:

index -

Returns:

ListItem

onBeginPopulateItem

protected void onBeginPopulateItem(ListItem 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 -

onRender

protected void onRender(MarkupStream markupStream)

Description copied from class: MarkupContainer

Renders this component. This implementation just calls renderComponent.

Overrides:

onRender in class MarkupContainer

See Also:

Component.onRender(wicket.markup.MarkupStream)

populateItem

protected abstract void populateItem(ListItem item)

Populate a given item.

be carefull 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