Repository: wicket Updated Branches: refs/heads/master 19d700833 -> b2e663404
Guide changed due to WICKET-6137 Project: http://git-wip-us.apache.org/repos/asf/wicket/repo Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/b2e66340 Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/b2e66340 Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/b2e66340 Branch: refs/heads/master Commit: b2e66340417e44677eb1e0cf39e2c3dd0687efc1 Parents: 19d7008 Author: Andrea Del Bene <[email protected]> Authored: Thu Sep 1 16:55:42 2016 +0200 Committer: Andrea Del Bene <[email protected]> Committed: Thu Sep 1 16:55:42 2016 +0200 ---------------------------------------------------------------------- .../src/docs/guide/advanced/advanced_2.gdoc | 96 +++++++++----------- 1 file changed, 42 insertions(+), 54 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/wicket/blob/b2e66340/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc index 1d1dda0..e9b0cab 100644 --- a/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc +++ b/wicket-user-guide/src/docs/guide/advanced/advanced_2.gdoc @@ -1,39 +1,59 @@ -With Wicket it's quite easy to build a callback URL that executes a specific method on server side. This method must be defined in a functional interface (i.e. an an interface that defines just one method) that inherits from built-in @org.apache.wicket.IRequestListener@ and it must be a void method with no parameters in input: +With Wicket it's quite easy to build a callback URL that is handled on server side by a component or a behavior. What we have to do is to implement interface @org.apache.wicket.IRequestListener@: {code} -public interface IMyListener extends IRequestListener +public interface IRequestListener extends IClusterable { + + /** + * Does invocation of this listener render the page. + * + * @return default {@code true}, i.e. a {@link RenderPageRequestHandler} is schedules after invocation + */ + default boolean rendersPage() + { + return true; + } + /** - * Called when the relative callback URL is requested. + * Called when a request is received. */ - void myCallbackMethod(); + void onRequest(); } {code} -To control how the method will be invoked we must use class @org.apache.wicket.RequestListenerInterface@. In Wicket is a common practice to instantiate this class as a public static field inside the relative callback interface: +Method @onRequest@ is the handler that is executed to process the callback URL while @rendersPage@ tells if the whole page should be re-rendered after @onRequest@ has been executed (if we have a non-AJAX request). + +An example of a component that implements @IRequestListener@ can be seen in the Wicket standard link component. Here is an excerpt from its code: {code} -public interface IMyListener extends IRequestListener +public abstract class Link<T> extends AbstractLink implements IRequestListener ... { - /**RequestListenerInterface instance*/ - public static final RequestListenerInterface INTERFACE = new - RequestListenerInterface(IMyListener.class); /** - * Called when the relative callback URL is requested. + * Called when a link is clicked. + */ + public abstract void onClick(); + + /** + * THIS METHOD IS NOT PART OF THE WICKET API. DO NOT ATTEMPT TO OVERRIDE OR CALL IT. + * + * Called when a link is clicked. The implementation of this method is currently to simply call + * onClick(), but this may be augmented in the future. */ - void myCallbackMethod(); + @Override + public void onRequest() + { + // Invoke subclass handler + onClick(); + } } {code} -By default @RequestListenerInterface@ will respond rendering the current page after the callback method has been executed (if we have a non-AJAX request). To change this behavior we can use setter method @setRenderPageAfterInvocation(boolean)@. - -Now that our callback interface is complete we can generate a callback URL with @Component@'s method @urlFor(RequestListenerInterface, PageParameters)@ or with method @urlFor (Behavior, RequestListenerInterface, PageParameters)@ if we are using a callback interface with a behavior (see the following example). - -Project CallbackURLExample contains a behavior (class @OnChangeSingleChoiceBehavior@) that implements a callback interface to update the model of an @AbstractSingleSelectChoice@ component when user changes the selected option (it provides the same functionality of method @wantOnSelectionChangedNotifications@). +Callback URLs can be generated with @Component@'s method @urlFor(PageParameters)@ or with method @urlFor (Behavior, RequestListenerInterface, PageParameters)@ if we are using a callback interface with a behavior (see the following example). -Instead of a custom callback interface, @OnChangeSingleChoiceBehavior@ implements built-in interface @org.apache.wicket.behavior.IBehaviorListener@ which is designed to generate a callback URL for behaviors. The callback method defined in this interface is @onRequest()@ and the following is the implementation provided by @OnSelectionChangedNotifications@: +Project @CallbackURLExample@ contains a behavior (class @OnChangeSingleChoiceBehavior@) that implements @org.apache.wicket.IRequestListener@ to update the model of an @AbstractSingleSelectChoice@ component when user changes the selected option (it provides the same functionality of method @wantOnSelectionChangedNotifications@). +The following is the implementation of @onRequest()@ provided by @OnSelectionChangedNotifications@: {code} @Override @@ -73,60 +93,28 @@ public void onComponentTag(Component component, ComponentTag tag) { The goal of @onComponentTag@ is to build an onchange handler that forces user's browser to move to the callback URL (modifing standard property window.location.href). Please note that we have appended the expected parameter (choiceId) to the URL retrieving its value with a JQuery selector suited for the current type of component (a drop-down menu or a radio group). Since we are using JQuery in our JavaScript code, the behavior comes also with method @renderHead@ that adds the bundled JQuery library to the current page. -Method @getCallbackUrl()@ is used to generate the callback URL for our custom behavior and it has been copied from built-in class @AbstractAjaxBehavior@: +Method @getCallbackUrl()@ is used to generate the callback URL for our custom behavior: {code} -public CharSequence getCallbackUrl(){ - if (boundComponent == null){ +public CharSequence getCallbackUrl() { + if (boundComponent == null) { throw new IllegalArgumentException( "Behavior must be bound to a component to create the URL"); } - final RequestListenerInterface rli; - - rli = IBehaviorListener.INTERFACE; - - return boundComponent.urlFor(this, rli, new PageParameters()); + return boundComponent.urlForListener(this, new PageParameters()); } {code} -Static field @IBehaviorListener.INTERFACE@ is the implementation of @RequestListenerInterface@ defined inside callback interface @IBehaviorListener@. The home page of project @CallbackURLExample@ contains a @DropDownChoice@ and a @RadioChoice@ which use our custom behavior. There are also two labels to display the content of the models of the two components: !CallbackURLExample-screenshot.png! {note} -Implementing interface @IBehaviorListener@ makes a behavior stateful because its callback URL is specific for a given instance of component. +Implementing interface @IRequestListener@ makes a behavior stateful because its callback URL is specific for a given instance of component. {note} -As final note it's interesting to see how Wicket internally uses callback URLs for its standard link component. Class @org.apache.wicket.markup.html.link.Link@ implements interface @org.apache.wicket.markup.html.link.ILinkListener@ which in turn extends @IRequestListener@: - -{code} -public interface ILinkListener extends IRequestListener -{ - /** Listener interface */ - public static final RequestListenerInterface INTERFACE = new RequestListenerInterface( - ILinkListener.class); - - /** - * Called when a link is clicked. - */ - void onLinkClicked(); -} -{code} - -The implementation of method @onLinkClicked@ simply delegates event handling to our custom version of @onClick@: - -{code} -@Override -public final void onLinkClicked() -{ - // Invoke subclass handler - onClick(); -} -{code} - h3. Wicket events infrastructure Starting from version 1.5 Wicket offers an event-based infrastructure for inter-component communication. The infrastructure is based on two simple interfaces (both in package @org.apache.wicket.event@) : @IEventSource@ and @IEventSink@.
