org.apache.wicket.ajax
Class AjaxRequestTarget

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

All Implemented Interfaces:

IPageClassRequestHandler, IPageRequestHandler, IRequestHandler

public class AjaxRequestTarget
extends java.lang.Object
implements IPageRequestHandler

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#addComponent(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(org.apache.wicket.ajax.AjaxRequestTarget.IListener)

Since:

1.2

Author:

Igor Vaynberg (ivaynberg), Eelco Hillenius

Nested Class Summary

static interface	AjaxRequestTarget.IJavaScriptResponse An ajax javascript response that allows users to add javascript to be executed on the client side
static interface	AjaxRequestTarget.IListener An AjaxRequestTarget listener that can be used to respond to various target-related events
static interface	AjaxRequestTarget.ITargetRespondListener Components can implement this interface to get a notification when AjaxRequestTarget begins to respond.

Constructor Summary

AjaxRequestTarget(Page page)
Constructor

Method Summary

void	add(Component... components) Adds components to the list of components to be rendered.
void	add(Component component, java.lang.String markupId) Adds a component to the list of components to be rendered
void	addChildren(MarkupContainer parent, java.lang.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	addComponent(Component... components) Deprecated. use add(Component...) instead
void	addComponent(Component component, java.lang.String markupId) Deprecated. use add(Component...) instead
void	addListener(AjaxRequestTarget.IListener listener) Adds a listener to this target
void	appendJavaScript(java.lang.CharSequence javascript) Adds javascript that will be evaluated on the client side after components are replaced
void	detach(IRequestCycle requestCycle) This method is called at the end of a request cycle to indicate that processing is done and that cleaning up of the subject(s) of this target may be done.
protected java.lang.String	encode(java.lang.CharSequence str) Encodes a string so it is safe to use inside CDATA blocks
boolean	equals(java.lang.Object obj)
void	focusComponent(Component component) Sets the focus in the browser to the given component.
static AjaxRequestTarget	get() Static method that returns current AjaxRequestTarget or null of no AjaxRequestTarget is available.
java.util.Collection<? extends Component>	getComponents() Returns an unmodifiable collection of all components added to this target
protected java.lang.String	getEncodingName()
IHeaderResponse	getHeaderResponse() Returns the header response associated with current AjaxRequestTarget.
java.lang.String	getLastFocusedElementId() Returns the HTML id of the last focused element.
Page	getPage() Returns the page.
java.lang.Class<? extends IRequestablePage>	getPageClass() Returns the page class
java.lang.Integer	getPageId() Returns the page id.
PageParameters	getPageParameters()
java.lang.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
protected boolean	needsEncoding(java.lang.CharSequence str)
void	prependJavaScript(java.lang.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) Generates a response.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

AjaxRequestTarget

public AjaxRequestTarget(Page page)

Constructor

Parameters:

page -

Method Detail

getPage

public Page getPage()

Description copied from interface: IPageRequestHandler

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

Specified by:

getPage in interface IPageRequestHandler

Returns:

page instance

See Also:

IPageRequestHandler.getPage()

addListener

public void addListener(AjaxRequestTarget.IListener listener)
                 throws java.lang.IllegalStateException

Adds a listener to this target

Parameters:

listener -

Throws:

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

addChildren

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

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

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.

addComponent

@Deprecated
public void addComponent(Component... components)

Deprecated. use add(Component...) instead

Adds components to the list of components to be rendered

Parameters:

components - components to be rendered

add

public void add(Component... components)

Adds components to the list of components to be rendered.

Parameters:

components - components to be rendered

addComponent

@Deprecated
public final void addComponent(Component component,
                                          java.lang.String markupId)

Deprecated. use add(Component...) instead

Adds a component to the list of components to be rendered

Parameters:

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

component - component to be rendered

add

public final void add(Component component,
                      java.lang.String markupId)
               throws java.lang.IllegalArgumentException,
                      java.lang.IllegalStateException

Adds a component to the list of components to be rendered

Parameters:

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

component - component to be rendered

Throws:

java.lang.IllegalArgumentException - if the component is a Page or an AbstractRepeater

java.lang.IllegalStateException - if the components are currently being rendered, or have already been rendered

getComponents

public final java.util.Collection<? extends Component> getComponents()

Returns an unmodifiable collection of all components added to this target

Returns:

unmodifiable collection of all components added to this target

focusComponent

public final void focusComponent(Component component)

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.

Parameters:

component - The component to get the focus or null.

appendJavaScript

public final void appendJavaScript(java.lang.CharSequence javascript)

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

Parameters:

javascript -

detach

public void detach(IRequestCycle requestCycle)

Description copied from interface: IRequestHandler

This method is called at the end of a request cycle to indicate that processing is done and that cleaning up of the subject(s) of this target may be done.

Specified by:

detach in interface IRequestHandler

Parameters:

requestCycle - the current request cycle

See Also:

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

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

See Also:

Object.hashCode()

prependJavaScript

public final void prependJavaScript(java.lang.CharSequence javascript)

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

Parameters:

javascript -

registerRespondListener

public void registerRespondListener(AjaxRequestTarget.ITargetRespondListener listener)

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

Parameters:

listener -

respond

public final void respond(IRequestCycle requestCycle)

Description copied from interface: IRequestHandler

Generates a response.

Specified by:

respond in interface IRequestHandler

Parameters:

requestCycle - the current request cycle

See Also:

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

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()

encode

protected java.lang.String encode(java.lang.CharSequence str)

Encodes a string so it is safe to use inside CDATA blocks

Parameters:

str -

Returns:

encoded string

getEncodingName

protected java.lang.String getEncodingName()

Returns:

name of encoding used to possibly encode the contents of the CDATA blocks

needsEncoding

protected boolean needsEncoding(java.lang.CharSequence str)

Parameters:

str -

Returns:

true if string needs to be encoded, false otherwise

getHeaderResponse

public IHeaderResponse getHeaderResponse()

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.

Returns:

header response

get

public static AjaxRequestTarget get()

Static method that returns current AjaxRequestTarget or null of no AjaxRequestTarget is available.

Returns:

AjaxRequestTarget instance if current request is an Ajax request, null otherwise.

getLastFocusedElementId

public java.lang.String getLastFocusedElementId()

Returns the HTML id of the last focused element.

Returns:

markup id of last focused element, null if none

getPageClass

public java.lang.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 java.lang.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 not yet created

getRenderCount

public final java.lang.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()