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

Class Border

  • All Implemented Interfaces:
    Serializable, Iterable<Component>, IEventSink, IEventSource, IFeedbackContributor, IConverterLocator, IMetadataContext<Serializable,​Component>, IQueueRegion, IHeaderContributor, IComponentResolver, IRequestableComponent, org.apache.wicket.util.IHierarchical<Component>, org.apache.wicket.util.io.IClusterable
    Direct Known Subclasses:
    FormComponentFeedbackBorder
    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(), #get(int), 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:
    An alternative implementation based on Panel, A behavior which adds (raw) markup before and after the component, Serialized Form

    • Method Detail

      • 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

      • 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

      • 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:
        Component.getMarkup()

      • 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 {@link 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