001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.markup.html.panel;
018
019import org.apache.wicket.Component;
020import org.apache.wicket.MarkupContainer;
021import org.apache.wicket.markup.ComponentTag;
022import org.apache.wicket.markup.IMarkupFragment;
023import org.apache.wicket.markup.MarkupStream;
024import org.apache.wicket.markup.html.internal.HtmlHeaderContainer;
025import org.apache.wicket.markup.resolver.IComponentResolver;
026
027/**
028 * Markup sourcing strategies determine whether a Component behaves like a "Panel" pulling its
029 * Markup from an associated Markup file, or like a Fragment pulling it from a another components
030 * Markup.
031 * 
032 * @author Juergen Donnerstag
033 */
034public interface IMarkupSourcingStrategy
035{
036        /**
037         * Will be called in addition to {@link Component#internalRenderHead(HtmlHeaderContainer)} and allows
038         * the strategy to contribute to the <head> section of the response.
039         * 
040         * @see Component#internalRenderHead(HtmlHeaderContainer)
041         * 
042         * @param component
043         *            The component calling the strategy
044         * @param container
045         */
046        void renderHead(final Component component, HtmlHeaderContainer container);
047
048        /**
049         * Will be called in addition to {@link Component#onComponentTag(ComponentTag)} and allows the
050         * strategy to modify the component's tag or any of the tag attributes.
051         * 
052         * @see Component#onComponentTag(ComponentTag)
053         * 
054         * @param component
055         *            The component calling the strategy
056         * @param tag
057         */
058        void onComponentTag(Component component, ComponentTag tag);
059
060        /**
061         * Will <b>replace</b> the respective component's method.
062         * <p>
063         * It's perfectly valid to call <code>component.onComponentTagBody(markupStream, openTag)</code>
064         * from inside this method.
065         * 
066         * @see Component#onComponentTagBody(MarkupStream, ComponentTag)
067         * 
068         * @param component
069         *            The component calling the strategy
070         * @param markupStream
071         * @param openTag
072         */
073        void onComponentTagBody(final Component component, final MarkupStream markupStream,
074                final ComponentTag openTag);
075
076        /**
077         * Will <b>replace</b> the respective component's method. However by returning null, the
078         * component's method will be called.
079         * 
080         * @see MarkupContainer#getMarkup(Component)
081         * 
082         * @param container
083         *            The parent containing the child. This is not the direct parent, transparent
084         *            component {@link IComponentResolver resolver} may be in the hierarchy between.
085         * @param child
086         *            The component to find the markup for.
087         * @return the markup fragment for the child, or {@code null}.
088         */
089        IMarkupFragment getMarkup(final MarkupContainer container, final Component child);
090}