wicket-user-guide/src/main/asciidoc/ajax/ajax_1.adoc

Wicket support for AJAX is implemented in file wicket-ajax-jquery.js which makes complete transparent to Java code any detail about AJAX communication. 

AJAX components and behaviors shipped with Wicket expose one or more callback methods which are executed when they receive an AJAX request. One of the arguments of these methods is an instance of interface _org.apache.wicket.ajax.AjaxRequestTarget_. 

For example component AjaxLink (in package _org.apache.wicket.ajax.markup.html_) defines abstract method _onClick(AjaxRequestTarget target)_ which is executed when user clicks on the component:

[source,java]
----
new AjaxLink<Void>("ajaxLink"){
	@Override
	public void onClick(AjaxRequestTarget target) {
	    //some server side code...
	}  	
};
----

Using AjaxRequestTarget we can specify the content that must be sent back to the client as response to the current AJAX request. The most commonly used method of this interface is probably _add(Component... components)_. With this method we tell Wicket to render again the specified components and refresh their markup via AJAX:

[source,java]
----
new AjaxLink<Void>("ajaxLink"){
	@Override
	public void onClick(AjaxRequestTarget target) {
	    //modify the model of a label and refresh it on browser
	    label.setDefaultModelObject("Another value 4 label.");
	    target.add(label);
	}  	
};
----

Components can be refreshed via Ajax only if they have rendered a markup id for their related tag. As a consequence, we must remember to set a valid id value on every component we want to add to _AjaxRequestTarget_. This can be done using one of the two methods seen in <<keepControl.adoc#_generating_tag_attribute_id,paragraph 6.3>>:

[source,java]
----
final Label label = new Label("labelComponent", "Initial value.");
//autogenerate a markup id
label.setOutputMarkupId(true);
add(label);
//...
new AjaxLink<Void>("ajaxLink"){
	@Override
	public void onClick(AjaxRequestTarget target) {
	    //modify the model of a label and refresh it on client side
	    label.setDefaultModelObject("Another value 4 label.");
	    target.add(label);
	}  	
};
----

Another common use of AjaxRequestTarget is to prepend or append some JavaScript code to the generated response. For example the following AJAX link displays an alert box as response to user's click:

[source,java]
----
new AjaxLink<Void>("ajaxLink"){
	@Override
	public void onClick(AjaxRequestTarget target) {
	    target.appendJavaScript(";alert('Hello!!');");
	}  	
};
----

WARNING: Repeaters component that have _org.apache.wicket.markup.repeater.AbstractRepeater_ as base class (like _ListView_, _RepeatingView_, etc...) can not be directly updated via AJAX.

If we want to refresh their markup via AJAX we must add one of their parent containers to the _AjaxRequestTarget_.

The standard implementation of _AjaxRequestTarget_ used by Wicket is class _org.apache.wicket.ajax.AjaxRequestHandler_. To create new instances of _AjaxRequestTarget_ a Wicket application uses the provider object registered with method _setAjaxRequestTargetProvider_:

[source,java]
----
setAjaxRequestTargetProvider(
		Function<Page, AjaxRequestTarget> ajaxRequestTargetProvider)
----

The provider is an implementation of interface _java.util.function.Function_, hence to use custom implementations of _AjaxRequestTarget_ we must register a custom provider that returns the desired implementation:

[source,java]
----
private static class MyCustomAjaxRequestTargetProvider implements
		Function<Page, AjaxRequestTarget>
	{
		@Override
		public AjaxRequestTarget apply(Page page)
		{
			return new MyCustomAjaxRequestTarget();
		}
	}
----

NOTE: During request handling _AjaxRequestHandler_ sends an event to its application to notify the entire component hierarchy of the current page:

[source,java]
----
   //'page' is the associated Page instance
   page.send(app, Broadcast.BREADTH, this);
----

The payload of the event is the _AjaxRequestHandler_ itself.