org.apache.wicket
Class MarkupContainer

java.lang.Object
  org.apache.wicket.Component
      org.apache.wicket.MarkupContainer

All Implemented Interfaces:

java.io.Serializable, java.lang.Iterable<Component>, IEventSink, IEventSource, IClusterable, IConverterLocator, IHeaderContributor, IRequestableComponent, IHierarchical<Component>

Direct Known Subclasses:

AbstractOutputTransformerContainer, Page, WebMarkupContainer

public abstract class MarkupContainer
extends Component
implements java.lang.Iterable<Component>

A MarkupContainer holds a map of child components.

• Children - Children can be added by calling the add() method, and they can be looked up using a dotted path. For example, if a container called "a" held a nested container "b" which held a nested component "c", then a.get("b:c") would return the Component with id "c". The number of children in a MarkupContainer can be determined by calling size(), and the whole hierarchy of children held by a MarkupContainer can be traversed by calling visitChildren(), passing in an implementation of IVisitor.
• Markup Rendering - A MarkupContainer also holds/references associated markup which is used to render the container. As the markup stream for a container is rendered, component references in the markup are resolved by using the container to look up Components in the container's component map by id. Each component referenced by the markup stream is given an opportunity to render itself using the markup stream.

  Components may alter their referring tag, replace the tag's body or insert markup after the tag. But components cannot remove tags from the markup stream. This is an important guarantee because graphic designers may be setting attributes on component tags that affect visual presentation.

  The type of markup held in a given container subclass can be determined by calling getMarkupType(). Markup is accessed via a MarkupStream object which allows a component to traverse ComponentTag and RawMarkup MarkupElements while rendering a response. Markup in the stream may be HTML or some other kind of markup, such as VXML, as determined by the specific container subclass.

  A markup stream may be directly associated with a container via setMarkupStream. However, a container which does not have a markup stream (its getMarkupStream() returns null) may inherit a markup stream from a container above it in the component hierarchy. The findMarkupStream() method will locate the first container at or above this container which has a markup stream.

  All Page containers set a markup stream before rendering by calling the method getAssociatedMarkupStream() to load the markup associated with the page. Since Page is at the top of the container hierarchy, it is guaranteed that findMarkupStream will always return a valid markup stream.

  Author:

  Jonathan Locke

  See Also:

  MarkupStream, 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

  MarkupContainer(java.lang.String id)
  

  MarkupContainer(java.lang.String id, IModel<?> model)
  

  Method Summary

  MarkupContainer	add(Component... childs) Adds a child component to this container.
  MarkupContainer	addOrReplace(Component... childs) Replaces a child component of this container with another or just adds it in case no child with the same id existed yet.
  boolean	autoAdd(Component component, MarkupStream markupStream) This method allows a component to be added by an auto-resolver such as AutoLinkResolver.
  boolean	contains(Component component, boolean recurse)
  Component	get(int index) Returns child component at the specified index
  Component	get(java.lang.String path) Get a child component by looking it up with the given path.
  Markup	getAssociatedMarkup() Gets a fresh markup stream that contains the (immutable) markup resource for this class.
  MarkupStream	getAssociatedMarkupStream(boolean throwException) Gets a fresh markup stream that contains the (immutable) markup resource for this class.
  IMarkupFragment	getMarkup(Component child) Get the childs markup
  MarkupType	getMarkupType() Get the type of associated markup for this component.
  boolean	hasAssociatedMarkup()
  void	internalAdd(Component child) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  void	internalInitialize() THIS METHOD IS NOT PART OF THE PUBLIC API, DO NOT CALL IT Overrides Component.internalInitialize() to call Component.fireInitialize() for itself and for all its children.
  java.util.Iterator<Component>	iterator()
  java.util.Iterator<Component>	iterator(java.util.Comparator<Component> comparator)
  protected void	onAfterRenderChildren()
  void	onComponentTagBody(MarkupStream markupStream, ComponentTag openTag) Handle the container's body.
  protected void	onMarkupAttached() Can be subclassed by any user to implement init-like logic which requires the markup to be available
  protected void	onRender() Implementation that renders this component.
  MarkupContainer	remove(Component component)
  MarkupContainer	remove(java.lang.String id) Removes the given component
  MarkupContainer	removeAll() Removes all children from this container.
  protected void	renderAll(MarkupStream markupStream, ComponentTag openTag) Loop through the markup in this container
  void	renderAssociatedMarkup(java.lang.String openTagName, java.lang.String exceptionMessage) Renders the entire associated markup for a container such as a Border or Panel.
  protected boolean	renderNext(MarkupStream markupStream) THIS METHOD IS NOT PART OF THE WICKET PUBLIC API.
  MarkupContainer	replace(Component child) Replaces a child component of this container with another
  MarkupContainer	setDefaultModel(IModel<?> model) Sets the given model.
  int	size() Get the number of children in this container.
  void	swap(int idx1, int idx2) Swaps position of children.
  java.lang.String	toString() Gets the string representation of this component.
  java.lang.String	toString(boolean detailed)
  ComponentHierarchyIterator	visitChildren()
  ComponentHierarchyIterator	visitChildren(java.lang.Class<?> clazz)
  <S extends Component,R> R	visitChildren(java.lang.Class<?> clazz, IVisitor<S,R> visitor) Traverses all child components of the given class in this container, calling the visitor's visit method at each one.
  <R> R	visitChildren(IVisitor<Component,R> visitor) Traverses all child components in this container, calling the visitor's visit method at each one.

  Methods inherited from class org.apache.wicket.Component

  add, addStateChange, afterRender, beforeRender, canCallListenerInterface, checkComponentTag, checkComponentTagAttribute, checkHierarchyChange, 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, getFeedbackMessage, 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, isStateless, isVersioned, isVisibilityAllowed, isVisible, isVisibleInHierarchy, locateMarkupStream, markRendering, modelChanged, modelChanging, newMarkupSourcingStrategy, onAfterRender, onBeforeRender, onComponentTag, onConfigure, onDetach, onEvent, onInitialize, onModelChanged, onModelChanging, 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, warn, wrap

  Methods inherited from class java.lang.Object

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

  Constructor Detail

  MarkupContainer

  public MarkupContainer(java.lang.String id)

  See Also:

  Component.Component(String)

  MarkupContainer

  public MarkupContainer(java.lang.String id,
                         IModel<?> model)

  See Also:

  Component.Component(String, IModel)

  Method Detail

  add

  public MarkupContainer add(Component... childs)

  Adds a child component to this container.

  Parameters:

  childs - The child(s)

  Returns:

  This

  Throws:

  java.lang.IllegalArgumentException - Thrown if a child with the same id is replaced by the add operation.

  addOrReplace

  public MarkupContainer addOrReplace(Component... childs)

  Replaces a child component of this container with another or just adds it in case no child with the same id existed yet.

  Parameters:

  childs - The child(s) to be added or replaced

  Returns:

  This

  autoAdd

  public final boolean autoAdd(Component component,
                               MarkupStream markupStream)

  This method allows a component to be added by an auto-resolver such as AutoLinkResolver. While the component is being added, the component's FLAG_AUTO boolean is set. The isAuto() method of Component returns true if a component or any of its parents has this bit set. When a component is added via autoAdd(), the logic in Page that normally (a) checks for modifications during the rendering process, and (b) versions components, is bypassed if Component.isAuto() returns true.

  The result of all this is that components added with autoAdd() are free from versioning and can add their own children without the usual exception that would normally be thrown when the component hierarchy is modified during rendering.

  Parameters:

  component - The component to add

  markupStream - Null, if the parent container is able to provide the markup. Else the markup stream to be used to render the component.

  Returns:

  True, if component has been added

  contains

  public boolean contains(Component component,
                          boolean recurse)

  Parameters:

  component - The component to check

  recurse - True if all descendents should be considered

  Returns:

  True if the component is contained in this container

  get

  public final Component get(java.lang.String path)

  Get a child component by looking it up with the given path.

  Specified by:

  get in interface IRequestableComponent

  Overrides:

  get in class Component

  Parameters:

  path - Path to component

  Returns:

  The component at the path

  getAssociatedMarkupStream

  public MarkupStream getAssociatedMarkupStream(boolean throwException)

  Gets a fresh markup stream that contains the (immutable) markup resource for this class.

  Parameters:

  throwException - If true, throw an exception, if markup could not be found

  Returns:

  A stream of MarkupElement elements

  getAssociatedMarkup

  public Markup getAssociatedMarkup()

  Gets a fresh markup stream that contains the (immutable) markup resource for this class.

  Returns:

  A stream of MarkupElement elements. Null if not found.

  getMarkup

  public IMarkupFragment getMarkup(Component child)

  Get the childs markup

  Parameters:

  child - The child component. If null, the container's markup will be returned. See Border, Panel or Enclosure where getMarkup(null) != getMarkup().

  Returns:

  The childs markup

  See Also:

  Component.getMarkup()

  getMarkupType

  public MarkupType getMarkupType()

  Get the type of associated markup for this component.

  Returns:

  The type of associated markup for this component (for example, "html", "wml" or "vxml"). The markup type for a component is independent of whether or not the component actually has an associated markup resource file (which is determined at runtime). If there is no markup type for a component, null may be returned, but this means that no markup can be loaded for the class. Null is also returned if the component, or any of its parents, has not been added to a Page.

  internalAdd

  public void internalAdd(Component child)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT. Adds a child component to this container.

  Parameters:

  child - The child

  Throws:

  java.lang.IllegalArgumentException - Thrown if a child with the same id is replaced by the add operation.

  iterator

  public java.util.Iterator<Component> iterator()

  Specified by:

  iterator in interface java.lang.Iterable<Component>

  Returns:

  Iterator that iterates through children in the order they were added

  iterator

  public final java.util.Iterator<Component> iterator(java.util.Comparator<Component> comparator)

  Parameters:

  comparator - The comparator

  Returns:

  Iterator that iterates over children in the order specified by comparator

  remove

  public MarkupContainer remove(Component component)

  Parameters:

  component - Component to remove from this container

  Returns:

  this for chaining

  remove

  public MarkupContainer remove(java.lang.String id)

  Removes the given component

  Parameters:

  id - The id of the component to remove

  Returns:

  this for chaining

  removeAll

  public MarkupContainer removeAll()

  Removes all children from this container.

  Note: implementation does not call remove(Component) for each component.

  Returns:

  this for method chaining

  renderAssociatedMarkup

  public final void renderAssociatedMarkup(java.lang.String openTagName,
                                           java.lang.String exceptionMessage)

  Renders the entire associated markup for a container such as a Border or Panel. Any leading or trailing raw markup in the associated markup is skipped.

  Parameters:

  openTagName - the tag to render the associated markup for

  exceptionMessage - message that will be used for exceptions

  replace

  public MarkupContainer replace(Component child)

  Replaces a child component of this container with another

  Parameters:

  child - The child

  Returns:

  This

  Throws:

  java.lang.IllegalArgumentException - Thrown if there was no child with the same id.

  setDefaultModel

  public MarkupContainer setDefaultModel(IModel<?> model)

  Description copied from class: Component

  Sets the given model.

  WARNING: DO NOT OVERRIDE THIS METHOD UNLESS YOU HAVE A VERY GOOD REASON FOR IT. OVERRIDING THIS MIGHT OPEN UP SECURITY LEAKS AND BREAK BACK-BUTTON SUPPORT.

  Overrides:

  setDefaultModel in class Component

  Parameters:

  model - The model

  Returns:

  This

  See Also:

  Component.setDefaultModel(org.apache.wicket.model.IModel)

  size

  public int size()

  Get the number of children in this container.

  Returns:

  Number of children in this container

  toString

  public java.lang.String toString()

  Description copied from class: Component

  Gets the string representation of this component.

  Overrides:

  toString in class Component

  Returns:

  The path to this component

  See Also:

  Component.toString()

  toString

  public java.lang.String toString(boolean detailed)

  Overrides:

  toString in class Component

  Parameters:

  detailed - True if a detailed string is desired

  Returns:

  String representation of this container

  visitChildren

  public final <S extends Component,R> R visitChildren(java.lang.Class<?> clazz,
                                                       IVisitor<S,R> visitor)

  Traverses all child components of the given class in this container, calling the visitor's visit method at each one. Make sure that if you give a type S that the clazz parameter will only resolve to those types. Else a class cast exception will occur.

  Type Parameters:

  S - The type that goes into the Visitor.component() method.

  R -

  Parameters:

  clazz - The class of child to visit, or null to visit all children

  visitor - The visitor to call back to

  Returns:

  The return value from a visitor which halted the traversal, or null if the entire traversal occurred

  visitChildren

  public final <R> R visitChildren(IVisitor<Component,R> visitor)

  Traverses all child components in this container, calling the visitor's visit method at each one.

  Type Parameters:

  R -

  Parameters:

  visitor - The visitor to call back to

  Returns:

  The return value from a visitor which halted the traversal, or null if the entire traversal occurred

  visitChildren

  public final ComponentHierarchyIterator visitChildren()

  Returns:

  A iterator which iterators over all children and grand-children the Component

  visitChildren

  public final ComponentHierarchyIterator visitChildren(java.lang.Class<?> clazz)

  Parameters:

  clazz - Filter condition

  Returns:

  A iterator which iterators over all children and grand-children the Component, returning only components which implement (instanceof) the provided clazz.

  internalInitialize

  public final void internalInitialize()

  THIS METHOD IS NOT PART OF THE PUBLIC API, DO NOT CALL IT Overrides Component.internalInitialize() to call Component.fireInitialize() for itself and for all its children.

  Overrides:

  internalInitialize in class Component

  See Also:

  Component.fireInitialize()

  get

  public final Component get(int index)

  Returns child component at the specified index

  Parameters:

  index -

  Returns:

  child component at the specified index

  Throws:

  java.lang.ArrayIndexOutOfBoundsException

  renderNext

  protected final boolean renderNext(MarkupStream markupStream)

  THIS METHOD IS NOT PART OF THE WICKET PUBLIC API. DO NOT USE IT. Renders the next element of markup in the given markup stream.

  Parameters:

  markupStream - The markup stream

  Returns:

  true, if element was rendered as RawMarkup

  onComponentTagBody

  public void onComponentTagBody(MarkupStream markupStream,
                                 ComponentTag openTag)

  Handle the container's body. If your override of this method does not advance the markup stream to the close tag for the openTag, a runtime exception will be thrown by the framework.

  Overrides:

  onComponentTagBody in class Component

  Parameters:

  markupStream - The markup stream

  openTag - The open tag for the body

  onRender

  protected void onRender()

  Description copied from class: Component

  Implementation that renders this component.

  Specified by:

  onRender in class Component

  See Also:

  Component.onRender()

  renderAll

  protected final void renderAll(MarkupStream markupStream,
                                 ComponentTag openTag)

  Loop through the markup in this container

  Parameters:

  markupStream -

  openTag -

  onAfterRenderChildren

  protected void onAfterRenderChildren()

  Overrides:

  onAfterRenderChildren in class Component

  hasAssociatedMarkup

  public boolean hasAssociatedMarkup()

  Returns:

  True if this markup container has associated markup

  swap

  public final void swap(int idx1,
                         int idx2)

  Swaps position of children. This method is particularly useful for adjusting positions of repeater's items without rebuilding the component hierarchy

  Parameters:

  idx1 - index of first component to be swapped

  idx2 - index of second component to be swapped

  onMarkupAttached

  protected void onMarkupAttached()

  Description copied from class: Component

  Can be subclassed by any user to implement init-like logic which requires the markup to be available

  Overrides:

  onMarkupAttached in class Component

  See Also:

  Component.onMarkupAttached()