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.core.request.handler;
018
019import java.util.Collection;
020
021import org.apache.wicket.Component;
022import org.apache.wicket.MarkupContainer;
023import org.apache.wicket.markup.head.IHeaderResponse;
024
025/**
026 * Request handler that allows partial updates of the current page instance.
027 */
028public interface IPartialPageRequestHandler extends IPageRequestHandler
029{
030
031        /**
032         * Adds a component to the list of components to be rendered
033         *
034         * @param markupId
035         *            id of client-side dom element that will be updated
036         * @param component
037         *            component to be rendered
038         * @throws IllegalArgumentException
039         *             if the component is a {@link org.apache.wicket.Page} or an {@link org.apache.wicket.markup.repeater.AbstractRepeater}
040         * @throws IllegalStateException
041         *             if the components are currently being rendered, or have already been rendered
042         */
043        void add(final Component component, final String markupId);
044
045        /**
046         * Adds components to the list of components to be rendered.
047         *
048         * @param components
049         *            components to be rendered
050         */
051        void add(Component... components);
052
053
054        /**
055         * Visits all children of the specified parent container and adds them to the target if they are
056         * of same type as <code>childCriteria</code>
057         *
058         * @param parent
059         *            Must not be null.
060         * @param childCriteria
061         *            Must not be null. If you want to traverse all components use ` Component.class as
062         *            the value for this argument.
063         */
064        void addChildren(MarkupContainer parent, Class<?> childCriteria);
065
066        /**
067         * Add JavasSript that will be evaluated on the client side after components are replaced
068         * <p>
069         * If the JavaScript needs to do something asynchronously (i.e. uses window.setTimeout(), for example
070         * to do animations), it may call <code>Wicket.Ajax.suspendCall()</code> to suspend the evaluation of the current
071         * Ajax call. The returned function has to be called when the asynchronous task is finished, after which the evaluation
072         * of the Ajax call is continued, e.g.
073         * <pre>
074         * target.appendJavaScript("var continueCall = Wicket.Ajax.suspendCall(); try { ... } finally { continueCall(); }");
075         * </pre>
076         * <strong>Important</strong>: it is recommended to execute your code in try/finally to make sure
077         * the function is executed even if an error happens in your code, otherwise all following scripts and
078         * component replacements wont be made.
079         *
080         * @param javascript
081         */
082        void appendJavaScript(CharSequence javascript);
083
084        /**
085         * Add JavaScript that will be evaluated on the client side before components are replaced.
086         * <p>
087         * If the JavaScript needs to do something asynchronously (i.e. uses window.setTimeout(), for example
088         * to do animations), it may call <code>Wicket.Ajax.suspendCall()</code> to suspend the evaluation of the current
089         * Ajax call. The returned function has to be called when the asynchronous task is finished, after which the evaluation
090         * of the Ajax call is continued, e.g.
091         * <pre>
092         * target.prependJavaScript("var continueCall = Wicket.Ajax.suspendCall(); try { ... } finally { continueCall(); }");
093         * </pre>
094         * <strong>Important</strong>: it is recommended to execute your code in try/finally to make sure
095         * the function is executed even if an error happens in your code, otherwise all following scripts and
096         * component replacements wont be made.
097         *
098         * @param javascript
099         */
100        void prependJavaScript(CharSequence javascript);
101
102        /**
103         * Sets the focus in the browser to the given component. The markup id must be set. If the
104         * component is null the focus will not be set to any component.
105         *
106         * @param component
107         *            The component to get the focus or null.
108         */
109        void focusComponent(Component component);
110
111        /**
112         * Returns an unmodifiable collection of all components added to this target
113         *
114         * @return unmodifiable collection of all components added to this target
115         */
116        Collection<? extends Component> getComponents();
117
118        /**
119         * Returns the header response associated with current handler.
120         *
121         * Beware that only renderOnDomReadyJavaScript and renderOnLoadJavaScript can be called outside
122         * the renderHeader(IHeaderResponse response) method. Calls to other render** methods will
123         * result in the call failing with a debug-level log statement to help you see why it failed.
124         *
125         * @return header response
126         */
127        IHeaderResponse getHeaderResponse();
128}