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

      • 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

      • replaceInBorder

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

      • 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: