You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by ad...@apache.org on 2015/03/29 22:15:06 UTC
[09/11] wicket git commit: Integration of Wicket-User-Guide into
build process
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/ajax/ajax_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/ajax/ajax_3.gdoc b/wicket-user-guide/src/docs/guide/ajax/ajax_3.gdoc
new file mode 100644
index 0000000..853109c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/ajax/ajax_3.gdoc
@@ -0,0 +1,117 @@
+
+
+In addition to specific components, Wicket offers also a set of built in AJAX behaviors that can be used to easily add AJAX functionalities to existing components. As we will see in this paragraph AJAX behaviors can be used also to ajaxify components that weren't initially designed to work with this technology. All the following behaviors are inside package @org.apache.wicket.ajax@.
+
+h3. AjaxEventBehavior
+
+AjaxEventBehavior allows to handle a JavaScript event (like click, change, etc...) on server side via AJAX. Its constructor takes in input the name of the event that must be handled. Every time this event is fired for a given component on client side, the callback method @onEvent(AjaxRequestTarget target)@ is executed. onEvent is abstract, hence we must implement it to tell @AjaxEventBehavior@ what to do when the specified event occurs.
+
+In project @AjaxEventBehaviorExample@ we used this behavior to build a “clickable” Label component that counts the number of clicks. Here is the code from the home page of the project:
+
+*HTML:*
+{code:html}
+<body>
+ <div wicket:id="clickCounterLabel"></div>
+ User has clicked <span wicket:id="clickCounter"></span> time/s on the label above.
+</body>
+{code}
+
+*Java Code:*
+{code}
+public class HomePage extends WebPage {
+ public HomePage(final PageParameters parameters) {
+ super(parameters);
+
+ final ClickCounterLabel clickCounterLabel =
+ new ClickCounterLabel("clickCounterLabel", "Click on me!");
+ final Label clickCounter =
+ new Label("clickCounter", new PropertyModel(clickCounterLabel, "clickCounter"));
+
+
+ clickCounterLabel.setOutputMarkupId(true);
+ clickCounterLabel.add(new AjaxEventBehavior("click"){
+
+ @Override
+ protected void onEvent(AjaxRequestTarget target) {
+ clickCounterLabel.clickCounter++;
+ target.add(clickCounter);
+ }
+ });
+
+ add(clickCounterLabel);
+ add(clickCounter.setOutputMarkupId(true));
+ }
+}
+
+class ClickCounterLabel extends Label{
+ public int clickCounter;
+
+ public ClickCounterLabel(String id) {
+ super(id);
+ }
+
+ public ClickCounterLabel(String id, IModel<?> model) {
+ super(id, model);
+ }
+
+ public ClickCounterLabel(String id, String label) {
+ super(id, label);
+ }
+}
+{code}
+
+In the code above we have declared a custom label class named @ClickCounterLabel@ that exposes a public integer field called clickCounter. Then, in the home page we have attached a @AjaxEventBehavior@ to our custom label to increment clickCounter every time it receives a click event.
+
+The number of clicks is displayed with another standard label named @clickCounter@.
+
+h3. AjaxFormSubmitBehavior
+
+This behavior allows to send a form via AJAX when the component it is attached to receives the specified event. The component doesn't need to be inside the form if we use the constructor version that, in addition to the name of the event, takes in input also the target form:
+
+{code}
+Form form = new Form("form");
+Button submitButton = new Button("submitButton");
+//submit form when button is clicked
+submitButton.add(new AjaxFormSubmitBehavior(form, "click"){});
+add(form);
+add(submitButton);
+{code}
+
+h3. AjaxFormComponentUpdatingBehavior
+
+This behavior updates the model of the form component it is attached to when a given event occurs. The standard form submitting process is skipped and the behavior validates only its form component.
+
+The behavior doesn't work with radio buttons and checkboxes. For these kinds of components we must use @AjaxFormChoiceComponentUpdatingBehavior@:
+
+{code}
+Form form = new Form("form");
+TextField textField = new TextField("textField", Model.of(""));
+//update the model of the text field each time event "change" occurs
+textField.add(new AjaxFormComponentUpdatingBehavior("change"){
+ @Override
+ protected void onUpdate(AjaxRequestTarget target) {
+ //...
+ }
+});
+add(form.add(textField));
+{code}
+
+h3. AbstractAjaxTimerBehavior
+
+@AbstractAjaxTimerBehavior@ executes callback method @onTimer(AjaxRequestTarget target)@ at a specified interval. The behavior can be stopped and restarted at a later time with methods @stop(AjaxRequestTarget target)@ and @restart(AjaxRequestTarget target)@:
+
+{code}
+Label dynamicLabel = new Label("dynamicLabel");
+//trigger an AJAX request every three seconds
+dynamicLabel.add(new AbstractAjaxTimerBehavior(Duration.seconds(3)) {
+ @Override
+ protected void onTimer(AjaxRequestTarget target) {
+ //...
+ }
+});
+add(dynamicLabel);
+{code}
+
+{note}
+As side effect AJAX components and behaviors make their hosting page stateful. As a consequence they are unfit for those pages that must stay stateless. Project WicketStuff provides a module with a stateless version of the most common AJAX components and behaviors. You can find more informations on this module in Appendix B.
+{note}
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/ajax/ajax_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/ajax/ajax_4.gdoc b/wicket-user-guide/src/docs/guide/ajax/ajax_4.gdoc
new file mode 100644
index 0000000..899e9af
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/ajax/ajax_4.gdoc
@@ -0,0 +1,31 @@
+
+
+One of the things we must take care of when we use AJAX is to notify user when an AJAX request is already in progress. This is usually done displaying an animated picture as activity indicator while the AJAX request is running.
+
+Wicket comes with a variant of components @AjaxButton@, @AjaxLink@ and @AjaxFallbackLink@ that display a default activity indicator during AJAX request processing. These components are respectively @IndicatingAjaxButton@, @IndicatingAjaxLink@ and @IndicatingAjaxFallbackLink@.
+
+The default activity indicator used in Wicket can be easily integrated in our components using behavior AjaxIndicatorAppender (available in package @org.apache.wicket.extensions.ajax.markup.html@) and implementing the interface @IAjaxIndicatorAware@ (in package @org.apache.wicket.ajax@).
+
+@IAjaxIndicatorAware@ declares method @getAjaxIndicatorMarkupId()@ which returns the id of the markup element used to display the activity indicator. This id can be obtained from the AjaxIndicatorAppender behavior that has been added to the current component. The following code snippet summarizes the steps needed to integrate the default activity indicator with an ajaxified component:
+
+{code}
+//1-Implement interface IAjaxIndicatorAware
+public class MyComponent extends Component implements IAjaxIndicatorAware {
+ //2-Instantiate an AjaxIndicatorAppender
+ private AjaxIndicatorAppender indicatorAppender =
+ new AjaxIndicatorAppender();
+
+ public MyComponent(String id, IModel<?> model) {
+ super(id, model);
+ //3-Add the AjaxIndicatorAppender to the component
+ add(indicatorAppender);
+ }
+ //4-Return the markup id obtained from AjaxIndicatorAppender
+ public String getAjaxIndicatorMarkupId() {
+ return indicatorAppender.getMarkupId();
+ }
+//...
+}
+{code}
+
+If we need to change the default picture used as activity indicator, we can override method @getIndicatorUrl()@ of @AjaxIndicatorAppender@ and return the URL to the desired picture.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/ajax/ajax_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/ajax/ajax_5.gdoc b/wicket-user-guide/src/docs/guide/ajax/ajax_5.gdoc
new file mode 100644
index 0000000..9729808
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/ajax/ajax_5.gdoc
@@ -0,0 +1,54 @@
+
+
+Starting from version 6.0 Wicket has introduced two entities which allow us to control how an AJAX request is generated on client side and to specify the custom JavaScript code we want to execute during request handling. These entities are class @AjaxRequestAttributes@ and interface @IAjaxCallListener@, both placed in package @org.apache.wicket.ajax.attributes@.
+
+AjaxRequestAttributes exposes the attributes used to generate the JavaScript call invoked on client side to start an AJAX request. Each attribute will be passed as a "JSON":http://en.wikipedia.org/wiki/JSON parameter to the JavaScript function @Wicket.Ajax.ajax@ which is responsible for sending the concrete AJAX request. Every JSON parameter is identified by a short name. Here is a partial list of the available parameters:
+
+{table}
+*Short name* | *Description* | *Default value*
+u | The callback URL used to serve the AJAX request that will be sent. |
+c | The id of the component that wants to start the AJAX call. |
+e | A list of event (click, change, etc...) that can trigger the AJAX call. | domready
+m | The request method that must be used (GET or POST). | GET
+f | The id of the form that must be submitted with the AJAX call. |
+mp | If the AJAX call involves the submission of a form, this flag indicates whether the data must be encoded using the encoding mode “multipart/form-data”. | false
+sc | The input name of the submitting component of the form |
+async | A boolean parameter that indicates if the AJAX call is asynchronous (true) or not. | true
+wr | Specifies the type of data returned by the AJAX call (XML, HTML, JSON, etc...). | XML
+bh, pre, bsh, ah, sh, fh, coh | This is a list of the listeners that are executed on client side (they are JavaScript scripts) during the lifecycle of an AJAX request. Each short name is the abbreviation of one of the methods defined in the interface IAjaxCallListener (see below). | An empty list
+{table}
+
+{note}
+A full list of the available request parameters as well as more details on the related JavaScript code can be found at "https://cwiki.apache.org/confluence/ display/WICKET/Wicket+Ajax":https://cwiki.apache.org/confluence/ display/WICKET/Wicket+Ajax .
+{note}
+
+Parameters 'u' (callback URL) and 'c' (the id of the component) are generated by the AJAX behavior that will serve the AJAX call and they are not accessible through @AjaxRequestAttributes@.
+
+Here is the final AJAX function generate for the behavior used in example project @AjaxEventBehavior@ Example:
+
+{code}
+Wicket.Ajax.ajax({"u":"./?0-1.IBehaviorListener.0-clickCounterLabel", "e":"click",
+ "c":"clickCounterLabel1"});
+{code}
+
+Even if most of the times we will let Wicket generate request attributes for us, both AJAX components and behaviors give us the chance to modify them overriding their method @updateAjaxAttributes (AjaxRequestAttributes attributes)@.
+
+One of the attribute we may need to modify is the list of @IAjaxCallListeners@ returned by method @getAjaxCallListeners()@.
+
+@IAjaxCallListener@ defines a set of methods which return the JavaScript code (as a @CharSequence@) that must be executed on client side when the AJAX request handling reaches a given stage:
+
+* *getBeforeHandler(Component)*: returns the JavaScript code that will be executed before any other handlers returned by IAjaxCallListener. The code is executed in a scope where it can use variable attrs, which is an array containing the JSON parameters passed to Wicket.Ajax.ajax.
+* *getPrecondition(Component)*: returns the JavaScript code that will be used as precondition for the AJAX call. If the script returns false then neither the Ajax call nor the other handlers will be executed. The code is executed in a scope where it can use variable attrs, which is the same variable seen for getBeforeHandler.
+* *getBeforeSendHandler(Component)*: returns the JavaScript code that will be executed just before the AJAX call is performed. The code is executed in a scope where it can use variables attrs, jqXHR and settings:
+** attrs is the same variable seen for getBeforeHandler.
+** jqXHR is the the jQuery XMLHttpRequest object used to make the AJAX call.
+** settings contains the settings used for calling jQuery.ajax().
+* *getAfterHandler(Component)*: returns the JavaScript code that will be executed after the AJAX call. The code is executed in a scope where it can use variable attrs, which is the same variable seen before for getBeforeHandler.
+* *getSuccessHandler(Component)*: returns the JavaScript code that will be executed if the AJAX call has successfully returned. The code is executed in a scope where it can use variables attrs, jqXHR, data and textStatus:
+** attrs and jqXHR are same variables seen for getBeforeSendHandler:
+** data is the data returned by the AJAX call. Its type depends on parameter wr (Wicket AJAX response).
+** textStatus it's the status returned as text.
+* *getFailureHandler(Component)*: returns the JavaScript code that will be executed if the AJAX call has returned with a failure. The code is executed in a scope where it can use variable attrs, which is the same variable seen for getBeforeHandler.
+* *getCompleteHandler(Component)*: returns the JavaScript that will be invoked after success or failure handler has been executed. The code is executed in a scope where it can use variables attrs, jqXHR and textStatus which are the same variables seen for getSuccessHandler.
+
+In the next paragraph we will see an example of custom @IAjaxCallListener@ designed to disable a component during AJAX request processing.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/ajax/ajax_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/ajax/ajax_6.gdoc b/wicket-user-guide/src/docs/guide/ajax/ajax_6.gdoc
new file mode 100644
index 0000000..399399b
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/ajax/ajax_6.gdoc
@@ -0,0 +1,174 @@
+
+
+Displaying an activity indicator is a nice way to notify user that an AJAX request is already running, but sometimes is not enough. In some situations we may need to completely disable a component during AJAX request processing, for example when we want to avoid that impatient users submit a form multiple times. In this paragraph we will see how to accomplish this goal building a custom and reusable @IAjaxCallListener@. The code used in this example is from project @CustomAjaxListenerExample@.
+
+h3. What we want for our listener
+
+The listener should execute some JavaScript code to disable a given component when the component it is attached to is about to make an AJAX call. Then, when the AJAX request has been completed, the listener should bring back the disabled component to an active state.
+
+When a component is disabled it must be clear to user that an AJAX request is running and that he/she must wait for it to complete. To achieve this result we want to disable a given component covering it with a semi-transparent overlay area with an activity indicator in the middle.
+
+The final result will look like this:
+
+!custom-ajax-call-listener.png!
+
+h3. How to implement the listener
+
+The listener will implement methods @getBeforeHandler@ and @getAfterHandler@: the first will return the code needed to place an overlay <div> on the desired component while the second must remove this overlay when the AJAX call has completed.
+
+To move and resize the overlay area we will use another module from "JQueryUI library":http://jqueryui.com/position/ that allows us to position DOM elements on our page relative to another element.
+
+So our listener will depend on four static resources: the JQuery library, the position module of JQuery UI, the custom code used to move the overlay <div> and the picture used as activity indicator. Except for the activity indicator, all these resources must be added to page header section in order to be used.
+
+Ajax call listeners can contribute to header section by simply implementing interface @IComponentAwareHeaderContributor@. Wicket provides adapter class @AjaxCallListener@ that implements both @IAjaxCallListener@ and @IComponentAwareHeaderContributor@. We will use this class as base class for our listener.
+
+h3. JavaScript code
+
+Now that we know what to do on the Java side, let's have a look at the custom JavaScript code that must be returned by our listener (file moveHiderAndIndicator.js):
+
+{code:javascript}
+DisableComponentListener = {
+ disableElement: function(elementId, activeIconUrl){
+ var hiderId = elementId + "-disable-layer";
+ var indicatorId = elementId + "-indicator-picture";
+
+ elementId = "#" + elementId;
+ //create the overlay <div>
+ $(elementId).after('<div id="' + hiderId
+ + '" style="position:absolute;">'
+ + '<img id="' + indicatorId + '" src="' + activeIconUrl + '"/>'
+ + '</div>');
+
+ hiderId = "#" + hiderId;
+ //set the style properties of the overlay <div>
+ $(hiderId).css('opacity', '0.8');
+ $(hiderId).css('text-align', 'center');
+ $(hiderId).css('background-color', 'WhiteSmoke');
+ $(hiderId).css('border', '1px solid DarkGray');
+ //set the dimention of the overlay <div>
+ $(hiderId).width($(elementId).outerWidth());
+ $(hiderId).height($(elementId).outerHeight());
+ //positioning the overlay <div> on the component that must be disabled.
+ $(hiderId).position({of: $(elementId),at: 'top left', my: 'top left'});
+
+ //positioning the activity indicator in the middle of the overlay <div>
+ $("#" + indicatorId).position({of: $(hiderId), at: 'center center',
+ my: 'center center'});
+ },
+ //function hideComponent
+{code}
+
+Function DisableComponentListener.disableElement places the overlay <div> an the activity indicator on the desired component. The parameters in input are the markup id of the component we want to disable and the URL of the activity indicator picture. These two parameters must be provided by our custom listener.
+
+The rest of custom JavaScript contains function DisableComponentListener.hideComponent which is just a wrapper around the JQuery function remove():
+
+{code:javascript}
+hideComponent: function(elementId){
+ var hiderId = elementId + "-disable-layer";
+ $('#' + hiderId).remove();
+ }
+};
+{code}
+
+h3. Java class code
+
+The code of our custom listener is the following:
+
+{code}
+public class DisableComponentListener extends AjaxCallListener {
+ private static PackageResourceReference customScriptReference = new
+ PackageResourceReference(DisableComponentListener.class, "moveHiderAndIndicator.js");
+
+ private static PackageResourceReference jqueryUiPositionRef = new
+ PackageResourceReference(DisableComponentListener.class, "jquery-ui-position.min.js");
+
+ private static PackageResourceReference indicatorReference =
+ new PackageResourceReference(DisableComponentListener.class, "ajax-loader.gif");
+
+ private Component targetComponent;
+
+ public DisableComponentListener(Component targetComponent){
+ this.targetComponent = targetComponent;
+ }
+
+ @Override
+ public CharSequence getBeforeHandler(Component component) {
+ CharSequence indicatorUrl = getIndicatorUrl(component);
+ return ";DisableComponentListener.disableElement('" + targetComponent.getMarkupId()
+ + "'," + "'" + indicatorUrl + "');";
+ }
+
+ @Override
+ public CharSequence getCompleteHandler(Component component) {
+ return ";DisableComponentListener.hideComponent('"
+ + targetComponent.getMarkupId() + "');";
+ }
+
+ protected CharSequence getIndicatorUrl(Component component) {
+ return component.urlFor(indicatorReference, null);
+ }
+
+ @Override
+ public void renderHead(Component component, IHeaderResponse response) {
+ ResourceReference jqueryReference =
+ Application.get().getJavaScriptLibrarySettings().getJQueryReference();
+ response.render(JavaScriptHeaderItem.forReference(jqueryReference));
+ response.render(JavaScriptHeaderItem.forReference(jqueryUiPositionRef));
+ response.render(JavaScriptHeaderItem.forReference(customScriptReference) );
+ }
+}
+{code}
+
+As you can see in the code above we have created a function (@getIndicatorUrl@) to retrieve the URL of the indicator picture. This was done in order to make the picture customizable by overriding this method.
+
+Once we have our listener in place, we can finally use it in our example overwriting method @updateAjaxAttributes@ of the AJAX button that submits the form:
+
+{code}
+//...
+new AjaxButton("ajaxButton"){
+ @Override
+ protected void updateAjaxAttributes(AjaxRequestAttributes attributes) {
+ super.updateAjaxAttributes(attributes);
+ attributes.getAjaxCallListeners().add(new DisableComponentListener(form));
+ }
+}
+//...
+{code}
+
+h3. Global listeners
+
+So far we have seen how to use an AJAX call listener to track the AJAX activity of a single component. In addition to these kinds of listeners, Wicket provides also global listeners which are triggered for any AJAX request sent from a page.
+
+Global AJAX call events are handled with JavaScript. We can register a callback function for a specific event of the AJAX call lifecycle with function @Wicket.Event.subscribe('<eventName>', <callback Function>)@. The first parameter of this function is the name of the event we want to handle. The possible names are:
+
+* '/ajax/call/before': called before any other event handler.
+* '/ajax/call/beforeSend': called just before the AJAX call.
+* '/ajax/call/after': called after the AJAX request has been sent.
+* '/ajax/call/success': called if the AJAX call has successfully returned.
+* '/ajax/call/failure': called if the AJAX call has returned with a failure.
+* '/ajax/call/complete': called when the AJAX call has completed.
+* '/dom/node/removing': called when a component is about to be removed via AJAX. This happens when component markup is updated via AJAX (i.e. the component itself or one of its containers has been added to @AjaxRequestTarget@)
+* '/dom/node/added': called when a component has been added via AJAX. Just like '/dom/node/removing', this event is triggered when a component is added to @AjaxRequestTarget@.
+
+The callback function takes in input the following parameters: attrs, jqXHR, textStatus, jqEvent and errorThrown. The first three parameters are the same seen before with @IAjaxCallListener@ while jqEvent is an event internally fired by Wicket. The last parameter errorThrown indicates if an error has occurred during the AJAX call.
+
+To see a basic example of use of a global AJAX call listener, let's go back to our custom datepicker created in chapter 14. When we built it we didn't think about a possible use of the component with AJAX. When a complex component like our datepicker is refreshed via AJAX, the following two side effects can occur:
+
+* After been refreshed, the component loses every JavaScript handler set on it. This is not a problem for our datepicker as it sets a new JQuery datepicker every time is rendered (inside method renderHead).
+* The markup previously created with JavaScript is not removed. For our datepicker this means that the icon used to open the calendar won't be removed while a new one will be added each time the component is refreshed.
+
+To solve the second unwanted side effect we can register a global AJAX call listener that completely removes the datepicker functionality from our component before it is removed due to an AJAX refresh (which fires event '/dom/node/removing').
+
+Project @CustomDatepickerAjax@ contains a new version of our datepicker which adds to its JavaScript file JQDatePicker.js the code needed to register a callback function that gets rid of the JQuery datepicker before the component is removed from the DOM:
+
+{code}
+Wicket.Event.subscribe('/dom/node/removing',
+ function(jqEvent, attributes, jqXHR, errorThrown, textStatus) {
+ var componentId = '#' + attributes['id'];
+ if($(componentId).datepicker !== undefined)
+ $(componentId).datepicker('destroy');
+ }
+);
+{code}
+
+The code above retrieves the id of the component that is about to be removed using parameter attributes. Then it checks if a JQuery datepicker was defined for the given component and if so, it removes the widget calling function destroy.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/ajax/ajax_7.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/ajax/ajax_7.gdoc b/wicket-user-guide/src/docs/guide/ajax/ajax_7.gdoc
new file mode 100644
index 0000000..83650d4
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/ajax/ajax_7.gdoc
@@ -0,0 +1,7 @@
+
+
+AJAX is another example of how Wicket can simplify web technologies providing a good component and object oriented abstraction of them.
+
+In this chapter we have seen how to take advantage of the AJAX support provided by Wicket to write AJAX-enhanced applications. Most of the chapter has been dedicated to the built-in components and behaviors that let us adopt AJAX without almost any effort.
+
+In the final part of the chapter we have seen how Wicket physically implements an AJAX call on client side using AJAX request attributes. Then, we have learnt how to use call listeners to execute custom JavaScript during AJAX request lifecycle.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices.gdoc b/wicket-user-guide/src/docs/guide/bestpractices.gdoc
new file mode 100644
index 0000000..711a009
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices.gdoc
@@ -0,0 +1 @@
+This section is addressed to developers, who have already made their first experiences with Apache Wicket. Developers who get into Wicket often have difficulties with it because they apply the typical JSF and Struts patterns and approaches. These frameworks primarily use procedural programming methods. In contrast Wicket is strongly based on object oriented patterns. So forget all Struts and JSF patterns, otherwise you won't have fun with Wicket in the long run.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_1.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_1.gdoc
new file mode 100644
index 0000000..a4403ee
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_1.gdoc
@@ -0,0 +1,119 @@
+
+
+A component should be self-contained. The user of a component should neither have to know nor care about its internal structure. She should just be familiar with its external interfaces and its documentation in order to be able to use it. This means in detail: Every component that extends Wicket's own Panel type (thus is a Panel itself) must provide its own HTML template. In contrast, when a component extends the classes @WebMarkupContainer@ or @Form@, there is no HTML template. This implies that you should add components through composition in @WebMarkupContainer@ or @Form@.
+
+*Listing 1:*
+
+{code}
+// Poor component
+public class RegistrationForm extends Form<Registration> {
+ public RegistrationForm(String id, IModel<Registration> regModel) {
+ super(id, new CompoundPropertyModel<Registration>(regModel))
+ // Wrong: RegistrationForm provides its own components
+ add(new TextField("username"));
+ add(new TextField("firstname"));
+ add(new TextField("lastname"));
+ }
+}
+{code}
+
+This snippet is an example for a poor component. The user of the @RegistrationForm@ must know the internal structure of the markup and component in order to use it.
+
+*Listing 2:*
+
+{code}
+public class RegistrationPage extends Page {
+ public RegistrationPage(IModel<Registration> regModel) {
+ Form<?> form = new RegistrationForm("form");
+ form.add(new SubmitButton("register") {
+ public void onSubmit() {
+ // do something
+ }
+ });
+ add(form);
+ }
+}
+{code}
+
+{code:html}
+<html>
+<body>
+ <form wicket:id="form">
+ <!-- These are internal structure information from RegistrationForm -->
+ Username <input type="text" wicket:id="username"/>
+ First name <input type="text" wicket:id="firstname"/>
+ Last name <input type="text" wicket:id="lastname"/>
+ <!-- Above new components from page which the user knows -->
+ <input type="submit" wicket:id="register" value="Register"/>
+ </form>
+</body>
+</html>
+{code}
+
+The code above shows the usage of the poor component in the @RegistrationPage@. You can see that the input fields @firstname@, @lastname@ and @username@ get used, even though these components are not added explicitly to the @RegistrationPage@. Avoid this, because other developers cannot directly see that the components were added in @RegistrationPage@ class.
+
+*Listing 3:*
+
+{code}
+// Good component
+public class RegistrationInputPanel extends Panel{
+ public RegistrationInputPanel(String id, IModel<Registration> regModel) {
+ super(id, regModel);
+ IModel<Registration> compound = new CompoundPropertyModel<Registration(regmodel)
+ Form<Registration> form = new Form<Registration>("form", compound);
+ // Correct: Add components to Form over the instance variable
+ form.add(new TextField("username"));
+ form.add(new TextField("firstname"));
+ form.add(new TextField("lastname"));
+ add(form);
+ }
+}
+{code}
+
+{code:html}
+<html>
+<body>
+ <wicket:panel>
+ <form wicket:id="form">
+ Username <input type="text" wicket:id="username"/>
+ First name <input type="text" wicket:id="firstname"/>
+ Last name <input type="text" wicket:id="lastname"/>
+ </form>
+ </wicket:panel>
+</body>
+</html>
+{code}
+
+Now we have a properly encapsulated input component which provides its own markup. Furthermore you can see the correct usage of a Wicket @Form@. The components get added by calling @form.add(Component)@ on the instance variable. On the other hand, it is allowed to add behaviours and validators over inheritance, because those do not have markup ids which must be bound.
+
+With that, the usage of @RegistrationInputPanel@ is much more intuitive. There is no markup of other embedded components present anymore, just markup of components which get directly added. The @RegistrationPage@ provides its own form that delegates the submit to all Wicket nested forms which are contained in the component tree.
+
+*Listing 4:*
+
+{code}
+public class RegistrationPage extends Page {
+ public RegistrationPage(IModel<Registration> regModel) {
+ Form<?> form = new Form("form");
+ form.add(new RegistrationInputPanel("registration", regModel);
+ form.add(new SubmitButton("register") {
+ public void onSubmit() {
+ // do something
+ }
+ });
+ add(form);
+ }
+}
+{code}
+
+{code:html}
+<html>
+<body>
+ <form wicket:id="form">
+ <div wicket:id="registration">
+ Display the RegistrationInputPanel
+ </div>
+ <input type=”submit” wicket:id="register" value="Register"/>
+ </form>
+</body>
+</html>
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_10.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_10.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_10.gdoc
new file mode 100644
index 0000000..255d47b
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_10.gdoc
@@ -0,0 +1,62 @@
+
+
+Do not pass entire components or pages to constructors of other components.
+
+*Listing 12:*
+
+{code}
+// Bad solution
+public class SettingsPage extends Page {
+ public SettingsPage (IModel<Settings> settingsModel, final Webpage backToPage) {
+ Form<?> form = new Form("form");
+ // add components
+ form.add(new SubmitButton("changeSettings") {
+ public void onSubmit() {
+ // do something
+ setResponsePage(backToPage);
+ }
+ });
+ add(form);
+ }
+}
+{code}
+
+The @SettingsPage@ expects the page which should be displayed after a successful submit to be passed to its constructor. This solution works, but is very bad practice. You need to know during the instanciation of @SettingsPage@ where you want to redirect the user. This requires a predetermined order of instanciation. It is better to order the instanciation based on business logic (e.g. the order in the HTML template). Furthermore, you need an unnecessary instance of the next success page which might never be displayed. The solution is once again the Hollywood principle. For this you create an abstract method or a hook:
+
+*Listing 13:*
+
+{code}
+// Good solution
+public class SettingsPage extends Page {
+ public SettingsPage (IModel<Settings> settingsModel) {
+ Form<?> form = new Form("form");
+ // add components
+ form.add(new SubmitButton("changeSettings") {
+ public void onSubmit() {
+ // do something
+ onSettingsChanged();
+ }
+ });
+ add(form);
+ }
+
+ // hook
+ protected void onSettingsChanged() {
+ }
+
+// The usage of the new component
+Link<Void> settings = new Link<Void>("settings") {
+ public void onClick() {
+ setResponsePage(new SettingsPage(settingsModel) {
+ @Override
+ protected void onSettingsChanged() {
+ // reference to the current page
+ setResponsePage(this);
+ }
+ });
+ }
+}
+add(settings);
+{code}
+
+This solution has more code, but it is more flexible and reuseable. We can see there is an event @onSettingsChanged()@ and this event is called after a successful change. Furthermore, there is the possibility to execute additional code besides setting the next page. For example, you can display messages or persist information.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_11.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_11.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_11.gdoc
new file mode 100644
index 0000000..0d07209
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_11.gdoc
@@ -0,0 +1,24 @@
+
+
+The Wicket session is your own extension of Wicket's base session. It is fully typed. There is no map structure to store information unlike the servlet session. You just should use Wicket's session for global data. Authentication is a good example for global data. The login and user information is required on nearly each page. For a blog application it would be good to know whether the user is an author who is allowed to compose blog entries. So you are able to hide or or show links to edit a blog entry. In general you should store the whole authorization logic in Wicket's session, because it is a global thing and you would expect it there. Data of forms and flows which only span certain pages should not stored in the session. This data can be passed from one page to the next via the constructor (see listing 14). As a consequence of this, the models and data have a clearly defined lifecycle that reflects the corresponding the page flow.
+
+*Listing 14:*
+
+{code}
+public class MyPage extends WebPage {
+ IModel<MyData> myDataModel;
+
+ public MyPage(IModel<MyData> myDataModel) {
+ this.myDataModel = myDataModel;
+ Link<Void> next = new Link<Void>("next") {
+ public void onClick() {
+ // do something
+ setResponsePage(new NextPage(myDataModel));
+ }
+ }
+ add(next);
+ }
+}
+{code}
+
+You should pass concrete information to the page. All models can simply be stored in fields because Wicket pages are user-specific instances and no singletons in contrast to Struts. The big advantage of this approach is that the data gets automatically cleaned up when a user completes or exits the page flow. No manual cleanup anymore! This is basically an automatic garbage collector for your session.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_12.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_12.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_12.gdoc
new file mode 100644
index 0000000..4926ce8
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_12.gdoc
@@ -0,0 +1,67 @@
+
+
+The factory pattern is useful, but nevertheless not suitable for Wicket components.
+
+*Listing 15:*
+
+{code}
+public class CmsFactory {
+ public Label getCmsLabel(String markupId, final String url) {
+ IModel<String> fragment = new AbstractReadOnlyModel<String>() {
+ @Override
+ public String getObject() {
+ return loadSomeContent(url);
+ }
+ };
+ Label result = new Label(markupId, fragment);
+ result.setRenderBodyOnly(true);
+ result.setEscapeModelStrings(false);
+ return result;
+ }
+
+ public String loadContent(String url) {
+ // load some content
+ }
+}
+
+// create the component within the page:
+public class MyPage extends WebPage {
+ @SpringBean
+ CmsFactory cmsFactory;
+
+ public MyPage() {
+ add(cmsFactory.getCmsLabel("id", "http://url.to.load.from"));
+ }
+}
+{code}
+
+This approach for adding a label from the @CmsFactory@ to a page seems to be okay at first glance, but it comes with some disadvantages. There is no possibility to use inheritance anymore. Furthermore, there is no possibility to override @isVisible()@ and @isEnabled()@. The factory could also be a Spring service which instanciates the component. A better solution is to create a @CmsLabel@.
+
+*Listing 16:*
+
+{code}
+public class CmsLabel extends Label {
+ @SpringBean
+ CmsResource cmsResource;
+ public CmsLabel(String id, IModel<String> urlModel) {
+ super(id, urlModel);
+ IModel<String> fragment = new AbstractReadOnlyModel<String>(){
+ @Override
+ public String getObject() {
+ return cmsResource.loadSomeContent(urlModel.getObject());
+ }
+ };
+ setRenderBodyOnly(true);
+ setEscapeModelStrings(false);
+ }
+}
+
+// create the component within a page
+public class MyPage extends WebPage {
+ public MyPage() {
+ add(new CmsLabel("id", Model.of("http://url.to.load.from")));
+ }
+}
+{code}
+
+The label in listing 16 is clearly encapsulated in a component without using a factory. Now you can easily create inline implementations and override @isVisible()@ or other stuff. Naturally, you might claim "I need a factory to initialize some values in the component, e.g. a Spring service.". For this you can create a implementation of @IComponentInstantiationListener@. This listener gets called on the super-constructor of every component. The most popular implementation of this interface is the @SpringComponentInjector@ which injects Spring beans in components when the fields are annotated with @\@SpringBean@. You can easliy write and add your own implementation of @IComponentInstantiationListener@. So there is no reason for using a factory anymore. More information about the instanciation listener is located in Wicket's JavaDoc.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_13.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_13.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_13.gdoc
new file mode 100644
index 0000000..97a6999
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_13.gdoc
@@ -0,0 +1,3 @@
+
+
+Every page and component should have a test. The simplest test just renders the component and validates its technical correctness. For example, a child component should have a matching wicket id in the markup. If the wicket id is not correctly bound - through a typo or if it was just forgotten - the test will fail. An advanced test could test a form, where a backend call gets executed and validated over a mock. So you can validate your component's behaviour. This is a simple way to detect and fix technical and business logic bugs during the build process. Wicket is very suitable for a test driven development approach. For instance, if you run a unit test which fails and shows a message that the wicket id not bound, you will avoid an unneccessary server startup (a server startup takes longer than running a unit test). This reduces the development turnaround. A disadvantage is the difficult testing possibility of AJAX components. However, the testing features of Wicket are much more s
ophisticated than in other web frameworks.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_14.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_14.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_14.gdoc
new file mode 100644
index 0000000..b16fadd
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_14.gdoc
@@ -0,0 +1,3 @@
+
+
+Try to get within the Wicket world whenever possible. Avoid the usage of other servlet filters. For this you can use the @RequestCycle@ and override the methods @onBeginRequest()@ and @onEndRequest()@. You can apply the same to the @HttpSession@. The equivalent in Wicket is the @WebSession@. Just extend the @WebSession@ and override the @newSession()@-method from the Application class. There are very few reasons to access the servlet interfaces. An example could be to read an external cookie to authenticate a user. Those parts should be properly encapsulated and avoided when possible. For this example, you could do the handling within the Wicket session because this is an authentication.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_15.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_15.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_15.gdoc
new file mode 100644
index 0000000..f6419a4
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_15.gdoc
@@ -0,0 +1,30 @@
+
+
+Avoid monolithic classes. Often I have seen that developers put the whole stuff into constructors. These classes are getting very unclear and chaotic because you use inline implementations over serveral levels. It is recommended to group logical units and extract methods with a correct business naming. This enhances the clarity and the understandability of the business aspect. When a developer navigates to a component, he is not interested in the technical aspect at first, however he just need the business aspect. To retrieve technical information of a component you can navigate to the method implementation. In case of doubt you should consider to extract seperate components. Smaller components increase the chances of reuse and make testing easier. Listing 17 shows an example of a possible structuring.
+
+*Listing 17:*
+
+{code}
+public class BlogEditPage extends WebPage {
+ private IModel<Blog> blogModel;
+
+ public BlogEditPage(IModel<Blog> blogModel) {
+ super(new PageParameters());
+ this.blogModel = blogModel;
+ add(createBlogEditForm());
+ }
+
+ private Form<Blog> createBlogEditForm() {
+ Form<Blog> form = newBlogEditForm();
+ form.add(createHeadlineField());
+ form.add(createContentField());
+ form.add(createTagField());
+ form.add(createViewRightPanel());
+ form.add(createCommentRightPanel());
+ form.setOutputMarkupId(true);
+ return form;
+ }
+
+ // more methods here
+}
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_16.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_16.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_16.gdoc
new file mode 100644
index 0000000..56e5c19
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_16.gdoc
@@ -0,0 +1,5 @@
+
+
+It is a widespread opinion that Wicket has a bad documentation. This argument is just partly correct. There are a lot of code samples and snippets which can be used as code templates. Furthermore, there is a big community that answers complex questions very quickly. In Wicket it is very hard to document everything, because nearly everything is extensible and replaceable. If a component is not completely suitable, you will extend or replace it. Working with Wicket means permanently navigating through code. For example, just consider validators. How can I find all navigators that exist? Open the interface @IValidator@ (Eclipse: Ctrl + Shift + T) and then open the type hierachy (Crtl + T). Now we can see all the validators existing in Wicket and our project.
+
+!validator-type-hierachy.png!
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_17.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_17.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_17.gdoc
new file mode 100644
index 0000000..0b4a29c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_17.gdoc
@@ -0,0 +1,3 @@
+
+
+The best practices presented in this chapter should help you to write better and more maintainable code in Wicket. All described methodologies were already proven in a few Wicket projects. If you follow these advices, your Wicket projects will get future-proof and hopefully successful.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_2.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_2.gdoc
new file mode 100644
index 0000000..9531968
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_2.gdoc
@@ -0,0 +1,3 @@
+
+
+In contrast to Struts, Wicket pages and components are no singletons, they are stateful and session-scoped. This enables us to store user-specific information within pages and components. The information should be stored in fields. This way you can access the information within a class while avoiding long method signatures only for passing the same information around. Instances of components can exist for several requests. For example, a page with a form which gets submitted and produces validation errors uses the same page instance. Furthermore the same page instance gets used when the user presses the back button of the browser and resubmits this formular again. Information which gets passed by the constructor should be assigned to fields (normally this must be models). When storing information in fields you should consider that the information is serializable, because the pages are stored in Wicket's page map. By default the page map stores the pages on the hard disk. A non-seria
lizable object leads to @NullPointerExceptions@ and @NonSerializableExceptions@. Additionally, big data (like binary stuff) should not be stored directly in fields because this can cause performance losses and memory leaks during serialization and deserialization. In this case, you should use the @LoadableDetachableModel@ which can be assigned to a field because this provides an efficient mechanism to load and detach data.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_3.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_3.gdoc
new file mode 100644
index 0000000..56a0dd5
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_3.gdoc
@@ -0,0 +1,5 @@
+
+
+For many developers, naming is a dispensable thing, but I think it is one of the major topics in software development. With the help of correct naming, you can easily identify the business aspects of a software component. Additionally good naming avoids unneccessary and bad comments.
+
+Bad namings for Wicket-IDs are @birthdateTextField@, @firstnameField@ and @addressPanel@. Why? The naming contains two aspects: A technical aspect (_"TextField"_) and the business aspect (_"birthdate"_). Only the the business aspect is relevant because both the HTML template as well as the Java code already contain the technical details ("@new TextField("birthdate")@)". Additionally, such names add a lot of effort when you do technical refactorings, e.g. if you have to replace a @TextField@ by a @DatePicker@ and the Wicket ID @birthdateTextField@ becomes @birthdateDatePicker@. Another reason for avoiding technical aspects in Wicket IDs is the @CompoundPropertyModel@. This model delegates the properties to its child components named by Wicket IDs (see listing 3). For example the @TextField username@ automatically calls @setUsername()@ and @getUsername()@ on the @Registration@ object. A setter like @setUsernameTextfield()@ would be very inconvenient here.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_4.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_4.gdoc
new file mode 100644
index 0000000..0dd5f34
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_4.gdoc
@@ -0,0 +1,17 @@
+
+
+You should consider Wicket's component tree a constant and fixed skeleton which gets revived when its model is filled with data like a robot without brain. Without brain the robot is not able to do anything and is just a dead and fixed skeleton. However, when you fill it with data, it becomes alive and can act. There is no need for changing hardware when filling him with data. In Wicket, you should manipulate the component tree as little as possible. Consequently, you should avoid calling methods like @Component.replace(Component)@ and @Component.remove(Component)@. Calling these methods indicates missing usage or misusage of Wicket's models. Furthermore the component trees should not be constructed using conditions (see listing 5). This reduces the possibility of reusing the same instance significantly.
+
+*Listing 5:*
+
+{code}
+// typical for struts
+if(MySession.get().isNotLoggedIn()) {
+ add(new LoginBoxPanel("login"))
+}
+else {
+ add(new EmptyPanel("login"))
+}
+{code}
+
+Instead of constructing @LoginBoxPanel@ conditionally, it is recommended to always add the panel and control the visibility by overriding @isVisible()@. So the component @LoginBoxPanel@ is responsible for displaying itself. We move the responsibility into the same component which executes the login. Brilliant! Cleanly encapsulated business logic. There is no decision from outside, the component handles all the logic. You can see another example in "Implement visibilities of components correctly".
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_5.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_5.gdoc
new file mode 100644
index 0000000..274f01e
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_5.gdoc
@@ -0,0 +1,47 @@
+
+
+Visibility of components is an important topic. In Wicket you control any component's visibility via the methods @isVisible()@ and @setVisible()@. These methods are within Wicket's base class @Component@ and therefore it is applicable for every component and page. Let's have a look at a concrete example of @LoginBoxPanel@. The panel just gets displayed when the user is not logged in.
+
+*Listing 6:*
+
+{code}
+// Poor implementation
+LoginBoxPanel loginBox = new LoginBoxPanel("login");
+loginBox.setVisible(MySession.get().isNotLoggedIn());
+add(loginBox);
+{code}
+
+Listing 6 shows a poor implementation, because a decision about the visibility is made while instanciating the component. Again, in Wicket instances of components exist for several requests. To reuse the same instance you have to call @loginBox.setVisible(false)@. This is very unhandy, because we always have to call @setVisible()@ and manage the visibility. Furthermore you are going to duplicate the states, because visible is equal to "not logged in". So we have two saved states, one for the business aspect "not logged in" and one for the technical aspect "visible". Both is always equal. This approach is error-prone and fragile, because we always have to pay attention to setting the correct information every time. But this is often forgotten because the logic is widely spread over the code. The solution is the Hollywood principle: "Don't call us, we'll call you.". Take a look at the following diagram illustrating an application flow with some calls. We avoid three calls through the
"Hollywood-Principle":http://en.wikipedia.org/wiki/Hollywood_Principle and we just have to instanciate the @LoginBoxPanel@.
+
+!login_calls_hollywood.png!
+
+*Listing 7:*
+
+{code}
+public class LoginBoxPanel {
+ // constructor etc.
+ @Override
+ public boolean isVisible() {
+ return MySession.get().isNotLoggedIn();
+ }
+};
+{code}
+
+Now the control over visibility has been inverted, the @LoginBoxPanel@ decides on its visibility autonomously. For each call of @isVisible()@ there is a refreshed interpretion of the login state. Hence, there is no additional state that might be outdated. The logic is centralized in one line code and not spread throughout the application. Furthermore, you can easily identify that the technical aspect @isVisible()@ correlates to the business aspect "logged in". The same rules can be applied to the method @isEnabled()@. If @isEnabled()@ returns false the components get displayed in gray. Forms which are within an inactive or invisible component do not get executed.
+
+Note that there are cases in which you cannot avoid to call the methods @setVisible()@ and @setEnabled()@. An example: The user presses a button to display an inlined registration form. In general, you can apply the following rules: data driven components override these methods and delegates to the data model. User triggered events call the method @setVisible(boolean)@. You can also override these methods with inline implementations:
+
+*Listing 8:*
+
+{code}
+new Label("headline", headlineModel) {
+ @Override
+ public boolean isVisible() {
+ // Hidden headline if text starts with "Berlusconi"
+ String headline = getModelObject();
+ return headline.startWith("Berlusconi");
+ }
+}
+{code}
+
+*Note:* Some people insist on overriding @isVisible()@ being [a bad thing|http://www.mail-archive.com/dev\@wicket.apache.org/msg07123.html]. The method @isVisible()@ gets called very often (more than once for each request!), so you have to ensure that the calls within @isVisible()@ are cheap. The main point is that the visibility of a component should be controlled by its own and not be controlled by other components. This avoids a wide-spread logic over the whole application. Another way you can realize this is to override @onConfigure()@ and set the visibility there. This method gets called once during each request.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_6.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_6.gdoc
new file mode 100644
index 0000000..b93574c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_6.gdoc
@@ -0,0 +1,16 @@
+
+
+Always use models - period! Do not pass raw objects directly to components. Instances of pages and components can exist for several requests. If you use raw objects, you cannot replace them later. An example is an entity which gets loaded at each request within a @LoadableDetachableModel@. The entity manager creates a new object reference, but the page would keep the obsolete instance. Always pass @IModel@ in the constructor of your components:
+
+*Listing 9:*
+
+{code}
+public class RegistrationInputPanel extends Panel{
+ // Correct: The class Registration gets wrapped by IModel
+ public RegistrationInputPanel(String id, IModel<Registration> regModel) {
+ // add components
+ }
+}
+{code}
+
+This code can use any implementation of @IModel@, e.g. the class @Model@, a @PropertyModel@ or a custom implementation of @LoadableDetachableModel@ which loads and persists the values automatically. The model implementations gets very easy to replace. You - as a developer - just need to know: if I call @IModel.getObject()@, I will get an object of type @Registration@. Where the object comes from is within the responsibility of the model implementation and the calling component. For example you can pass the model while instanciating the component. If you avoid using models, you will almost certainly have to modify the component tree sooner or later which forces you to duplicate states and thus produce unmaintainable code. Additionally, you should use models due to serialization issues. Objects which get stored in fields of pages and components get serialized and deserialized on each request. This can be inefficient in some cases.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_7.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_7.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_7.gdoc
new file mode 100644
index 0000000..a48313c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_7.gdoc
@@ -0,0 +1,17 @@
+
+
+Avoid unwrapping models within the constructor hierarchy, i.e. do not call @IModel.getObject()@ within any constructor. As already mentioned, a page instance can exist for several page requests, so you might store obsolete and redundant infomation. It is reasonable to unpack Wicket Models at events (user actions), that are methods like @onUpdate()@, @onClick() or @onSubmit()@:
+
+*Listing 10:*
+
+{code}
+new Form("register") {
+ public void onSubmit() {
+ // correct, unwrap model in an event call
+ Registration reg = registrationModel.getObject()
+ userService.register(reg);
+ }
+}
+{code}
+
+An additional possibility to unwrap models is via overriding methods like @isVisible()@, @isEnabled()@ or @onBeforeRender()@.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_8.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_8.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_8.gdoc
new file mode 100644
index 0000000..f094d32
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_8.gdoc
@@ -0,0 +1,14 @@
+
+
+Always try to pass models on to the parent component. By that, you ensure that at the end of every request the method @IModel.detach()@ gets called. This method is responsible for a data cleanup. Another example: you have implemented your own model which persists the data in the @detach()@ method. So the call of @detach()@ is necessary for that your data gets persisted. You can see an exemplary passing to the super constructor here:
+
+*Listing 11:*
+
+{code}
+public class RegistrationInputPanel extends Panel{
+ public RegistrationInputPanel(String id, IModel<Registration> regModel) {
+ super(id, regModel)
+ // add components
+ }
+}
+{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_9.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_9.gdoc b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_9.gdoc
new file mode 100644
index 0000000..de6d08f
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/bestpractices/bestpractices_9.gdoc
@@ -0,0 +1,3 @@
+
+
+Validators should just validate. Consider a bank account form which has a @BankFormValidator@. This validator checks the bank data over a webservice and corrects the bank name. Nobody would expect that a validator modifies information. Such logic has to be located in @Form.onSubmit()@ or in the event logic of a button.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle.gdoc
new file mode 100644
index 0000000..09caf60
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle.gdoc
@@ -0,0 +1 @@
+Just like applets and servlets, also Wicket components follow a lifecycle during their existence. In this chapter we will analyze each stage of this cycle and we will learn how to make the most of the hook methods that are triggered when a component moves from one stage to another.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_1.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_1.gdoc
new file mode 100644
index 0000000..0dded4c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_1.gdoc
@@ -0,0 +1,20 @@
+
+
+During its life a Wicket component goes through three basic stages:
+
+# *Initialization:* a component is instantiated by Wicket and prepared for the rendering phase.
+# *Rendering:* in this stage Wicket generates component markup. If a component contains children (i.e. is a subclass of @MarkupContainer@) it must first wait for them to be rendered before starting its own rendering.
+# *Removing:* this stage is triggered when a component is explicitly removed from its component hierarchy, i.e. when its parent invokes @remove(component)@ on it. This stage is facultative and is never triggered for pages.
+
+The following picture shows the state diagram of component lifecycle:
+
+!component-lifecycle.png!
+
+Once a component has been removed it can be added again to a container, but the initialization stage won't be executed again.
+
+{note}
+If you read the JavaDoc of class @Component@ you will find a more detailed description of component lifecycle.
+However this description introduces some advanced topics we didn't covered yet hence, to avoid confusion, in this chapter some details have been omitted and they will be covered later in the next chapters.
+
+For now you can consider just the simplified version of the lifecycle described above.
+{note}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_2.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_2.gdoc
new file mode 100644
index 0000000..fed387c
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_2.gdoc
@@ -0,0 +1,13 @@
+
+
+Class @Component@ comes with a number of hook methods that can be overridden in order to customize component behavior during its lifecycle.
+In the following table these methods are grouped according to the stage in which they are invoked (and they are sorted by execution order):
+
+{table}
+*Cycle stage* | *Involved methods*
+Initialization | onInitialize
+Rendering | onConfigure, onBeforeRender, onRender, onComponentTag, onComponentTagBody, onAfterRenderChildren, onAfterRender
+Removing | onRemove
+{table}
+
+Now let's take a closer look at each stage and to at hook methods.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_3.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_3.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_3.gdoc
new file mode 100644
index 0000000..61bd996
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_3.gdoc
@@ -0,0 +1,5 @@
+
+
+This stage is performed at the beginning of the component lifecycle. During initialization, the component has already been inserted into its component hierarchy so we can safely access to its parent container or to its page with methods @getParent()@ or @getPage()@. The only method triggered during this stage is @onInitialize()@. This method is a sort of “special” constructor where we can execute a custom initialization of our component.
+
+Since @onInitialize@ is similar to a regular constructor, when we override this method we have to call @super.onInitialize@ inside its body, usually as first instruction.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_4.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_4.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_4.gdoc
new file mode 100644
index 0000000..7710ed7
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_4.gdoc
@@ -0,0 +1,131 @@
+This stage is triggered each time a component is rendered by Wicket, typically when its page is requested or when it is refreshed via AJAX.
+
+h3. Method onConfigure
+
+Method @onConfigure()@ has been introduced in order to provide a good point to manage the component states such as its visibility or enabled state. This method is called before the render phase starts. As stated in [chapter 6.1|guide:keepControl_1], @isVisible@ and @isEnabled@ are called multiple times when a page or a component is rendered, so it's highly recommended not to directly override these method, but rather to use @onConfigure@ to change component states. On the contrary method @onBeforeRender@ (see the next paragraph) is not indicated for this task because it will not be invoked if component visibility is set to false.
+
+h3. Method onBeforeRender
+
+The most important hook method of this stage is probably @onBeforeRender()@. This method is called before a component starts its rendering phase and it is our last chance to change its children hierarchy.
+
+If we want add/remove children components this is the right place to do it. In the next example (project LifeCycleStages) we will create a page which alternately displays two different labels, swapping between them each time it is rendered:
+
+{code}
+public class HomePage extends WebPage
+{
+ private Label firstLabel;
+ private Label secondLabel;
+
+ public HomePage(){
+ firstLabel = new Label("label", "First label");
+ secondLabel = new Label("label", "Second label");
+
+ add(firstLabel);
+ add(new Link("reload"){
+ @Override
+ public void onClick() {
+ }
+ });
+ }
+
+ @Override
+ protected void onBeforeRender() {
+ if(contains(firstLabel, true))
+ replace(secondLabel);
+ else
+ replace(firstLabel);
+
+ super.onBeforeRender();
+ }
+}
+{code}
+
+The code inside @onBeforeRender()@ is quite trivial as it just checks which label among @firstLabel@ and @secondLabel@ is currently inserted into the component hierarchy and it replaces the inserted label with the other one.
+
+This method is also responsible for invoking children @onBeforeRender()@ so if we decide to override it we have to call @super.onBeforeRender()@. However, unlike @onInitialize()@, the call to superclass method should be placed at the end of method's body in order to affect children's rendering with our custom code.
+
+Please note that in the example above we can trigger the rendering stage pressing F5 key or clicking on link “reload”.
+
+{warning}
+If we forget to call superclass version of methods @onInitialize()@ or @onBeforeRender()@, Wicket will throw an @IllegalStateException@ with the following message:
+
+@java.lang.IllegalStateException: @org.apache.wicket.Component@ has not been properly initialized. Something in the hierarchy of <page class name> has not called super.onInitialize()/onBeforeRender() in the override of onInitialize()/ onBeforeRender() method@
+
+{warning}
+
+h3. Method onComponentTag
+
+Method @onComponentTag(ComponentTag)@ is called to process component tag, which can be freely manipulated through its argument of type @org.apache.wicket.markup.ComponentTag@. For example we can add/remove tag attributes with methods @put(String key, String value)@ and @remove(String key)@, or we can even decide to change the tag or rename it with method @setName(String)@ (the following code is taken from project OnComponentTagExample):
+
+*Markup code:*
+
+{code:html}
+<head>
+ <meta charset="utf-8" />
+ <title></title>
+</head>
+<body>
+ <h1 wicket:id="helloMessage"></h1>
+</body>
+{code}
+
+*Java code:*
+
+{code}
+public class HomePage extends WebPage {
+ public HomePage() {
+ add(new Label("helloMessage", "Hello World"){
+ @Override
+ protected void onComponentTag(ComponentTag tag) {
+ super.onComponentTag(tag);
+ //Turn the h1 tag to a span
+ tag.setName("span");
+ //Add formatting style
+ tag.put("style", "font-weight:bold");
+ }
+ });
+ }
+}
+{code}
+
+*Generated markup:*
+
+{code:html}
+<head>
+ <meta charset="utf-8" />
+ <title></title>
+</head>
+<body>
+ <span wicket:id="helloMessage" style="font-weight:bold">Hello World</span>
+</body>
+{code}
+
+Just like we do with @onInitialize@, if we decide to override @onComponentTag@ we must remember to call the same method of the super class because also this class may also customize the tag. Overriding @onComponentTag@ is perfectly fine if we have to customize the tag of a specific component, but if we wanted to reuse the code across different components we should consider to use a behavior in place of this hook method.
+
+We have already seen in [chapter 6.2|guide:keepControl_2] how to use behavior @AttributeModifier@ to manipulate the tag's attribute. In [chapter 17.1|guide:advanced_1] we will see that base class @Behavior@ offers also a callback method named @onComponentTag(ComponentTag, Component)@ that can be used in place of the hook method @onComponentTag(ComponentTag)@.
+
+h3. Methods onComponentTagBody
+
+Method @onComponentTagBody(MarkupStream, ComponentTag)@ is called to process the component tag's body. Just like @onComponentTag@ it takes as input a @ComponentTag@ parameter representing the component tag. In addition, we also find a @MarkupStream@ parameter which represents the page markup stream that will be sent back to the client as response.
+
+@onComponentTagBody@ can be used in combination with the @Component@'s method @replaceComponentTagBody@ to render a custom body under specific conditions. For example (taken from project OnComponentTagExample) we can display a brief description instead of the body if the label component is disabled:
+
+{code}
+public class HomePage extends WebPage {
+ public HomePage() {
+
+ add(new Label("helloMessage", "Hello World"){
+ @Override
+ protected void onComponentTagBody(MarkupStream markupStream, ComponentTag tag) {
+
+ if(!isEnabled())
+ replaceComponentTagBody(markupStream, tag, "(the component is disabled)");
+ else
+ super.onComponentTagBody(markupStream, tag);
+ }
+ });
+ }
+}
+{code}
+
+Note that the original version of @onComponentTagBody@ is invoked only when we want to preserve the standard rendering mechanism for the tag's body (in our example this happens when the component is enabled).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_5.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_5.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_5.gdoc
new file mode 100644
index 0000000..2063663
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_5.gdoc
@@ -0,0 +1,6 @@
+
+
+This stage is triggered when a component is removed from its container hierarchy. The only hook method for this phase is @onRemove()@. If our component still holds some resources needed during rendering phase, we can override this method to release them.
+
+Once a component has been removed we are free to add it again to the same container or to a different one. Starting from version 6.18.0 Wicket added a further hook method called @onReAdd()@ which is triggered every time a previously removed component is re-added to a cointainer.
+Please note that while @onInitialize@ is called only the very first time a component is added, @onReAdd@ is called every time it is re-added after having been removed.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_6.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_6.gdoc b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_6.gdoc
new file mode 100644
index 0000000..0265551
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/componentLifecycle/componentLifecycle_6.gdoc
@@ -0,0 +1,3 @@
+
+
+In this chapter we have seen which stages compose the lifecycle of Wicket components and which hook methods they provide. Overriding these methods we can dynamically modify the component hierarchy and we can enrich the behavior of our custom components.
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/contributing.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/contributing.gdoc b/wicket-user-guide/src/docs/guide/contributing.gdoc
new file mode 100644
index 0000000..65a9d16
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/contributing.gdoc
@@ -0,0 +1,30 @@
+You can contribute to this guide by following these steps:
+
+* The guide uses Grails GDoc to generate the final HTML/PDF so you should consult with its [syntax|http://grails.org/WikiSyntax].
+
+* Checkout Apache Wicket's [site|https://svn.apache.org/repos/asf/wicket/common/site/trunk/_site/]
+{code}
+svn checkout https://svn.apache.org/repos/asf/wicket/common/site/trunk/_site/
+{code}
+
+* Edit the _.gdoc_ files in __site/guide/guide/src/docs/guide_ folder
+
+* To preview your changes you should have [Grails|http://grails.org/] installed.
+** Download it from [here|http://grails.org/download].
+*Note*: Download version *2.2.4*. Newer versions are not supported at the moment.
+** Install it by following these [instructions|http://grails.org/doc/latest/guide/gettingStarted.html#requirements]
+
+* Navigate to __site/guide/guide_ folder and execute
+{code}
+grails doc
+{code}
+
+* To preview your changes open __site/guide/index.html_ in a browser
+
+* Create a patch with
+{code}
+svn diff > my.patch
+{code}
+and attach it to a ticket in Apache Wicket's [JIRA|https://issues.apache.org/jira/browse/WICKET]
+
+*Thank you!*
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/forms2.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/forms2.gdoc b/wicket-user-guide/src/docs/guide/forms2.gdoc
new file mode 100644
index 0000000..138cab5
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/forms2.gdoc
@@ -0,0 +1,5 @@
+In the previous chapter we have only scratched the surface of Wicket forms. The Form component was not only designed to collect user input but also to extend the semantic of the classic HTML forms with new features.
+
+One of such features is the ability to work with nested forms (they will be discussed in paragraph 10.5).
+
+In this chapter we will continue to explore Wicket forms learning how to master them and how to build effective and user-proof forms for our web applications.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/forms2/forms2_1.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_1.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_1.gdoc
new file mode 100644
index 0000000..5920070
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/forms2/forms2_1.gdoc
@@ -0,0 +1,15 @@
+
+
+In paragraph 9.3 we have seen a very basic usage of the Form component and we didn't pay much attention to what happens behind the scenes of form submission. In Wicket when we submit a form we trigger the following steps on server side:
+
+# Form validation: user input is checked to see if it satisfies the validation rules set on the form. If validation fails, step number 2 is skipped and the form should display a feedback message to explain to user what went wrong. During this step input values (which are simple strings sent with a web request) are converted into Java objects. In the next paragraphs we will explore the infrastructures provided by Wicket for the three sub-tasks involved with form validation, which are: conversion of user input into objects, validation of user input, and visualization of feedback messages.
+# Updating of models: if validation succeeds, the form updates the model of its children components with the converted values obtained in the previous step.
+# Invoking callback methods onSubmit() or onError(): if we didn't have any validation error, method onSubmit() is called, otherwise onError() will be called. The default implementation of both these methods is left empty and we can override them to perform custom actions.
+
+{note}
+Please note that the model of form components is updated only if no validation error occurred (i.e. step two is performed only if validation succeeds).
+{note}
+
+Without going into too much detail, we can say that the first two steps of form processing correspond to the invocation of one or more Form's internal methods (which are declared protected and final). Some examples of these methods are validate(), which is invoked during validation step, and updateFormComponentModels(), which is used at the step that updates the form field models.
+
+The whole form processing is started invoking public method process(IFormSubmitter) (Later in paragraph 10.4 we will introduce interface IFormSubmitter).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/wicket/blob/c1da4aef/wicket-user-guide/src/docs/guide/forms2/forms2_10.gdoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/docs/guide/forms2/forms2_10.gdoc b/wicket-user-guide/src/docs/guide/forms2/forms2_10.gdoc
new file mode 100644
index 0000000..0de6193
--- /dev/null
+++ b/wicket-user-guide/src/docs/guide/forms2/forms2_10.gdoc
@@ -0,0 +1,78 @@
+
+
+In chapter 6 we have seen how Wicket pages can be divided into two categories: stateful and stateless. Pages that are stateless don't need to be stored in the user session and they should be used when we don't need to save any user data in the user session (for example in the public area of a site).
+
+Besides saving resources on server-side, stateless pages can be adopted to improve user experience and to avoid security weaknesses. A typical situation where a stateless page can bring these benefits is when we have to implement a login page.
+
+For this kind of page we might encounter two potential problems if we chose to use a stateful page. The first problem occurs when the user tries to login without a valid session assigned to him. This could happen if the user leaves the login page opened for a period of time bigger than the session's timeout and then he decides to log in. Under these conditions the user will be redirected to a 'Page expired' error page, which is not exactly a nice thing for user experience.
+
+The second problem occurs when a malicious user or a web crawler program attempts to login into our web application, generating a huge number of page versions and consequently increasing the size of the user session.
+
+To avoid these kinds of problems we should build a stateless login page which does not depend on a user session. Wicket provides a special version of the Form component called StatelessForm which is stateless by default (i.e its method getStatelessHint() returns true), hence it's an ideal solution when we want to build a stateless page with a form. A possible implementation of our login form is the following (example project StatelessLoginForm):
+
+*HTML:*
+
+{code:html}
+<html>
+ <head>
+ <meta charset="utf-8" />
+ </head>
+ <body>
+ <div>Session is <b wicket:id="sessionType"></b></div>
+ <br/>
+ <div>Type 'user' as correct credentials</div>
+ <form wicket:id="form">
+ <fieldset>
+ Username: <input type="text" wicket:id="username"/> <br/>
+ Password: <input type="password" wicket:id="password"/><br/>
+ <input type="submit"/>
+ </fieldset>
+ </form>
+ <br/>
+ <div wicket:id="feedbackPanel"></div>
+ </body>
+</html>
+{code}
+
+*Java code:*
+
+{code}
+public class HomePage extends WebPage {
+ private Label sessionType;
+ private String password;
+ private String username;
+
+ public HomePage(final PageParameters parameters) {
+ StatelessForm form = new StatelessForm("form"){
+ @Override
+ protected void onSubmit() {
+ //sign in if username and password are “user”
+ if("user".equals(username) && username.equals(password))
+ info("Username and password are correct!");
+ else
+ error("Wrong username or password");
+ }
+ };
+
+ form.add(new PasswordTextField("password"));
+ form.add(new TextField("username"));
+
+ add(form.setDefaultModel(new CompoundPropertyModel(this)));
+
+ add(sessionType = new Label("sessionType", Model.of("")));
+ add(new FeedbackPanel("feedbackPanel"));
+ }
+
+ @Override
+ protected void onBeforeRender() {
+ super.onBeforeRender();
+
+ if(getSession().isTemporary())
+ sessionType.setDefaultModelObject("temporary");
+ else
+ sessionType.setDefaultModelObject("permanent");
+ }
+}
+{code}
+
+Label sessionType shows if current session is temporary or not and is set inside onBeforeRender(): if our page is really stateless the session will be always temporary. We have also inserted a feedback panel in the home page that shows if the credentials are correct. This was done to make the example form more interactive.
\ No newline at end of file