org.apache.wicket.ajax
Class AjaxRequestHandler

java.lang.Object
  org.apache.wicket.ajax.AjaxRequestHandler

All Implemented Interfaces:

AjaxRequestTarget, IPageClassRequestHandler, IPageRequestHandler, ILoggableRequestHandler, IRequestHandler

public class AjaxRequestHandler
extends Object
implements AjaxRequestTarget

A request target that produces ajax response envelopes used on the client side to update component markup as well as evaluate arbitrary javascript.

A component whose markup needs to be updated should be added to this target via AjaxRequestTarget#add(Component) method. Its body will be rendered and added to the envelope when the target is processed, and refreshed on the client side when the ajax response is received.

It is important that the component whose markup needs to be updated contains an id attribute in the generated markup that is equal to the value retrieved from Component#getMarkupId(). This can be accomplished by either setting the id attribute in the html template, or using an attribute modifier that will add the attribute with value Component#getMarkupId() to the tag ( such as MarkupIdSetter )

Any javascript that needs to be evaluated on the client side can be added using AjaxRequestTarget#append/prependJavaScript(String). For example, this feature can be useful when it is desirable to link component update with some javascript effects.

The target provides a listener interface AjaxRequestTarget.IListener that can be used to add code that responds to various target events by adding listeners via addListener(AjaxRequestTarget.IListener)

Since:

1.2

Author:

Igor Vaynberg (ivaynberg), Eelco Hillenius

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.wicket.ajax.AjaxRequestTarget

AjaxRequestTarget.AbstractListener, AjaxRequestTarget.IJavaScriptResponse, AjaxRequestTarget.IListener, AjaxRequestTarget.ITargetRespondListener

Field Summary

protected boolean	listenersFrozen
protected boolean	respondersFrozen see https://issues.apache.org/jira/browse/WICKET-3564

Constructor Summary

AjaxRequestHandler(Page page)
Constructor

Method Summary

void	add(Component... components) Adds components to the list of components to be rendered.
void	add(Component component, String markupId) Adds a component to the list of components to be rendered
void	addChildren(MarkupContainer parent, Class<?> childCriteria) Visits all children of the specified parent container and adds them to the target if they are of same type as childCriteria
void	addListener(AjaxRequestTarget.IListener listener) Adds a listener to this target
void	appendJavaScript(CharSequence javascript) Adds javascript that will be evaluated on the client side after components are replaced
void	detach(IRequestCycle requestCycle)
boolean	equals(Object obj)
void	focusComponent(Component component) Sets the focus in the browser to the given component.
Collection<? extends Component>	getComponents() Returns an unmodifiable collection of all components added to this target
IHeaderResponse	getHeaderResponse() Returns the header response associated with current AjaxRequestTarget.
String	getLastFocusedElementId() Returns the HTML id of the last focused element.
PageLogData	getLogData()
Page	getPage() Returns the page.
Class<? extends IRequestablePage>	getPageClass() Returns the page class
Integer	getPageId() Returns the page id.
PageParameters	getPageParameters()
Integer	getRenderCount() Returns the number of times this page has been rendered.
int	hashCode()
boolean	isPageInstanceCreated() Checks if the page instance is already created or if it will be created when IPageRequestHandler.getPage() is called
void	prependJavaScript(CharSequence javascript) Adds javascript that will be evaluated on the client side before components are replaced.
void	registerRespondListener(AjaxRequestTarget.ITargetRespondListener listener) Register the given respond listener.
void	respond(IRequestCycle requestCycle)
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

respondersFrozen

protected transient boolean respondersFrozen

see https://issues.apache.org/jira/browse/WICKET-3564

listenersFrozen

protected transient boolean listenersFrozen

Constructor Detail

AjaxRequestHandler

public AjaxRequestHandler(Page page)

Constructor

Parameters:

page - the currently active page

Method Detail

getPage

public Page getPage()

Description copied from interface: AjaxRequestTarget

Returns the page. Be aware that the page can be instantiated if this wasn't the case already.

Specified by:

getPage in interface AjaxRequestTarget

Specified by:

getPage in interface IPageRequestHandler

Returns:

page instance

See Also:

IPageRequestHandler.getPage()

addListener

public void addListener(AjaxRequestTarget.IListener listener)
                 throws IllegalStateException

Description copied from interface: AjaxRequestTarget

Adds a listener to this target

Specified by:

addListener in interface AjaxRequestTarget

Throws:

IllegalStateException - if AjaxRequestTarget.IListener's events are currently being fired or have both been fired already

addChildren

public final void addChildren(MarkupContainer parent,
                              Class<?> childCriteria)

Description copied from interface: AjaxRequestTarget

Visits all children of the specified parent container and adds them to the target if they are of same type as childCriteria

Specified by:

addChildren in interface AjaxRequestTarget

Parameters:

parent - Must not be null.

childCriteria - Must not be null. If you want to traverse all components use ` Component.class as the value for this argument.

add

public void add(Component... components)

Description copied from interface: AjaxRequestTarget

Adds components to the list of components to be rendered.

Specified by:

add in interface AjaxRequestTarget

Parameters:

components - components to be rendered

add

public void add(Component component,
                String markupId)

Description copied from interface: AjaxRequestTarget

Adds a component to the list of components to be rendered

Specified by:

add in interface AjaxRequestTarget

Parameters:

component - component to be rendered

markupId - id of client-side dom element that will be updated

getComponents

public final Collection<? extends Component> getComponents()

Description copied from interface: AjaxRequestTarget

Returns an unmodifiable collection of all components added to this target

Specified by:

getComponents in interface AjaxRequestTarget

Returns:

unmodifiable collection of all components added to this target

focusComponent

public final void focusComponent(Component component)

Description copied from interface: AjaxRequestTarget

Sets the focus in the browser to the given component. The markup id must be set. If the component is null the focus will not be set to any component.

Specified by:

focusComponent in interface AjaxRequestTarget

Parameters:

component - The component to get the focus or null.

appendJavaScript

public final void appendJavaScript(CharSequence javascript)

Description copied from interface: AjaxRequestTarget

Adds javascript that will be evaluated on the client side after components are replaced

If the javascript needs to do something asynchronously (i.e. needs to use window.setTimeout(), for example to do animations) then the following special syntax may be used: someFunctionName|myJsLogic(someFunctionName);. Wicket will transform it to: function(someFunctionName){myJsLogic(someFunctionName);} and your code is responsible to execute someFunctionName() when the asynchronous task is finished. Once someFunctionName is executed the next appended script will be executed. Important: it is highly recommended to execute your code in try/finally to make sure someFunctionName is executed even an error happens in your code, otherwise all following scripts wont be executed.

Specified by:

appendJavaScript in interface AjaxRequestTarget

detach

public void detach(IRequestCycle requestCycle)

Specified by:

detach in interface IRequestHandler

See Also:

IRequestHandler.detach(org.apache.wicket.request.IRequestCycle)

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

Overrides:

hashCode in class Object

See Also:

Object.hashCode()

prependJavaScript

public final void prependJavaScript(CharSequence javascript)

Description copied from interface: AjaxRequestTarget

Adds javascript that will be evaluated on the client side before components are replaced.

If the javascript needs to do something asynchronously (i.e. needs to use window.setTimeout(), for example to do animations) then the following special syntax may be used: someFunctionName|myJsLogic(someFunctionName);. Wicket will transform it to: function(someFunctionName){myJsLogic(someFunctionName);} and your code is responsible to execute someFunctionName() when the asynchronous task is finished. Once someFunctionName is executed the next prepended script will be executed. Important: it is highly recommended to execute your code in try/finally to make sure someFunctionName is executed even an error happens in your code, otherwise all following scripts and component replacements wont be made.

Specified by:

prependJavaScript in interface AjaxRequestTarget

registerRespondListener

public void registerRespondListener(AjaxRequestTarget.ITargetRespondListener listener)

Description copied from interface: AjaxRequestTarget

Register the given respond listener. The listener's AjaxRequestTarget.ITargetRespondListener.onTargetRespond(org.apache.wicket.ajax.AjaxRequestTarget) method will be invoked when the AjaxRequestTarget starts to respond.

Specified by:

registerRespondListener in interface AjaxRequestTarget

respond

public final void respond(IRequestCycle requestCycle)

Specified by:

respond in interface IRequestHandler

See Also:

IRequestHandler.respond(org.apache.wicket.request.IRequestCycle)

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

getHeaderResponse

public IHeaderResponse getHeaderResponse()

Description copied from interface: AjaxRequestTarget

Returns the header response associated with current AjaxRequestTarget. Beware that only renderOnDomReadyJavaScript and renderOnLoadJavaScript can be called outside the renderHeader(IHeaderResponse response) method. Calls to other render** methods will result in the call failing with a debug-level log statement to help you see why it failed.

Specified by:

getHeaderResponse in interface AjaxRequestTarget

Returns:

header response

getLastFocusedElementId

public String getLastFocusedElementId()

Description copied from interface: AjaxRequestTarget

Returns the HTML id of the last focused element.

Specified by:

getLastFocusedElementId in interface AjaxRequestTarget

Returns:

the markup id of the focused element in the browser

getPageClass

public Class<? extends IRequestablePage> getPageClass()

Description copied from interface: IPageClassRequestHandler

Returns the page class

Specified by:

getPageClass in interface IPageClassRequestHandler

Returns:

page class

See Also:

IPageClassRequestHandler.getPageClass()

getPageId

public Integer getPageId()

Description copied from interface: IPageRequestHandler

Returns the page id.

Specified by:

getPageId in interface IPageRequestHandler

Returns:

page id

See Also:

IPageRequestHandler.getPageId()

getPageParameters

public PageParameters getPageParameters()

Specified by:

getPageParameters in interface IPageClassRequestHandler

Returns:

page parameters

See Also:

IPageClassRequestHandler.getPageParameters()

isPageInstanceCreated

public final boolean isPageInstanceCreated()

Description copied from interface: IPageRequestHandler

Checks if the page instance is already created or if it will be created when IPageRequestHandler.getPage() is called

Specified by:

isPageInstanceCreated in interface IPageRequestHandler

Returns:

true iff page instance is already created

getRenderCount

public final Integer getRenderCount()

Description copied from interface: IPageRequestHandler

Returns the number of times this page has been rendered.

Specified by:

getRenderCount in interface IPageRequestHandler

Returns:

the number of times this page has been rendered.

See Also:

IRequestablePage.getRenderCount()

getLogData

public PageLogData getLogData()

Specified by:

getLogData in interface ILoggableRequestHandler