http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_6.adoc b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_6.adoc new file mode 100644 index 0000000..855c3c7 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_6.adoc @@ -0,0 +1,18 @@ + + + +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:* + +[source,java] +---- +public class RegistrationInputPanel extends Panel{ + // Correct: The class Registration gets wrapped by IModel + public RegistrationInputPanel(String id, IModel<Registration> regModel) { + // add components + } +} +---- + +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.
http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_7.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_7.adoc b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_7.adoc new file mode 100644 index 0000000..1c6cf66 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_7.adoc @@ -0,0 +1,19 @@ + + + +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:* + +[source,java] +---- +new Form("register") { + public void onSubmit() { + // correct, unwrap model in an event call + Registration reg = registrationModel.getObject() + userService.register(reg); + } +} +---- + +An additional possibility to unwrap models is via overriding methods like _isVisible()_, _isEnabled()_ or _onBeforeRender()_. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_8.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_8.adoc b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_8.adoc new file mode 100644 index 0000000..8f1725a --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_8.adoc @@ -0,0 +1,17 @@ + + + +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:* + +[source,java] +---- +public class RegistrationInputPanel extends Panel{ + public RegistrationInputPanel(String id, IModel<Registration> regModel) { + super(id, regModel) + // add components + } +} +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_9.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_9.adoc b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_9.adoc new file mode 100644 index 0000000..cff5fa2 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/bestpractices/bestpractices_9.adoc @@ -0,0 +1,4 @@ + + + +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. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle.adoc new file mode 100644 index 0000000..a56e44b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle.adoc @@ -0,0 +1,2 @@ + +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. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc new file mode 100644 index 0000000..bc38266 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_1.adoc @@ -0,0 +1,20 @@ + + + +During its life a Wicket component goes through three basic stages: + +1. *Initialization:* a component is instantiated by Wicket and prepared for the rendering phase. +2. *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. +3. *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: + +image::../img/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. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc new file mode 100644 index 0000000..7eda2e2 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_2.adoc @@ -0,0 +1,14 @@ + + + +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): + +|=== +|*Cycle stage* | *Involved methods* +|Initialization | onInitialize +|Rendering | onConfigure, onBeforeRender, onRender, onComponentTag, onComponentTagBody, onAfterRenderChildren, onAfterRender +|Removing | onRemove +|=== + +Now let's take a closer look at each stage and to at hook methods. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc new file mode 100644 index 0000000..cb6593b --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_3.adoc @@ -0,0 +1,6 @@ + + + +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. http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc new file mode 100644 index 0000000..380933c --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc @@ -0,0 +1,135 @@ + +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. + +=== 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 <<keepControl.adoc#_hiding_or_disabling_a_component,chapter 6.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. + +=== 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: + +[source,java] +---- +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(); + } +} +---- + +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_ + + +=== 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:* + +[source,html] +---- +<head> + <meta charset="utf-8" /> + <title></title> +</head> +<body> + <h1 wicket:id="helloMessage"></h1> +</body> +---- + +*Java code:* + +[source,java] +---- +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"); + } + }); + } +} +---- + +*Generated markup:* + +[source,html] +---- +<head> + <meta charset="utf-8" /> + <title></title> +</head> +<body> + <span wicket:id="helloMessage" style="font-weight:bold">Hello World</span> +</body> +---- + +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 <<keepControl.adoc#_modifing_tag_attributes,chapter 6.2>> how to use behavior _AttributeModifier_ to manipulate the tag's attribute. In <<advanced.adoc#_enriching_components_with_behaviors,chapter 19.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)_. + +=== 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: + +[source,java] +---- +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); + } + }); + } +} +---- + +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). http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc new file mode 100644 index 0000000..5f13e16 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_5.adoc @@ -0,0 +1,8 @@ + + + +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/533c2d36/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc new file mode 100644 index 0000000..50fbb17 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_6.adoc @@ -0,0 +1,5 @@ + + + +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/533c2d36/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc new file mode 100644 index 0000000..68ecc44 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc @@ -0,0 +1,4 @@ + +So far to build component hierarchy we have explicitly added each component and container in accordance with the corresponding markup. This necessary step can involve repetitive and boring code which must be change every time we decide to change markup hierarchy. +Component queueing is a new feature in Wicket 7 that solves this problem allowing Wicket to build component hierarchy in Java automatically making your code simpler and more maintainable. This chapter should serve as a short introduction to what Component Queueing is and what problems it is trying to solve. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_1.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_1.adoc new file mode 100644 index 0000000..74d023f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_1.adoc @@ -0,0 +1,169 @@ + +With Wicket as developers we use to define the hierarchy of components in the markup templates: + +[source,html] +---- +<form wicket:id='customer'> + <input wicket:id='first' type='text'/> + <input wicket:id='last' type='text'/> + <div wicket:id="child"> + <input wicket:id='first' type='text'/> + <input wicket:id='last' type='text'/> + <input wicket:id='dob' type='date'/> + </div> +</form> +---- + +and then we repeat the same hierarchy in Java code: + +[source,java] +---- +Form form=new Form("customer"); +add(form); + +form.add(new TextField("first")); +form.add(new TextField("last")); + +WebMarkupContainer child=new WebMarkupContainer("child"); +form.add(child); + +child.add(new TextField("first")); +child.add(new TextField("last")); +child.add(new TextField("dob")); +---- + +The need for the hierarchy in the markup is obvious, it is simply how the markup works. On the Java side of things it may not be immediately apparent. After all, why can we not write the code like this? + +[source,java] +---- +add(new Form("customer")); +add(new TextField("first")); +add(new TextField("last")); +WebMarkupContainer child=new WebMarkupContainer("child"); +add(child); +add(new TextField("first")); +add(new TextField("last")); +add(new TextField("dob")); +---- + +There are a couple of reasons: + +* Ambiguities that happen with duplicate ids +* Inheriting state from parent to child + +We will examine these below. + +=== Markup Id Ambiguities + +In the example above we have a form that collects the name of a customer along with the name of their child and the childâs date of birth. We mapped the name of the customer and child to form components with wicket ids _first_ and _last_. If we were to add all the components to the same parent we would get an error because we cannot have two components with the same wicket id under the same parent (two components with id _first_ and two with id _last_). +Without hierarchy in Java we would have to make sure that all wicket ids in a markup file are unique, no small feat in a non-trivial page or panel. But, with hierarchy on the Java side we just have to make sure that no parent has two children with the same id, which is trivial. + +=== Inheriting State From Parents + +Suppose we wanted to hide form fields related to the child in the example above when certain conditions are met. Without hierarchy we would have to modify the _first_, _last_, and _dob_ fields to implement the visibility check. Worse, whenever we would add a new child related field we would have to remember to implement the same check; this is a maintenance headache. With hierarchy this is easy, simply hide the parent container and all children will be hidden as well â the code lives in one place and is automatically inherited by all descendant components. Thus, hierarchy on the Java side allows us to write succinct and maintainable code by making use of the parent-child relationship of components. + +=== Pain Points of the Java-Side Hierarchy + +While undeniably useful, the Java-side hierarchy can be a pain to maintain. It is very common to get requests to change things because the designer needs to wrap some components in a _div_ with a dynamic style or class attribute. Essentially we want to go from: + +[source,html] +---- +<form wicket:id='customer'> + <input wicket:id='first' type='text'/> + <input wicket:id='last' type='text'/> +---- + +To: + +[source,java] +---- +<form wicket:id='customer'> + <div wicket:id='container'> + <input wicket:id='first' type='text'/> + <input wicket:id='last' type='text'/> + </div> +---- + +Seems simple enough, but to do so we need to create the new container, find the code that adds all the components that have to be relocated and change it to add to the new container instead. This code: + +[source,java] +---- +Form form=new Form("customer"); +add(form); + +form.add(new TextField("first")); +form.add(new TextField("last")); +---- + +Will become: + +[source,java] +---- +Form form=new Form("customer"); +add(form); + +WebMarkupContainer container=new WebMarkupContainer("container"); +form.add(container); + +container.add(new TextField("first")); +container.add(new TextField("last")); +---- + +Another common change is to tweak the nesting of markup tags. This is something a designer should be able to do on their own if the change is purely visual, but cannot if it means Wicket components will change parents. + +In large pages with a lot of components these kinds of simple changes tend to cause a lot of annoyance for the developers. + +=== Component Queueing To The Rescue + +The idea behind component queueing is simple: instead of adding components to their parents directly, the developer can queue them in any ancestor and have Wicket automatically âdequeueâ them to the correct parent using the hierarchy defined in the markup. This will give us the best of both worlds: the developer only has to define the hierarchy once in markup, and have it automatically constructed in Java land. + +That means we can go from code like this: + +[source,java] +---- +Form form=new Form("customer"); +add(form); + +form.add(new TextField("first")); +form.add(new TextField("last")); + +WebMarkupContainer child=new WebMarkupContainer("child"); +form.add(child); + +child.add(new TextField("first")); +child.add(new TextField("last")); +child.add(new TextField("dob")); +---- + +To code like this: + +[source,java] +---- +queue(new Form("customer")); +queue(new TextField("first")); +queue(new TextField("last")); + +WebMarkupContainer child=new WebMarkupContainer("child"); +queue(child); +child.queue(new TextField("first")); +child.queue(new TextField("last")); +child.queue(new TextField("dob")); +---- + +NOTE: Note that we had to queue childâs _first_ and _last_ name fields to the _child_ container in order to disambiguate their wicket ids. + + +The code above does not look shorter or that much different, so where is the advantage? + +Suppose our designer wants us to wrap the customerâs first and last name fields with a _div_ that changes its styling based on some condition. We saw how to do that above, we had to create a container and then reparent the two _TextField_ components into it. Using queueing we can skip the second step, all we have to do is add the following line: + +[source,java] +---- +queue(new WebMarkupContainer("container")); +---- + +When dequeueing Wicket will automatically reparent the first and last name fields into the container for us. + +If the designer later wanted to move the first name field out of the _div_ we just added for them they could do it all by themselves without requiring any changes in the Java code. Wicket would dequeue the first name field into the form and the last name field into the container div. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_2.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_2.adoc new file mode 100644 index 0000000..f9d9e82 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_2.adoc @@ -0,0 +1,27 @@ + +Auto components, such as Enclosure, are a very useful feature of Wicket, but they have always been a pain to implement and use. + +Suppose we have: + +[source,xml] +---- +<wicket:enclosure childId="first"> + <input wicket:id="first" type="text"/> + <input wicket:id="last" type="text"/> +</wicket:enclosure> +---- + +Together with: + +[source,java] +---- +add(new TextField("first").setRequired(true).setVisible(false)); +add(new TextField("last").setRequired(true)); +---- + +When developing auto components the biggest pain point is in figuring out who the children of the auto component are. In the markup above the enclosure is a parent of the text fields, but in Java it would be a sibling because auto components do not modify the java-side hierarchy. So when the Enclosure is looking for its children it has to parse the markup to figure out what they are. This is not a trivial task. + +Because auto components do not insert themselves properly into the Java hierarchy they are also hard for users to use. For example, the documentation of Enclosure does not recommend it to be used to wrap form components like we have above. When the page renders the enclosure will be hidden because _first_ component is not visible. However, when we submit the form, _last_ component will raise a required error. This is because _last_ is not made a child of the hidden enclosure and therefore does not know its hidden â so it will try to process its input and raise the error. + +Had we used _queue_ instead of _add_ in the code above, everything would work as expected. As part of Queueing implementation Wicket will properly insert auto components into the Java hierarchy. Furthermore, auto components will remain in the hierarchy instead of being added before render and removed afterwords. This is a big improvement because developers will no longer have to parse markup to find the children components â since children will be added to the enclosure by the dequeueing. Likewise, user restrictions are removed as well; the code above would work as expected. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_3.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_3.adoc new file mode 100644 index 0000000..41b7628 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_3.adoc @@ -0,0 +1,7 @@ + +Once you call _queue()_, when are the components dequeued into the page hierarchy? When is it safe to call _getParent()_ or use methods such as _isVisibleInHierarchy()_ which rely on componentâs position in hierarchy? + +The components are dequeued as soon as a path is available from _Page_ to the component they are queued into. The dequeue operation needs access to markup which is only available once the Page is known (because the _Page_ object controls the extension of the markup). + +If the _Page_ is known at the time of the _queue()_ call (eg if its called inside _onInitialize()_) the components are dequeued before _queue()_ returns. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_4.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_4.adoc new file mode 100644 index 0000000..7e013eb --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_4.adoc @@ -0,0 +1,34 @@ + +=== Ancestors + +Suppose on a user profile panel we have the following code: + +[source,java] +---- +queue(new Label("first")); +queue(new Label("last")); + +WebMarkupContainer secure=new WebMarkupContainer("secure") { + void onConfigure() { + super.onConfigure(); + setVisible(isViewingOwnProfile()); + } +}; + +queue(secure); +secure.queue(new Label("creditCardNumber")); +secure.queue(new Label("creditCardExpiry")); +---- + +What is to prevent someone with access to markup from moving the _creditCardNumber_ label out of the _secure_ div, causing a big security problem for the site? + +Wicket will only dequeue components either to the component they are queued to or any of its descendants. + +In the code above this is the reason why we queued the _creditCardNumber_ label into the _secure_ container. That means it can only be dequeued into the _secure_ containerâs hierarchy. + +This restriction allows developers to enforce certain parent-child relationships in their code. + +=== Regions + +Dequeuing of components will not happen across components that implement the _org.apache.wicket.IQueueRegion_ interface. This interface is implemented by all components that provide their own markup such as: _Page_, _Panel_, _Border_, _Fragment_. This is done so that if both a page and panel contain a component with id _foo_ the one queued into the page will not be dequeued into the panel. This minimizes confusion and debugging time. The rule so far is that if a component provides its own markup only components queued inside it will be dequeued into it. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_5.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_5.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_5.adoc new file mode 100644 index 0000000..872ec0f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing/componentQueueing_5.adoc @@ -0,0 +1,3 @@ + +Component queueing is a new and improved way of creating the component hierarchy in Wicket 7. By having to define the hierarchy only once in markup we can make the Java-side code simpler and more maintainable. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/contributing.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/contributing.adoc b/wicket-user-guide/src/main/asciidoc/contributing.adoc new file mode 100644 index 0000000..6115ebc --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/contributing.adoc @@ -0,0 +1,25 @@ + +You can contribute to this guide by following these steps: + +* The guide uses AsciiDoctor to generate the final HTML/PDF so you should consult with its http://asciidoctor.org[syntax] + +* Clone Apache Wicket's GIT repository https://github.com/apache/wicket.git[site] +[source,java] +---- +git clone https://github.com/apache/wicket.git +---- + +* Edit the _.adoc_ files in `wicket/wicket-user-guide/src/main/asciidoctor` folder + +* To preview your changes run [mvn clean package -P guide] in the `wicket/wicket-user-guide` folder (in eclipse use a run configuration) + +* Navigate to _wicket/wicket-user-guide/target/guide/8.x_ and open one of the following files a browser / pdf viewer: +** _guide/single.html_ (single page version) +** _guide/single.pdf_ (single page pdf version) + +* Create a ticket in Apache Wicket's https://issues.apache.org/jira/browse/WICKET[JIRA] + +* *Commit and push the changes* to your forked Apacke Wicket's GIT repository and *create a pull request* on github + +*Thank you!* + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2.adoc b/wicket-user-guide/src/main/asciidoc/forms2.adoc new file mode 100644 index 0000000..ff7a1d4 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2.adoc @@ -0,0 +1,7 @@ + +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 <<forms2.adoc#_nested_forms,paragraph 12.6>>). + +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. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_1.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_1.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_1.adoc new file mode 100644 index 0000000..37214e6 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_1.adoc @@ -0,0 +1,15 @@ + + + +In <<modelsforms.adoc#_models_and_javabeans,paragraph 11.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: + +1. 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. +2. Updating of models: if validation succeeds, the form updates the model of its children components with the converted values obtained in the previous step. +3. 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). + +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 <<forms2.adoc#_submit_form_with_an_iformsubmittingcomponent,paragraph 12.5>> we will introduce interface IFormSubmitter). + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc new file mode 100644 index 0000000..99c4de5 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_10.adoc @@ -0,0 +1,83 @@ + + + +In +<<_page_versioning_and_caching,chapter 8>> 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:* + +[source,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> +---- + +*Java code:* + +[source,java] +---- +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"); + } +} +---- + +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. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc new file mode 100644 index 0000000..50abd02 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc @@ -0,0 +1,199 @@ + + + +In this paragraph we will see which components can be used to handle HTML radio buttons and checkboxes. Both these input elements are usually grouped together to display a list of possible choices: + +image::../img/choice-form-screenshot.png[] + +A check box can be used as single component to set a boolean property. For this purpose Wicket provides the _org.apache.wicket.markup.html.form.CheckBox_ component which must be attached to <input type= ../>[checkbox] tag. In the next example (project SingleCheckBox) we will consider a form similar to the one used in <<modelsforms.adoc#_component_dropdownchoice,paragraph 11.5>> to edit a Person object, but with an additional checkbox to let the user decide if she wants to subscribe to our mailing list or not. The form uses the following bean as backing object: + +[source,java] +---- +public class RegistrationInfo implements Serializable { + + private String name; + private String surname; + private String address; + private String email; + private boolean subscribeList; + + /*Getters and setters*/ +} +---- + +The markup and the code for this example are the following: + +*HTML:* + +[source,html] +---- +<form wicket:id="form"> + <div style="display: table;"> + <div style="display: table-row;"> + <div style="display: table-cell;">Name: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="name"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Surname: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="surname"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Address: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="address"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Email: </div> + <div style="display: table-cell;"> + <input type="text" wicket:id="email"/> + </div> + </div> + <div style="display: table-row;"> + <div style="display: table-cell;">Subscribe list:</div> + <div style="display: table-cell;"> + <input type="checkbox" wicket:id="subscribeList"/> + </div> + </div> + </div> + <input type="submit" value="Save"/> +</form> +---- + +*Java code:* + +[source,java] +---- +public HomePage(final PageParameters parameters) { + RegistrationInfo registrtionInfo = new RegistrationInfo(); + registrtionInfo.setSubscribeList(true); + + Form form = new Form("form", + new CompoundPropertyModel<RegistrationInfo>(registrtionInfo)); + + form.add(new TextField("name")); + form.add(new TextField("surname")); + form.add(new TextField("address")); + form.add(new TextField("email")); + form.add(new CheckBox("subscribeList")); + + add(form); +} +---- + +Please note that the checkbox will be initially selected because we have set to true the subscribe flag during the model object creation (with instruction registrtionInfo.setSubscribeList(true)): + +image::../img/subscribe-checkbox-set.png[] + +=== Working with grouped checkboxes + +When we need to display a given number of options with checkboxes, we can use the _org.apache.wicket.markup.html.form.CheckBoxMultipleChoice_ component. For example, If our options are a list of strings, we can display them in this way: + +*HTML:* + +[source,html] +---- +<div wicket:id="checkGroup"> + <input type="checkbox"/>It will be replaced by the actual checkboxes... +</div> +---- + +*Java code:* + +[source,java] +---- +List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new + ArrayList<String>()), fruits)); +---- + +*Screenshot:* + +image::../img/grouped-checkbox.png[] + +This component can be attached to a <div> tag or to a <span> tag. No specific content is required for this tag as it will be populated with the actual checkboxes. Since this component allows multiple selection, its model object is a list. In the example above we have used model class _org.apache.wicket.model.util.ListModel_ which is specifically designed to wrap a List object. + +By default CheckBoxMultipleChoice inserts a <br/> tag as suffix after each option. We can configure both the suffix and the prefix used by the component with the setPrefix and setSuffix methods. + +When our options are more complex objects than simple strings, we can render them using an IChoiceRender, as we did for DropDownChoice in <<modelsforms.adoc#_component_dropdownchoice,paragraph 11.5>>: + +*HTML:* + +[source,html] +---- +<div wicket:id="checkGroup"> + <input type="checkbox"/>It will be replaced by actual checkboxes... +</div> +---- + +*Java code:* + +[source,java] +---- +Person john = new Person("John", "Smith"); +Person bob = new Person("Bob", "Smith"); +Person jill = new Person("Jill", "Smith"); +List<Person> theSmiths = Arrays.asList(john, bob, jill); +ChoiceRenderer render = new ChoiceRenderer("name"); +form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel<String>(new ArrayList<String>()), + theSmiths, render)); +---- + +*Screenshot:* + +image::../img/grouped-checkbox2.png[] + +=== How to implement a [Select all] checkbox + +A nice feature we can offer to users when we have a group of checkboxes is a âspecialâ checkbox which selects/unselects all the other options of the group: + +image::../img/select-all-checkbox.png[] + +Wicket comes with a couple of utility components that make it easy to implement such a feature. They are CheckboxMultipleChoiceSelector and CheckBoxSelector classes, both inside package _org.apache.wicket.markup.html.form_. The difference between these two components is that the first works with an instance of CheckBoxMultipleChoice while the second takes in input a list of CheckBox objects: + +[source,java] +---- +/* CheckboxMultipleChoiceSelector usage: */ + +CheckBoxMultipleChoice checkGroup; +//checkGroup initialization... +CheckboxMultipleChoiceSelector cbmcs = new CheckboxMultipleChoiceSelector("id", checkGroup); + +/* CheckBoxSelector usage: */ + +CheckBox checkBox1, checkBox2, checkBox3; +//checks initialization... +CheckBoxSelector cbmcs = new CheckBoxSelector("id", checkBox1, checkBox2, checkBox3); +---- + +=== Working with grouped radio buttons + +For groups of radio buttons we can use the _org.apache.wicket.markup.html.form.RadioChoice_ component which works in much the same way as CheckBoxMultipleChoice: + +*HTML:* + +[source,html] +---- +<div wicket:id="radioGroup"> + <input type="radio"/>It will be replaced by actual radio buttons... +</div> +---- + +*Java code:* + +[source,java] +---- +List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new RadioChoice("radioGroup", Model.of(""), fruits)); +---- + +*Screenshot:* + +image::../img/grouped-radiobutton.png[] + +Just like CheckBoxMultipleChoice, this component provides the setPrefix and setSuffix methods to configure the prefix and suffix for our options and it supports IChoiceRender as well. In addition, RadioChoice provides the wantOnSelectionChangedNotifications() method to notify the web server when the selected option changes (this is the same method seen for DropDownChoice in paragraph 9.4). + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_12.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_12.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_12.adoc new file mode 100644 index 0000000..1cf15e6 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_12.adoc @@ -0,0 +1,112 @@ + + + +Checkboxes work well when we have a small amount of options to display, but they quickly become chaotic as the number of options increases. To overcome this limit we can use the <select> tag switching it to multiple-choice mode with attribute multiple= [multiple] +image::../img/list-multiple-choices.png[] + +Now the user can select multiple options by holding down Ctrl key (or Command key for Mac) and selecting them. + +To work with multiple choice list Wicket provides the _org.apache.wicket.markup.html.form.ListMultipleChoice_ component: + +*HTML:* + +[source,html] +---- +<select wicket:id="fruits"> + <option>choice 1</option> + <option>choice 2</option> +</select> +---- + +*Java code:* + +[source,java] +---- +List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new ListMultipleChoice("fruits", new ListModel<String>(new ArrayList<String>()), fruits)); +---- + +*Screenshot:* + +image::../img/list-multiple-choices2.png[] + +This component must be bound to a <select> tag but the attribute multiple= [multiple] is not required as it will automatically be added by the component. + +The number of visible rows can be set with the setMaxRows(int maxRows) method. + +=== Component Palette + +While multiple choice list solves the problem of handling a big number of multiple choices, it is not much intuitive for end users. That's why desktop GUIs have introduced a more complex component which can be generally referred to as multi select transfer component (it doesn't have an actual official name): + +image::../img/multi-select-transfer-component.png[] + +This kind of component is composed by two multiple-choice lists, one on the left displaying the available options and the other one on the right displaying the selected options. User can move options from a list to another by double clicking on them or using the buttons placed between the two list. + +Built-in _org.apache.wicket.extensions.markup.html.form.palette.Palette_ component provides an out-of-the-box implementation of a multi select transfer component. It works in a similar way to ListMultipleChoice: + +*HTML:* + +[source,html] +---- +<div wicket:id="palette"> + Select will be replaced by the actual content... + <select multiple="multiple"> + <option>option1</option> + <option>option2</option> + <option>option3</option> +</div> +---- + +*Java code:* + +[source,java] +---- +Person john = new Person("John", "Smith"); +Person bob = new Person("Bob", "Smith"); +Person jill = new Person("Jill", "Smith"); +Person andrea = new Person("Andrea", "Smith"); + +List<Person> theSmiths = Arrays.asList(john, bob, jill, andrea); +ChoiceRenderer render = new ChoiceRenderer("name"); + +form.add(new Palette("palette", Model.of(new ArrayList<String>()), new ListModel<String> (theSmiths), render, 5, true)); +---- + +*Screenshot:* + +image::../img/multi-select-transfer-component-wicket.png[] + +The last two parameters of the Palette's constructor (an integer value and a boolean value) are, respectively, the number of visible rows for the two lists and a flag to choose if we want to display the two optional buttons which move selected options up and down. The descriptions of the two lists (âAvailableâ and âSelectedâ) can be customized providing two resources with keys palette.available and palette.selected. + +The markup of this component uses a number of CSS classes which can be extended/overriden to customize the style of the component. We can find these classes and see which tags they decorate in the default markup file of the component: + +[source,html] +---- +<table cellspacing="0" cellpadding="2" class="palette"> +<tr> + <td class="header headerAvailable"><span wicket:id="availableHeader">[available header]</span></td> + <td> </td> + <td class="header headerSelected"><span wicket:id="selectedHeader">[selected header]</span> + </td> +</tr> +<tr> + <td class="pane choices"> + <select wicket:id="choices" class="choicesSelect">[choices]</select> + </td> + <td class="buttons"> + <button type="button" wicket:id="addButton" class="button add"><div/> + </button><br/> + <button type="button" wicket:id="removeButton" class="button remove"><div/> + </button><br/> + <button type="button" wicket:id="moveUpButton" class="button up"><div/> + </button><br/> + <button type="button" wicket:id="moveDownButton" class="button down"><div/> + </button><br/> + </td> + <td class="pane selection"> + <select class="selectionSelect" wicket:id="selection">[selection]</select> + </td> +</tr> +</table> +---- + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_13.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_13.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_13.adoc new file mode 100644 index 0000000..d64de39 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_13.adoc @@ -0,0 +1,8 @@ + + +Forms are the standard solution to let users interact with our web applications. In this chapter we have seen the three steps involved with the form processing workflow in Wicket. We have started looking at form validation and feedback messages generation, then we have seen how Wicket converts input values into Java objects and vice versa. + +In the second part of the chapter we learnt how to build reusable form components and how to implement a stateless form. We have ended the chapter with an overview of the built-in form components needed to handle standard input form elements like checkboxes, radio buttons and multiple selections lists. + + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc new file mode 100644 index 0000000..3dac717 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_2.adoc @@ -0,0 +1,287 @@ + + + +A basic example of a validation rule is to make a field required. In <<modelsforms.adoc#_models_and_javabeans,paragraph 11.3>> we have already seen how this can be done calling setRequired(true) on a field. However, to set a validation rule on a FormComponent we must add the corresponding validator to it. + +A validator is an implementation of the _org.apache.wicket.validation.IValidator_ interface and the _FormComponent_ has a version of method add which takes as input a reference of this interface. + +For example if we want to use a text field to insert an email address, we could use the built-in validator EmailAddressValidator to ensure that the inserted input will respect the email format http://en.wikipedia.org/wiki/Email_address[local-part@domain] : + +[source,java] +---- +TextField email = new TextField("email"); +email.add(EmailAddressValidator.getInstance()); +---- + +Wicket comes with a set of built-in validators that should suit most of our needs. We will see them later in this chapter. + +=== Feedback messages and localization + +Wicket generates a feedback message for each field that doesn't satisfy one of its validation rules. For example the message generated when a required field is left empty is the following + +_Field '<label>' is required._ + +<label> is the value of the label model set on a FormComponent with method setLabel(IModel <String> model). If such model is not provided, component id will be used as the default value. + +The entire infrastructure of feedback messages is built on top of the Java internationalization (I18N) support and it uses http://docs.oracle.com/javase/tutorial/i18n/resbundle/index.html[resource bundles] to store messages. + +NOTE: The topics of internationalization will be covered in +<<_internationalization_with_wicket,chapter 15>>. For now we will give just few notions needed to understand the examples from this chapter. + +By default resource bundles are stored into properties files but we can easily configure other sources as described later in <<i18n.adoc#_localization_in_wicket,paragraph 15.2>>. + +Default feedback messages (like the one above for required fields) are stored in the file Application. properties placed inside Wicket the org.apache.wicket package. Opening this file we can find the key and the localized value of the message: + +_Required=Field '$\{label\}' is required._ + +We can note the key (Required in our case) and the label parameter written in the http://en.wikipedia.org/wiki/Expression_Language[expression language] (${label}). Scrolling down this file we can also find the message used by the Email AddressValidator: + +_EmailAddressValidator=The value of '${label}' is not a valid email address._ + +By default FormComponent provides 3 parameters for feedback message: input (the value that failed validation), label and name (this later is the id of the component). + +WARNING: Remember that component model is updated with the user input only if validation succeeds! As a consequence, we can't retrieve the wrong value inserted for a field from its model. Instead, we should use getValue() method of FormComponent class. (This method will be introduced in the example used later in this chapter) + +=== Displaying feedback messages and filtering them + +To display feedback messages we must use component _org.apache.wicket.markup.html.panel.FeedbackPanel_. This component automatically reads all the feedback messages generated during form validation and displays them with an unordered list: + +[source,html] +---- +<ul class="feedbackPanel"> + <li class="feedbackPanelERROR"> + <span class="feedbackPanelERROR">Field 'Username' is required.</span> + </li> +</ul> +---- + +CSS classes [feedbackPanel] and [feedbackPanelERROR] can be used in order to customize the style of the message list: + +image::../img/feedback-panel-style.png[] + +The component can be freely placed inside the page and we can set the maximum amount of displayed messages with the setMaxMessages() method. + +Error messages can be filtered using three built-in filters: + +* *ComponentFeedbackMessageFilter*: shows only messages coming from a specific component. +* *ContainerFeedbackMessageFilter*: shows only messages coming from a specific container or from any of its children components. +* *ErrorLevelFeedbackMessageFilter*: shows only messages with a level of severity equals or greater than a given lower bound. Class FeedbackMessage defines a set of static constants to express different levels of severity: DEBUG, ERROR, WARNING, INFO, SUCCESS, etc.... Levels of severity for feedback messages are discussed later in this chapter. + +These filters are intended to be used when there are more than one feedback panel (or more than one form) in the same page. We can pass a filter to a feedback panel via its constructor or using the setFilter method. Custom filters can be created implementing the IFeedbackMessageFilter interface. An example of custom filter is illustrated later in this paragraph. + +=== Built-in validators + +Wicket already provides a number of built-in validators ready to be used. The following table is a short reference where validators are listed along with a brief description of what they do. The default feedback message used by each of them is reported as well: + +==== EmailAddressValidator + +Checks if input respects the format local-part\_domain. + +*Message:* + +_The value of '${label}' is not a valid email address._ + +==== UrlValidator + +Checks if input is a valid URL. We can specify in the constructor which protocols are allowed (http://, https://, and ftp://). + +*Message:* + +_The value of '${label}' is not a valid URL._ + +==== DateValidator + +Validator class that can be extended or used as a factory class to get date validators to check if a date is bigger than a lower bound (method minimum(Date min)), smaller than a upper bound (method maximum(Date max)) or inside a range (method range(Date min, Date max)). + +*Messages:* + +_The value of '${label}' is less than the minimum of ${minimum}._ + +_The value of '${label}' is larger than the maximum of ${maximum}._ + +_The value of '${label}' is not between ${minimum} and ${maximum}._ + +==== RangeValidator + +Validator class that can be extended or used as a factory class to get validators to check if a value is bigger than a given lower bound (method minimum(T min)), smaller than a upper bound (method maximum(T max)) or inside a range (method range(T min,T max)). + +The type of the value is a generic subtype of java.lang.Comparable and must implement Serializable interface. + +*Messages:* + +_The value of '${label}' must be at least ${minimum}._ + +_The value of '${label}' must be at most ${maximum}._ + +_The value of '${label}' must be between ${minimum} and ${maximum}._ + +==== StringValidator + +Validator class that can be extended or used as a factory class to get validators to check if the length of a string value is bigger then a given lower bound (method minimumLength (int min)), smaller then a given upper bound (method maximumLength (int max)) or within a given range (method lengthBetween(int min, int max)). + +To accept only string values consisting of exactly n characters, we must use method exactLength(int length). + +*Messages:* + +_The value of '${label}' is shorter than the minimum of ${minimum} characters._ + +_The value of '${label}' is longer than the maximum of ${maximum} characters._ + +_The value of '${label}' is not between ${minimum} and ${maximum} characters long._ + +_The value of '${label}' is not exactly ${exact} characters long._ + +==== CreditCardValidator + +Checks if input is a valid credit card number. This validator supports some of the most popular credit cards (like âAmerican Express ["MasterCard] , âVisaâ or âDiners Clubâ). + +*Message:* + +_The credit card number is invalid._ + +==== EqualPasswordInputValidator + +This validator checks if two password fields have the same value. + +*Message:* + +_${label0} and ${label1} must be equal._ + +=== Overriding standard feedback messages with custom bundles + +If we don't like the default validation feedback messages, we can override them providing custom properties files. In these files we can write our custom messages using the same keys of the messages we want to override. For example if we wanted to override the default message for invalid email addresses, our properties file would contain a line like this: + +_EmailAddressValidator=Man, your email address is not good!_ + +As we will see in the next chapter, Wicket searches for custom properties files in various positions inside the application's class path, but for now we will consider just the properties file placed next to our application class. The name of this file must be equal to the name of our application class: + +image::../img/custom-properties-file.png[] + +The example project OverrideMailMessage overrides email validator's message with a new one which also reports the value that failed validation: + +_EmailAddressValidator=The value '${input}' inserted for field '${label}' is not a valid email address._ + +image::../img/validation-error-message.png[] + +=== Creating custom validators + +If our web application requires a complex validation logic and built-in validators are not enough, we can implement our own custom validators. For example (project UsernameCustomValidator) suppose we are working on the registration page of our site where users can create their profile choosing their username. Our registration form should validate the new username checking if it was already chosen by another user. In a situation like this we may need to implement a custom validator that queries a specific data source to check if a username is already in use. + +For the sake of simplicity, the validator of our example will check the given username against a fixed list of three existing usernames. + +A custom validator must simply implement interface IValidator: + +[source,java] +---- +public class UsernameValidator implements IValidator<String> { + List<String> existingUsernames = Arrays.asList("bigJack", "anonymous", "mrSmith"); + + public void validate(IValidatable<String> validatable) { + String chosenUserName = validatable.getValue(); + + if(existingUsernames.contains(chosenUserName)){ + ValidationError error = new ValidationError(this); + Random random = new Random(); + + error.setVariable("suggestedUserName", + validatable.getValue() + random.nextInt()); + validatable.error(error); + } + } +} +---- + +The only method defined inside IValidator is validate(IValidatable<T> validatable) and is invoked during validation's step. Interface IValidatable represents the component being validated and it can be used to retrieve the component model (getModel()) or the value to validate (getValue()). + +The custom validation logic is all inside IValidator's method validate. When validation fails a validator must use IValidatable's method error(IValidationError error) to generate the appropriate feedback message. In the code above we used the ValidationError class as convenience implementation of the IValidationError interface which represents the validation error that must be displayed to the user. This class provides a constructor that uses the class name of the validator in input as key for the resource to use as feedback message (i.e. 'UsernameValidator' in the example). If we want to specify more then one key to use to locate the error message, we can use method addKey(String key) of ValidationError class. + +In our example when validation fails, we suggest a possible username concatenating the given input with a pseudo-random integer. This value is passed to the feedback message with a variable named suggestedUserName. The message is inside application's properties file: + +_UsernameValidator=The username '${input}' is already in use. Try with '${suggestedUserName}'_ + +To provide further variables to our feedback message we can use method setVariable(String name, Object value) of class ValidationError as we did in our example. + +The code of the home page of the project will be examined in the next paragraph after we have introduced the topic of flash messages. + +=== Using flash messages + +So far we have considered just the error messages generated during validation step. However Wicket's Component class provides a set of methods to explicitly generate feedback messages called flash messages. These methods are: + +* debug(Serializable message) +* info(Serializable message) +* success(Serializable message) +* warn(Serializable message) +* error(Serializable message) +* fatal(Serializable message) + +Each of these methods corresponds to a level of severity for the message. The list above is sorted by increasing level of severity. + +In the example seen in the previous paragraph we have a form which uses success method to notify user when the inserted username is valid. Inside this form there are two FeedbackPanel components: one to display the error message produced by custom validator and the other one to display the success message. The code of the example page is the following: + +*HTML:* + +[source,html] +---- +<body> + <form wicket:id="form"> + Username: <input type="text" wicket:id="username"/> + <br/> + <input type="submit"/> + </form> + <div style="color:green" wicket:id="succesMessage"> + </div> + <div style="color:red" wicket:id="feedbackMessage"> + </div> +</body> +---- + +*Java code:* + +[source,java] +---- +public class HomePage extends WebPage { + + public HomePage(final PageParameters parameters) { + Form form = new Form("form"){ + @Override + protected void onSubmit() { + super.onSubmit(); + success("Username is good!"); + } + }; + + TextField mail; + + form.add(mail = new TextField("username", Model.of(""))); + mail.add(new UsernameValidator()); + + add(new FeedbackPanel("feedbackMessage", + new ExactErrorLevelFilter(FeedbackMessage.ERROR))); + add(new FeedbackPanel("succesMessage", + new ExactErrorLevelFilter(FeedbackMessage.SUCCESS))); + + add(form); + } + + class ExactErrorLevelFilter implements IFeedbackMessageFilter{ + private int errorLevel; + + public ExactErrorLevelFilter(int errorLevel){ + this.errorLevel = errorLevel; + } + + public boolean accept(FeedbackMessage message) { + return message.getLevel() == errorLevel; + } + + } + //UsernameValidator definition + //... +} +---- + +The two feedback panels must be filtered in order to display just the messages with a given level of severity (ERROR for validator message and SUCCESS for form's flash message). Unfortunately the built-in message filter ErrorLevelFeedbackMessageFilter is not suitable for this task because its filter condition does not check for an exact error level (the given level is used as lower bound value). As a consequence, we had to build a custom filter (inner class ExactErrorLevelFilter) to accept only the desired severity level (see method accept of interface IFeedbackMessageFilter). + +NOTE: Since version 6.13.0 Wicket provides the additional filter class org.apache.wicket.feedback.ExactLevelFeedbackMessageFilter to accept only feedback messages of a certain error level. + + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_3.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_3.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_3.adoc new file mode 100644 index 0000000..1eada76 --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_3.adoc @@ -0,0 +1,142 @@ + + + +Working with Wicket we will rarely need to worry about conversion between input values (which are strings because the underlying HTTP protocol) and Java types because in most cases the default conversion mechanism will be smart enough to infer the type of the model object and perform the proper conversion. However, sometimes we may need to work under the hood of this mechanism to make it properly work or to perform custom conversions. That's why this paragraph will illustrate how to control input value conversion. + +The component that is responsible for converting input is the FormComponent itself with its convertInput() method. In order to convert its input a FormComponent must know the type of its model object. This parameter can be explicitly set with method setType(Class<?> type): + +[source,java] +---- +//this field must receive an integer value +TextField integerField = new TextField("number", new Model()).setType(Integer.class)); +---- + +If no type has been provided, FormComponent will try to ask its model for this information. The PropertyModel and CompoundPropertyModel models can use reflection to get the type of object model. By default, if FormComponent can not obtain the type of its model object in any way, it will consider it as a simple String. + +Once FormComponent has determined the type of model object, it can look up for a converter, which is the entity in charge of converting input to Java object and vice versa. Converters are instances of _org.apache.wicket.util.convert.IConverter_ interface and are registered by our application class on start up. + +To get a converter for a specific type we must call method getConverter(Class<C> type) on the interface IConverterLocator returned by Application's method getConverterLocator(): + +[source,java] +---- +//retrieve converter for Boolean type +Application.get().getConverterLocator().getConverter(Boolean.class); +---- + +NOTE: Components which are subclasses of AbstractSingleSelectChoice don't follow the schema illustrated above to convert user input. + +These kinds of components (like DropDownChoice and RadioChoice1) use their choice render and their collection of possible choices to perform input conversion. + +=== Creating custom application-scoped converters + +The default converter locator used by Wicket is _org.apache.wicket.ConverterLocator_. This class provides converters for the most common Java types. Here we can see the converters registered inside its constructor: + +[source,java] +---- +public ConverterLocator() +{ + set(Boolean.TYPE, BooleanConverter.INSTANCE); + set(Boolean.class, BooleanConverter.INSTANCE); + set(Byte.TYPE, ByteConverter.INSTANCE); + set(Byte.class, ByteConverter.INSTANCE); + set(Character.TYPE, CharacterConverter.INSTANCE); + set(Character.class, CharacterConverter.INSTANCE); + set(Double.TYPE, DoubleConverter.INSTANCE); + set(Double.class, DoubleConverter.INSTANCE); + set(Float.TYPE, FloatConverter.INSTANCE); + set(Float.class, FloatConverter.INSTANCE); + set(Integer.TYPE, IntegerConverter.INSTANCE); + set(Integer.class, IntegerConverter.INSTANCE); + set(Long.TYPE, LongConverter.INSTANCE); + set(Long.class, LongConverter.INSTANCE); + set(Short.TYPE, ShortConverter.INSTANCE); + set(Short.class, ShortConverter.INSTANCE); + set(Date.class, new DateConverter()); + set(Calendar.class, new CalendarConverter()); + set(java.sql.Date.class, new SqlDateConverter()); + set(java.sql.Time.class, new SqlTimeConverter()); + set(java.sql.Timestamp.class, new SqlTimestampConverter()); + set(BigDecimal.class, new BigDecimalConverter()); +} +---- + +If we want to add more converters to our application, we can override Application's method newConverterLocator which is used by application class to build its converter locator. + +To illustrate how to implement custom converters and use them in our application, we will build a form with two text field: one to input a regular expression pattern and another one to input a string value that will be split with the given pattern. + +The first text field will have an instance of class java.util.regex.Pattern as model object. The final page will look like this (the code of this example is from the CustomConverter project): + +image::../img/regex-form.png[] + +The conversion between Pattern and String is quite straightforward. The code of our custom converter is the following: + +[source,java] +---- +public class RegExpPatternConverter implements IConverter<Pattern> { + @Override + public Pattern convertToObject(String value, Locale locale) { + return Pattern.compile(value); + } + + @Override + public String convertToString(Pattern value, Locale locale) { + return value.toString(); + } +} +---- + +Methods declared by interface IConverter take as input a Locale parameter in order to deal with locale-sensitive data and conversions. We will learn more about locales and internationalization in +<<_internationalization_with_wicket,paragraph 15>>. + +Once we have implemented our custom converter, we must override method newConverterLocator() inside our application class and tell it to add our new converter to the default set: + +[source,java] +---- +@Override + protected IConverterLocator newConverterLocator() { + ConverterLocator defaultLocator = new ConverterLocator(); + + defaultLocator.set(Pattern.class, new RegExpPatternConverter()); + + return defaultLocator; + } +---- + +Finally, in the home page of the project we build the form which displays (with a flash message) the tokens obtained splitting the string with the given pattern: + +[source,java] +---- +public class HomePage extends WebPage { + private Pattern regExpPattern; + private String stringToSplit; + + public HomePage(final PageParameters parameters) { + TextField regExpPatternTxt; + TextField stringToSplitTxt; + + Form form = new Form("form"){ + @Override + protected void onSubmit() { + super.onSubmit(); + String messageResult = "Tokens for the given string and pattern:<br/>"; + String[] tokens = regExpPattern.split(stringToSplit); + + for (String token : tokens) { + messageResult += "- " + token + "<br/>"; + } + success(messageResult); + } + }; + + form.setDefaultModel(new CompoundPropertyModel(this)); + form.add(regExpPatternTxt = new TextField("regExpPattern")); + form.add(stringToSplitTxt = new TextField("stringToSplit")); + add(new FeedbackPanel("feedbackMessage").setEscapeModelStrings(false)); + + add(form); + } +} +---- + +NOTE: If the user input can not be converted to the target type, FormComponent will generate the default error message âThe value of '${label}' is not a valid ${type}.â. The bundle key for this message is IConverter. + http://git-wip-us.apache.org/repos/asf/wicket/blob/533c2d36/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc ---------------------------------------------------------------------- diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc new file mode 100644 index 0000000..16cfc7f --- /dev/null +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc @@ -0,0 +1,89 @@ + +Standard JSR 303 defines a set of annotations and APIs to validate our domain objects at field-level. Wicket has introduced an experimental support for this standard since version 6.4.0 and with version 6.14.0 it has became an official Wicket module (named _wicket-bean-validation_). +In this paragraph we will see the basic steps needed to use JSR 303 validation in our Wicket application. Code snippets are from example project _JSR303validation_. + +In the example application we have a form to insert the data for a new _Person_ bean and its relative _Address_. The code for class _Person_ is the following + +[source,java] +---- +public class Person implements Serializable{ + + @NotNull + private String name; + + //regular expression to validate an email address + @Pattern(regexp = "^[_A-Za-z0-9-]+(.[_A-Za-z0-9-]+)*[A-Za-z0-9-]+(.[A-Za-z0-9-]+)*((.[A-Za-z]{2,}){1}$)") + private String email; + + @Range(min = 18, max = 150) + private int age; + + @Past @NotNull + private Date birthDay; + + @NotNull + private Address address; +} +---- + +You can note the JSR 303 annotations used in the code above to declare validation constraints on class fields. Class _Address_ has the following code: + +[source,java] +---- +public class Address implements Serializable { + + @NotNull + private String city; + + @NotNull + private String street; + + @Pattern(regexp = "\\d+", message = "{address.invalidZipCode}") + private String zipCode; +} +---- + +You might have noted that in class _Address_ we have used annotation _Pattern using also attribute _message_ which contains the key of the bundle to use for validation message. Our custom bundle is contained inside _HomePage.properties_: + +[source,java] +---- +address.invalidZipCode=The inserted zip code is not valid. +---- + +To tell Wicket to use JSR 303, we must register bean validator on Application's startup: + +[source,java] +---- +public class WicketApplication extends WebApplication { + @Override + public void init(){ + super.init(); + + new BeanValidationConfiguration().configure(this); + } +} +---- + +The last step to harness JSR 303 annotations is to add validator _org.apache.wicket.bean.validation.PropertyValidator_ to our corresponding form components: + +[source,java] +---- +public HomePage(final PageParameters parameters) { + super(parameters); + + setDefaultModel(new CompoundPropertyModel<Person>(new Person())); + + Form<Void> form = new Form<Void>("form"); + + form.add(new TextField("name").add(new PropertyValidator())); + form.add(new TextField("email").add(new PropertyValidator())); + form.add(new TextField("age").add(new PropertyValidator())); + //... +} +---- + +Now we can run our application an see that JSR 303 annotations are fully effective: + +image::../img/jsr303-form-validation.png[] + +
