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.ajax; 018 019import java.util.Map; 020 021import org.apache.wicket.Component; 022import org.apache.wicket.Page; 023import org.apache.wicket.ajax.attributes.AjaxRequestAttributes; 024import org.apache.wicket.core.request.handler.IPartialPageRequestHandler; 025import org.apache.wicket.request.ILoggableRequestHandler; 026 027/** 028 * 029 * @since 6.0 030 */ 031public interface AjaxRequestTarget extends IPartialPageRequestHandler, ILoggableRequestHandler 032{ 033 /** 034 * An {@link AjaxRequestTarget} listener that can be used to respond to various target-related 035 * events 036 * 037 */ 038 interface IListener 039 { 040 /** 041 * Triggered before the target begins writing components. 042 * 043 * @param map 044 * modifiable map (markupId -> component) of components already added to the target 045 * @param target 046 * the target itself. Could be used to add components or to append/prepend 047 * JavaScript 048 * 049 */ 050 default void onBeforeRespond(Map<String, Component> map, AjaxRequestTarget target) 051 {} 052 053 /** 054 * Triggered after the target has written components. At this point only 055 * additional JavaScript can be added to the response. 056 * 057 * NOTE: During this stage of processing any calls that manipulate components will result in 058 * an exception. After notification of all listeners no JavaScript can be added any longer. 059 * 060 * @param map 061 * read-only map:markupId->component of components already added to the target 062 * @param target 063 * the target itself. Could be used to append/prepend JavaScript 064 */ 065 default void onAfterRespond(Map<String, Component> map, AjaxRequestTarget target) 066 { 067 } 068 069 /** 070 * Triggered for every Ajax behavior. Can be used to configure common settings. 071 * 072 * @param behavior 073 * the behavior the attributes are updated for 074 * @param attributes 075 * The attributes for the Ajax behavior 076 * @since 7.0.0 077 */ 078 default void updateAjaxAttributes(AbstractDefaultAjaxBehavior behavior, AjaxRequestAttributes attributes) 079 {} 080 } 081 082 /** 083 * Components can implement this interface to get a notification when AjaxRequestTarget begins 084 * to respond. This can be used to postpone adding components to AjaxRequestTarget until the 085 * response begins. 086 * 087 * @author Matej Knopp 088 */ 089 @FunctionalInterface 090 interface ITargetRespondListener 091 { 092 /** 093 * Invoked when AjaxRequestTarget is about to respond. 094 * 095 * @param target 096 */ 097 void onTargetRespond(AjaxRequestTarget target); 098 } 099 100 /** 101 * Adds a listener to this target 102 * 103 * @param listener 104 * @throws IllegalStateException 105 * if {@link AjaxRequestTarget.IListener}'s events are currently being fired or have both been fired 106 * already 107 */ 108 void addListener(AjaxRequestTarget.IListener listener); 109 110 /** 111 * Register the given respond listener. The listener's 112 * {@link org.apache.wicket.ajax.AjaxRequestTarget.ITargetRespondListener#onTargetRespond} method will be invoked when 113 * the {@link AjaxRequestTarget} starts to respond. 114 * 115 * @param listener 116 */ 117 void registerRespondListener(ITargetRespondListener listener); 118 119 /** 120 * Returns the HTML id of the last focused element. 121 * 122 * @return markup id of last focused element, <code>null</code> if none 123 */ 124 String getLastFocusedElementId(); 125 126 /** 127 * Returns the page. Be aware that the page can be instantiated if this wasn't the case already. 128 * 129 * @return page instance 130 */ 131 @Override 132 Page getPage(); 133}