wicket.markup.html.list
Class ListView

java.lang.Object
  extended by wicket.Component
      extended by wicket.MarkupContainer
          extended by wicket.markup.html.WebMarkupContainer
              extended by 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


Copyright © 2004-2007 Wicket developers. All Rights Reserved.