Module org.apache.wicket.core
Package org.apache.wicket.markup.html.border

Class Border

java.lang.Object
org.apache.wicket.Component
org.apache.wicket.MarkupContainer
org.apache.wicket.markup.html.WebMarkupContainer
org.apache.wicket.markup.html.border.Border
All Implemented Interfaces:
Serializable, Iterable<Component>, IEventSink, IEventSource, IFeedbackContributor, IConverterLocator, IMetadataContext<Serializable,Component>, IQueueRegion, IHeaderContributor, IComponentResolver, IRequestableComponent, IHierarchical<Component>, IClusterable
Direct Known Subclasses:
FormComponentFeedbackBorder, OrderByBorder
public abstract class Border extends WebMarkupContainer implements IComponentResolver, IQueueRegion
A border component has associated markup which is drawn and determines placement of markup and/or components nested within the border component.

The portion of the border's associated markup file which is to be used in rendering the border is denoted by a <wicket:border> tag. The children of the border component instance are then inserted into this markup, replacing the first <wicket:body> tag in the border's associated markup.

For example, if a border's associated markup looked like this: 

   <html>
   <body>
     <wicket:border>
       First <wicket:body/> Last
     </wicket:border>
   </body>
   </html>
And the border was used on a page like this: 
   <html>
   <body>
     <span wicket:id = "myBorder">
       Middle
     </span>
   </body>
   </html>
Then the resulting HTML would look like this: 
   <html>
   <body>
     First Middle Last
   </body>
   </html>
In other words, the body of the myBorder component is substituted into the border's associated markup at the position indicated by the <wicket:body> tag.

Regarding <wicket:body/> you have two options. Either use <wicket:body/> (open-close tag) which will automatically be expanded to <wicket:body>body content</wicket:body> or use <wicket:body>preview region</wicket:body> in your border's markup. The preview region (everything in between the open and close tag) will automatically be removed.

The border body container will automatically be created for you and added to the border container. It is accessible via getBodyContainer(). In case the body markup is not an immediate child of border (see the example below), then you must use code such as someContainer.add(getBodyContainer()) to add the body component to the correct container. 

   <html>
   <body>
     <wicket:border>
       <span wicket:id="someContainer">
         <wicket:body/>
       </span>
     </wicket:border>
   </body>
   </html>
The component "someContainer" in the previous example must be added to the border, and not the body, which is achieved via addToBorder(Component...).

add(Component...) is an alias to getBodyContainer().add(Component...) and will add a child component to the border body as shown in the example below. 

   <html>
   <body>
     <span wicket:id = "myBorder">
       <input wicket:id="name"/>
     </span>
   </body>
   </html>
This implementation does not apply any magic with respect to component handling. In doubt think simple. But everything you can do with a MarkupContainer or Component, you can do with a Border or its Body as well.

Other methods like Component.remove(), MarkupContainer.get(String), MarkupContainer.iterator(), etc. are not aliased to work on the border's body and attention must be paid when they need to be used.

Author:
Jonathan Locke, Juergen Donnerstag
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • getBodyContainer

      public final Border.BorderBodyContainer getBodyContainer()
      Returns the border body container. NOTE: this component is NOT meant to be directly handled by users, meaning that you can not explicitly add it to an arbitrary container or remove it from its original parent container.
      Returns:
      The border body container

    • add

      public Border add(Component... children)
      This is for all components which have been added to the markup like this: 
              <span wicket:id="myBorder">
                <input wicket:id="text1" .. />
                ...
        </span>
      Whereas addToBorder(Component...) will add a component associated with the following markup: 
              <wicket:border>
                <form wicket:id="myForm" .. >
                        <wicket:body/>
                </form>
        </wicket:border>
      Overrides:
      add in class MarkupContainer
      Parameters:
      children - The child(ren) to add.
      Returns:
      This
      See Also:

    • addOrReplace

      public Border addOrReplace(Component... children)
      Description copied from class: MarkupContainer
      Replaces a child component of this container with another or just adds it in case no child with the same id existed yet.
      Overrides:
      addOrReplace in class MarkupContainer
      Parameters:
      children - The child(ren) to be added or replaced
      Returns:
      this markup container

    • remove

      public Border remove(Component component)
      Description copied from class: MarkupContainer
      Removes a component from the children identified by the component.getId()
      Overrides:
      remove in class MarkupContainer
      Parameters:
      component - Component to remove from this container
      Returns:
      this for chaining

    • remove

      public Border remove(String id)
      Description copied from class: MarkupContainer
      Removes the given component
      Overrides:
      remove in class MarkupContainer
      Parameters:
      id - The id of the component to remove
      Returns:
      this for chaining

    • removeAll

      public Border removeAll()
      Description copied from class: MarkupContainer
      Removes all children from this container.

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

      Overrides:
      removeAll in class MarkupContainer
      Returns:
      this for method chaining

    • replace

      public Border replace(Component replacement)
      Description copied from class: MarkupContainer
      Replaces a child component of this container with another
      Overrides:
      replace in class MarkupContainer
      Parameters:
      replacement - The child
      Returns:
      This

    • addToBorder

      public Border addToBorder(Component... children)
      Adds children components to the Border itself
      Parameters:
      children - the children components to add
      Returns:
      this

    • queue

      public Border queue(Component... components)
      Description copied from class: MarkupContainer
      Queues one or more components to be dequeued later. The advantage of this method over the MarkupContainer.add(Component...) method is that the component does not have to be added to its direct parent, only to a parent upstream; it will be dequeued into the correct parent using the hierarchy defined in the markup. This allows the component hierarchy to be maintained only in markup instead of in markup and in java code; affording designers and developers more freedom when moving components in markup.
      Overrides:
      queue in class MarkupContainer
      Parameters:
      components - the components to queue
      Returns:
      this for method chaining

    • onConfigure

      protected void onConfigure()
      Description copied from class: Component
      Called on all components before any component is rendered. This method should be used to configure such things as visibility and enabled flags.

      Overrides must call super.onConfigure(), usually before any other code

      NOTE: Component hierarchy should not be modified inside this method, instead it should be done in Component.onBeforeRender()

      NOTE: Why this method is preferrable to directly overriding Component.isVisible() and Component.isEnabled()? Because those methods are called multiple times even for processing of a single request. If they contain expensive logic they can slow down the response time of the entire page. Further, overriding those methods directly on form components may lead to inconsistent or unexpected state depending on when those methods are called in the form processing workflow. It is a better practice to push changes to state rather than pull.

      NOTE: If component's visibility or another property depends on another component you may call other.configure() followed by other.isVisible() as mentioned in Component.configure() javadoc.

      NOTE: Why should Component.onBeforeRender() not be used for this? Because if a component's visibility is controlled inside Component.onBeforeRender(), once invisible the component will never become visible again.

      Overrides:
      onConfigure in class Component

    • queueToBorder

      public Border queueToBorder(Component... children)
      Queues children components to the Border itself
      Parameters:
      children - the children components to queue
      Returns:
      this

    • removeFromBorder

      public Border removeFromBorder(Component child)
      Removes child from the Border itself
      Parameters:
      child -
      Returns:
      this

    • replaceInBorder

      public Border replaceInBorder(Component component)
      Replaces component in the Border itself
      Parameters:
      component -
      Returns:
      this

    • resolve

      public Component resolve(MarkupContainer container, MarkupStream markupStream, ComponentTag tag)
      Try to resolve a component.
      Specified by:
      resolve in interface IComponentResolver
      Parameters:
      container - The container parsing its markup
      markupStream - The current markupStream
      tag - The current component tag while parsing the markup
      Returns:
      component or null if not found

    • newMarkupSourcingStrategy

      protected IMarkupSourcingStrategy newMarkupSourcingStrategy()
      If Component.getMarkupSourcingStrategy() returns null, this method will be called. By default it returns null, which means that a default markup strategy will be attached to the component.

      Please note that markup source strategies are not persisted. Instead they get re-created by calling this method again. That's ok since markup sourcing strategies usually do not maintain a state.

      Overrides:
      newMarkupSourcingStrategy in class Component
      Returns:
      Markup sourcing strategy

    • getMarkup

      public IMarkupFragment getMarkup(Component child)
      Search for the child markup in the file associated with the Border. The child markup must in between the <wicket:border> tags.
      Overrides:
      getMarkup in class MarkupContainer
      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 child's markup
      See Also:

    • canDequeueTag

      protected DequeueTagAction canDequeueTag(ComponentTag tag)
      Description copied from class: MarkupContainer
      Checks if this container can dequeue a child represented by the specified tag. This method should be overridden when containers can dequeue components represented by non-standard tags. For example, borders override this method and dequeue their body container when processing the body tag. By default all ComponentTags are supported as well as WicketTags that return a non-null value from ComponentTag.getAutoComponentFactory() method.
      Overrides:
      canDequeueTag in class MarkupContainer

    • findComponentToDequeue

      public Component findComponentToDequeue(ComponentTag tag)
      Description copied from class: MarkupContainer
      Queries this container to find a child that can be dequeued that matches the specified tag. The default implementation will check if there is a component in the queue that has the same id as a tag, but sometimes custom tags can be dequeued and in those situations this method should be overridden.
      Overrides:
      findComponentToDequeue in class MarkupContainer
      Returns:

    • addDequeuedComponent

      protected void addDequeuedComponent(Component component, ComponentTag tag)
      Description copied from class: MarkupContainer
      Adds a dequeued component to this container. This method should rarely be overridden because the common case of simply forwarding the component to MarkupContainer.add(Component...) method should cover most cases. Components that implement a custom hierarchy, such as borders, may wish to override it to support edge-case non-standard behavior.
      Overrides:
      addDequeuedComponent in class MarkupContainer

    • getRegionMarkup

      public IMarkupFragment getRegionMarkup()
      Returns the markup inside <wicket:border> tag. If such tag is not found, all the markup is returned.
      Specified by:
      getRegionMarkup in interface IQueueRegion
      Overrides:
      getRegionMarkup in class MarkupContainer
      Returns:
      the markup to use for queuing
      See Also: