From 481633efc3fc611b3c2e31c3a24356a692fda5ec Mon Sep 17 00:00:00 2001 From: Jan Mewes Date: Fri, 23 Nov 2018 09:45:06 +0100 Subject: [PATCH] Fix typos in documentation --- .../componentLifecycle_4.adoc | 36 ++++++++--------- .../src/main/asciidoc/componentQueueing.adoc | 3 +- .../src/main/asciidoc/contributing.adoc | 5 +-- .../src/main/asciidoc/forms2/forms2_11.adoc | 39 +++++++++---------- .../src/main/asciidoc/forms2/forms2_4.adoc | 34 ++++++++-------- .../src/main/asciidoc/forms2/forms2_6.adoc | 12 +++--- .../asciidoc/helloWorld/helloWorld_1.adoc | 3 +- .../asciidoc/keepControl/keepControl_5.adoc | 5 +-- .../asciidoc/modelsforms/modelsforms_2.adoc | 13 +++---- .../asciidoc/modelsforms/modelsforms_3.adoc | 29 +++++++------- .../asciidoc/modelsforms/modelsforms_4.adoc | 37 +++++++++--------- .../asciidoc/modelsforms/modelsforms_5.adoc | 8 ++-- .../asciidoc/modelsforms/modelsforms_6.adoc | 12 +++--- .../asciidoc/modelsforms/modelsforms_9.adoc | 4 +- .../src/main/asciidoc/redirects.adoc | 4 +- .../requestProcessing_2.adoc | 4 +- .../requestProcessing_4.adoc | 2 +- .../versioningCaching_1.adoc | 2 +- .../versioningCaching_2.adoc | 2 +- .../main/asciidoc/whyLearn/whyLearn_4.adoc | 2 +- 20 files changed, 122 insertions(+), 134 deletions(-) diff --git a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc index 4cdd67225ad..e811917efed 100644 --- a/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/componentLifecycle/componentLifecycle_4.adoc @@ -3,7 +3,7 @@ This stage is reached each time a component is rendered, typically when a page i === 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 an all components whose parent is visible. +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 on all components whose parent is visible. As stated in <<_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. @@ -23,7 +23,7 @@ public class HomePage extends WebPage public HomePage(){ firstLabel = new Label("label", "First label"); secondLabel = new Label("label", "Second label"); - + add(firstLabel); add(new Link("reload"){ @Override @@ -31,14 +31,14 @@ public class HomePage extends WebPage } }); } - + @Override protected void onBeforeRender() { if(contains(firstLabel, true)) replace(secondLabel); else replace(firstLabel); - + super.onBeforeRender(); } } @@ -46,7 +46,7 @@ public class HomePage extends WebPage 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. +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”. @@ -59,7 +59,7 @@ This method gives all components the possibility to add items to the page header === Method onRender -This method does the actual rendering - you will rarely have to implement it, since most components already contain a specific implementation to produce their markup. +This method does the actual rendering -- you will rarely have to implement it, since most components already contain a specific implementation to produce their markup. === Method onComponentTag @@ -73,8 +73,8 @@ Method _onComponentTag(ComponentTag)_ is called to process a component tag, whic - -

+ +

---- @@ -86,7 +86,7 @@ public class HomePage extends WebPage { public HomePage() { add(new Label("helloMessage", "Hello World"){ @Override - protected void onComponentTag(ComponentTag tag) { + protected void onComponentTag(ComponentTag tag) { super.onComponentTag(tag); //Turn the h1 tag to a span tag.setName("span"); @@ -106,8 +106,8 @@ public class HomePage extends WebPage { - - Hello World + + Hello World ---- @@ -117,7 +117,7 @@ We have already seen in <<_modifing_tag_attributes,chapter 6.2>> how to use beha === 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. +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: @@ -128,14 +128,14 @@ public class HomePage extends WebPage { add(new Label("helloMessage", "Hello World"){ @Override - protected void onComponentTagBody(MarkupStream markupStream, ComponentTag tag) { - + protected void onComponentTagBody(MarkupStream markupStream, ComponentTag tag) { + if(!isEnabled()) - replaceComponentTagBody(markupStream, tag, "(the component is disabled)"); - else + replaceComponentTagBody(markupStream, tag, "(the component is disabled)"); + else super.onComponentTagBody(markupStream, tag); } - }); + }); } } ---- @@ -144,4 +144,4 @@ Note that the original version of _onComponentTagBody_ is invoked only when we w === Methods onAfterRender -Called on each rendered component immediately after it has been rendered - _onAfterRender()_ will even be called when rendering failed with an exception. \ No newline at end of file +Called on each rendered component immediately after it has been rendered - _onAfterRender()_ will even be called when rendering failed with an exception. diff --git a/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc b/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc index 68ecc4465b2..24ab3506366 100644 --- a/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc +++ b/wicket-user-guide/src/main/asciidoc/componentQueueing.adoc @@ -1,4 +1,3 @@ -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. +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 changed 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. - diff --git a/wicket-user-guide/src/main/asciidoc/contributing.adoc b/wicket-user-guide/src/main/asciidoc/contributing.adoc index e338e23cfab..a70e17f9091 100644 --- a/wicket-user-guide/src/main/asciidoc/contributing.adoc +++ b/wicket-user-guide/src/main/asciidoc/contributing.adoc @@ -3,7 +3,7 @@ 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] -* Fork Apache Wicket's GIT https://github.com/apache/wicket.git[repository] to your own github account. +* Fork Apache Wicket's GIT https://github.com/apache/wicket.git[repository] to your own github account * Clone your forked copy of Apache Wicket's repository into your machine [source,java] @@ -11,7 +11,7 @@ You can contribute to this guide by following these steps: git clone https://github.com/<>/wicket.git ---- -* Edit the _.adoc_ files in `wicket/wicket-user-guide/src/main/asciidoctor` folder +* 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 (You may use a run configuration in your IDE) @@ -24,4 +24,3 @@ git clone https://github.com/<>/wicket.git * *Commit and push the changes* to your forked Apache Wicket's GIT repository and *create a pull request* on github (Enter the created JIRA ticket id into your pull request's title) *Thank you!* - diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc index ae67daad45a..bf3f93fa6fb 100644 --- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_11.adoc @@ -10,13 +10,13 @@ A check box can be used as single component to set a boolean property. For this [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*/ } ---- @@ -27,25 +27,25 @@ The markup and the code for this example are the following: [source,html] ---- -
+
Name:
- -
+ +
Surname:
-
+
Address:
-
+
Email:
@@ -59,7 +59,7 @@ The markup and the code for this example are the following:
- +
---- @@ -71,16 +71,16 @@ The markup and the code for this example are the following: public HomePage(final PageParameters parameters) { RegistrationInfo registrtionInfo = new RegistrationInfo(); registrtionInfo.setSubscribeList(true); - - Form form = new Form<>("form", - new CompoundPropertyModel(registrtionInfo)); - + + Form form = new Form<>("form", + new CompoundPropertyModel(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); } ---- @@ -91,7 +91,7 @@ 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: +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:* @@ -106,8 +106,8 @@ When we need to display a given number of options with checkboxes, we can use th [source,java] ---- -List fruits = Arrays.asList("apple", "strawberry", "watermelon"); -form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel(new +List fruits = Arrays.asList("apple", "strawberry", "watermelon"); +form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel(new ArrayList()), fruits)); ---- @@ -137,9 +137,9 @@ When our options are more complex objects than simple strings, we can render the Person john = new Person("John", "Smith"); Person bob = new Person("Bob", "Smith"); Person jill = new Person("Jill", "Smith"); -List theSmiths = Arrays.asList(john, bob, jill); +List theSmiths = Arrays.asList(john, bob, jill); ChoiceRenderer render = new ChoiceRenderer("name"); -form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel(new ArrayList()), +form.add(new CheckBoxMultipleChoice("checkGroup", new ListModel(new ArrayList()), theSmiths, render)); ---- @@ -187,7 +187,7 @@ For groups of radio buttons we can use the _org.apache.wicket.markup.html.form.R [source,java] ---- -List fruits = Arrays.asList("apple", "strawberry", "watermelon"); +List fruits = Arrays.asList("apple", "strawberry", "watermelon"); form.add(new RadioChoice("radioGroup", Model.of(""), fruits)); ---- @@ -196,4 +196,3 @@ form.add(new RadioChoice("radioGroup", Model.of(""), fruits)); 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. - diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc index 16cfc7fddd4..70a48297891 100644 --- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_4.adoc @@ -7,22 +7,22 @@ In the example application we have a form to insert the data for a new _Person_ [source,java] ---- public class Person implements Serializable{ - + @NotNull private String name; - - //regular expression to validate an email address + + //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 int age; + + @Past @NotNull private Date birthDay; - + @NotNull - private Address address; + private Address address; } ---- @@ -31,26 +31,26 @@ You can note the JSR 303 annotations used in the code above to declare validatio [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_: +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: +To tell Wicket to use JSR 303, we must register bean validator on Application's startup: [source,java] ---- @@ -72,9 +72,9 @@ public HomePage(final PageParameters parameters) { super(parameters); setDefaultModel(new CompoundPropertyModel(new Person())); - + Form form = new Form("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())); @@ -85,5 +85,3 @@ public HomePage(final PageParameters parameters) { Now we can run our application an see that JSR 303 annotations are fully effective: image::../img/jsr303-form-validation.png[] - - diff --git a/wicket-user-guide/src/main/asciidoc/forms2/forms2_6.adoc b/wicket-user-guide/src/main/asciidoc/forms2/forms2_6.adoc index 7d3666488a5..3eb99d5bf79 100644 --- a/wicket-user-guide/src/main/asciidoc/forms2/forms2_6.adoc +++ b/wicket-user-guide/src/main/asciidoc/forms2/forms2_6.adoc @@ -1,24 +1,24 @@ -As you might already known, HTLM doesn't allow to have nested forms. However with Wicket we can overcome this limitation by adding one or more form components to a parent form. +As you might already known, HTML doesn't allow to have nested forms. However with Wicket we can overcome this limitation by adding one or more form components to a parent form. This can be useful if we want to split a big form into smaller ones in order to reuse them and to better distribute responsibilities among different components. Forms can be nested to an arbitrary level: [source,html] ---- -
+ ... - + ... ... -
- + + ---- When a form is submitted also its nested forms are submitted and they participate in the validation step. This means that if a nested form contains invalid input values, the outer form won't be submitted. On the contrary, nested forms can be singularly submitted without depending on the status of their outer form. -To submit a parent form when one of its children forms is submitted, we must override its method wantSubmitOnNestedFormSubmit and make it return true. +To submit a parent form when one of its children forms is submitted, we must override its method wantSubmitOnNestedFormSubmit and make it return true. diff --git a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_1.adoc b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_1.adoc index 5dac973877d..b7c750b0160 100644 --- a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_1.adoc +++ b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_1.adoc @@ -2,7 +2,7 @@ Wicket is available as a binary package on the main site http://wicket.apache.org[http://wicket.apache.org] . Inside this archive we can find the distribution jars of the framework. Each jar corresponds to a sub-module of the framework. The following table reports these modules along with a short description of their purpose and with the related dependencies: |=== -| *Module'sname* | *Description* | *Dependencies* +| *Module's name* | *Description* | *Dependencies* | wicket-core | Contains the main classes of the framework, like class _Component_ and _Application_. | wicket-request, wicket-util | wicket-request | This module contains the classes involved into web request processing. | wicket-util | wicket-util | Contains general-purpose utility classes for functional areas such as I/O, lang, string manipulation, security, etc... | None @@ -19,4 +19,3 @@ Wicket is available as a binary package on the main site http://wicket.apache.o |=== Please note that the core module depends on the utility and request modules, hence it cannot be used without them. - diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc index e44f3f193fc..8efb2dc00a5 100644 --- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc +++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc @@ -1,5 +1,5 @@ -Another circumstance in which we may prefer to avoid the creation of custom panels is when we want to conditionally display in a page small fragments of markup. In this case if we decided to use panels, we would end up having a huge number of small panel classes with their related markup file. +Another circumstance in which we may prefer to avoid the creation of custom panels is when we want to conditionally display small fragments of markup in a page. In this case if we decided to use panels, we would end up having a huge number of small panel classes with their related markup file. To better cope with situations like this, Wicket defines component _Fragment_ in package _org.apache.wicket.markup.html.panel_. Just like its parent component _WebMarkupContainer_, Fragment doesn't have its own markup file but it uses a markup fragment defined in the markup file of its parent container, which can be a page or a panel. The fragment must be delimited with tag __ and must be identified by a _wicket:id_ attribute. In addition to the component id, _Fragment_'s constructor takes as input also the id of the fragment and a reference to its container. @@ -44,7 +44,7 @@ When the page is rendered, markup inside the fragment will be inserted *inside d ---- -Fragments can be very helpful with complex pages or components. For example let's say that we have a page where users can register to our forum. This page should first display a form where user must insert his/her personal data (name, username, password, email and so on), then, once the user has submitted the form, the page should display a message like “Your registration is complete! Please check your mail to activate your user profile.”. +Fragments can be very helpful with complex pages or components. For example let's say that we have a page where users can register to our forum. This page should first display a form where user must insert his/her personal data (name, username, password, email and so on), then, once the user has submitted the form, the page should display a message like “Your registration is complete! Please check your mail to activate your user profile.”. Instead of displaying this message with a new component or in a new page, we can define two fragments: one for the initial form and one to display the confirmation message. The second fragment will replace the first one after the form has been submitted: @@ -76,4 +76,3 @@ add(fragment); Fragment fragment = new Fragment ("contentArea", "messageFrag", this); replace(fragment); ---- - diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc index 1b3a4eba375..5685934b1ea 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc @@ -1,5 +1,5 @@ -With Wicket 8 _IModel_ has been extended with new methods to fully leverage lambdas. The most interesting thing of the new version of _IModel_ is that it provides a default implementation for all of its methods (included _setObject()_), with the only exception of _getObject()_. +With Wicket 8 _IModel_ has been extended with new methods to fully leverage lambdas. The most interesting thing of the new version of _IModel_ is that it provides a default implementation for all of its methods (included _setObject()_), with the only exception of _getObject()_. In this way _IModel_ is eligible as functional interface and this greatly simplify the creation of custom models. As long as we need to display a static text it doesn't make much sense building a custom model, but if we need to display a dynamic value (like the input provided by a user or a value read from a database), defining a model with a lambda expression comes quite in handy. Let's say we need a label to display the current time stamp each time a page is rendered. This could be a possible solution: @@ -10,7 +10,7 @@ add(new Label("timeStamp", () -> java.time.LocalDate.now())); ---- As mentioned above, method _setObject()_ comes with a default implementation. The code is the following: - + [source,java] ---- default void setObject(final T object) @@ -30,20 +30,20 @@ Most of the default methods we find in _IModel_ are meant to leverage Lambda exp [source,java] ---- -//the filtered model will have a null model object if person's name +//the filtered model will have a null model object if person's name //is not "Jane" IModel janeModel = Model.of(person) .filter((p) -> p.getName().equals("Jane")); ---- -* *map(mapperFunction)*: Returns a _IModel_ applying the given mapper to the contained object, if it is not null. Example: +* *map(mapperFunction)*: Returns an _IModel_ applying the given mapper to the contained object, if it is not null. Example: [source,java] ---- //the new read-only model will contain the person's first name IModel personNameModel = Model.of(person).map(Person::getName); ---- -* *flatMap(mapperFunction)*: Returns a _IModel_ applying the given _IModel_-bearing mapper to the contained object, if it is not null. Example: +* *flatMap(mapperFunction)*: Returns an _IModel_ applying the given _IModel_-bearing mapper to the contained object, if it is not null. Example: [source,java] ---- //returns a read/write model for person's first name @@ -53,7 +53,7 @@ LambdaModel.of( () -> targetPerson::getName, targetPerson::setName )); ---- - * *flatMap(otherModel, combiner)*: Returns a _IModel_ applying the given combining function to the current model object and to the one from the other model, if they are not null. Example: + * *combineWith(otherModel, combiner)*: Returns an _IModel_ applying the given combining function to the current model object and to the one from the other model, if they are not null. Example: [source,java] ---- IModel hello = Model.of("hello"); @@ -69,4 +69,3 @@ assertEquals("hello world", combinedModel.getObject()); IModel nullObj = new Model(); assertEquals("hello!", nullObj.orElseGet(() -> "hello!"); ---- - diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc index 5490d61cd07..3e3db2b3aa0 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc @@ -5,17 +5,17 @@ One of the main goals of Wicket is to use JavaBeans and POJO as data model, over [source,java] ---- -public class Person implements Serializable { - +public class Person implements Serializable { + private String name; private String surname; private String address; private String email; private String passportCode; - + private Person spouse; private List children; - + public Person(String name, String surname) { this.name = name; this.surname = surname; @@ -23,9 +23,9 @@ public class Person implements Serializable { public String getFullName(){ return name + " " + surname; - } + } - /* + /* * Getters and setters for private fields */ } @@ -37,9 +37,9 @@ Let's say we want to display the name field of a Person instance with a label. W [source,java] ---- -Person person = new Person(); +Person person = new Person(); //load person's data... - + Label label = new Label("name", new Model(person.getName())); ---- @@ -47,9 +47,9 @@ However this solution has a huge drawback: the text displayed by the label will [source,java] ---- -Person person = new Person(); +Person person = new Person(); //load person's data... - + Label label = new Label("name", new PropertyModel(person, "name")); ---- @@ -71,7 +71,7 @@ If property is an array or a List, we can specify an index after its name. For e Label label = new Label("firstChildName", new PropertyModel(person, "children.0.name")); ---- -Indexes and map keys can be also specified using squared brackets: +Indexes and map keys can be also specified using squared brackets: [source,java] ---- @@ -81,7 +81,7 @@ mapField[key].subfield ... === LambdaModel -_PropertyModel_ uses textual expressions to resolve object properties. That's nice but it comes with some drawbacks. For example the expression can not be checked at compile time and is not refactory-friendly. To overcome these problems with Wicket 8 a new kind of lambda-based model has been introduced: _org.apache.wicket.model.LambdaModel_. This model uses lambda expressions to get/set model object. Here is the signature of its constructor: +_PropertyModel_ uses textual expressions to resolve object properties. That's nice but it comes with some drawbacks. For example the expression can not be checked at compile time and is not refactoring-friendly. To overcome these problems with Wicket 8 a new kind of lambda-based model has been introduced: _org.apache.wicket.model.LambdaModel_. This model uses lambda expressions to get/set model object. Here is the signature of its constructor: [source,java] ---- @@ -116,7 +116,7 @@ For example if we use CompoundPropertyModel with the previous example (display s //set CompoundPropertyModel as model for the container of the label setDefaultModel(new CompoundPropertyModel(person)); -Label label = new Label("spouse.name"); +Label label = new Label("spouse.name"); add(label); ---- @@ -148,7 +148,6 @@ setDefaultModel(compoundModel = new CompoundPropertyModel(person)); add(new Label("xyz", compoundModel.bind("spouse.name"))); ---- -CompoundPropertyModel are particularly useful when used in combination with Wicket forms, as we will see in the next paragraph. +CompoundPropertyModel is particularly useful when used in combination with Wicket forms, as we will see in the next paragraph. NOTE: Model is referred to as static model because the result of its method getObject is fixed and it is not dynamically evaluated each time the method is called. In contrast, models like PropertyModel and CompoundProperty Model are called dynamic models. - diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc index ea54a44b12d..a463f34820d 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc @@ -26,7 +26,7 @@ Form form = new Form("form"){ add(form); ---- -Method onSubmit is called whenever a form has been submitted and it can be overridden to perform custom actions. Please note that a Wicket form can be submitted using a standard HTML submit button which is not mapped to any component (i.e. it does not have a wicket:id attribute). +Method onSubmit is called whenever a form has been submitted and it can be overridden to perform custom actions. Please note that a Wicket form can be submitted using a standard HTML submit button which is not mapped to any component (i.e. it does not have a wicket:id attribute). In the next chapter we will continue to explore Wicket forms and we will see how to submit forms using special components which implement interface _org.apache.wicket.markup.html.form.IFormSubmitter_. === Form and models @@ -51,18 +51,18 @@ The following is a possible implementation of our form: [source,java] ---- public class LoginForm extends Form { - + private TextField usernameField; private PasswordTextField passwordField; private Label loginStatus; - + public LoginForm(String id) { super(id); - + usernameField = new TextField("username", Model.of("")); - passwordField = new PasswordTextField("password", Model.of("")); + passwordField = new PasswordTextField("password", Model.of("")); loginStatus = new Label("loginStatus", Model.of("")); - + add(usernameField); add(passwordField); add(loginStatus); @@ -75,7 +75,7 @@ public class LoginForm extends Form { if(username.equals("test") && password.equals("test")) loginStatus.setDefaultModelObject("Congratulations!"); else - loginStatus.setDefaultModelObject("Wrong username or password!"); + loginStatus.setDefaultModelObject("Wrong username or password!"); } } ---- @@ -85,7 +85,7 @@ Inside form's constructor we build the three components used in the form and we [source,java] ---- usernameField = new TextField("username", Model.of("")); -passwordField = new PasswordTextField("password", Model.of("")); +passwordField = new PasswordTextField("password", Model.of("")); loginStatus = new Label("loginStatus", Model.of("")); ---- @@ -93,10 +93,10 @@ If we don't provide a model to a form component, we will get the following excep [source,java] ---- -java.lang.IllegalStateException: Attempt to set model object on null model of component: +java.lang.IllegalStateException: Attempt to set model object on null model of component: ---- -Component TextField corresponds to the standard text field, without any particular behavior or restriction on the allowed values. We must bind this component to the tag with the attribute type set to "text" PasswordTextField is a subtype of TextFiled and it must be used with an tag with the attribute type set to "password". For security reasons component PasswordTextField cleans its value at each request, so it will be always empty after the form has been rendered. By default PasswordTextField fields are required, meaning that if we left them empty, the form won't be submitted (i.e. _onSubmit_ won't be called). Class FormComponent provides method _setRequired(boolean required)_ to change this behavior. Inside _onSubmit_, to get/set model objects we have used shortcut methods _setDefaultModelObject_ and _getDefaultModelObject_. Both methods are defined in class Component (see class diagram from Illustration 9.1). +Component TextField corresponds to the standard text field, without any particular behavior or restriction on the allowed values. We must bind this component to the tag with the attribute type set to "text" PasswordTextField is a subtype of TextFiled and it must be used with an tag with the attribute type set to "password". For security reasons component PasswordTextField cleans its value at each request, so it will be always empty after the form has been rendered. By default PasswordTextField fields are required, meaning that if we left them empty, the form won't be submitted (i.e. _onSubmit_ won't be called). Class FormComponent provides method _setRequired(boolean required)_ to change this behavior. Inside _onSubmit_, to get/set model objects we have used shortcut methods _setDefaultModelObject_ and _getDefaultModelObject_. Both methods are defined in class Component (see class diagram from illustration 9.1). The following are the possible markup and code for the login page: @@ -129,9 +129,9 @@ Java code: [source,java] ---- public class HomePage extends WebPage { - + public HomePage(final PageParameters parameters) { - + super(parameters); add(new LoginForm("loginForm")); @@ -144,25 +144,25 @@ The example shows how Wicket form components can be used to store user input ins [source,java] ---- public class LoginForm extends Form{ - + private String username; private String password; private String loginStatus; - + public LoginForm(String id) { - super(id); + super(id); setDefaultModel(new CompoundPropertyModel(this)); - + add(new TextField("username")); add(new PasswordTextField("password")); add(new Label("loginStatus")); } - public final void onSubmit() { + public final void onSubmit() { if(username.equals("test") && password.equals("test")) loginStatus = "Congratulations!"; else - loginStatus = "Wrong username or password !"; + loginStatus = "Wrong username or password !"; } } ---- @@ -189,4 +189,3 @@ add(spouseContainer); ---- The value displayed by label "name" will be "John" and not the spouse's name "Jill" as you may expect. In this example the label doesn't own a model, so it must search up its container hierarchy for an inheritable model. However, its container (WebMarkup Container with id 'spouse') doesn't own a model, hence the request for a model is forwarded to the parent container, which in this case is the page. In the end the label inherits CompoundPropertyModel from page but only its own id is used for the property expression. The containers in between are never taken into account for the final property expression. - diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc index f299e61d229..92e7316418d 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc @@ -17,7 +17,7 @@ Java code: [source,java] ---- -List fruits = Arrays.asList("apple", "strawberry", "watermelon"); +List fruits = Arrays.asList("apple", "strawberry", "watermelon"); form.add(new DropDownChoice("fruits", new Model(), fruits)); ---- @@ -44,16 +44,16 @@ In the example above the possible options are provided as a list of String objec The first option is a placeholder item corresponding to a null model value. By default DropDownChoice cannot have a null value so users are forced to select a not-null option. If we want to change this behavior we can set the nullValid flag to true via the setNullValid method. Please note that the placeholder text (“Chose one”) can be localized, as we will see in chapter 15. The other options are identified by the attribute value. By default the value of this attribute is the index of the single option inside the provided list of choices, while the text displayed to the user is obtained by calling toString()on the choice object. This default behavior works fine as long as our options are simple objects like strings, but when we move to more complex objects we may need to implement a more sophisticated algorithm to generate the value to use as the option id and the one to display to user. Wicket has solved this problem with _org.apache.wicket.markup.html.form.IChoiceRender_ interface. This interface defines method getDisplayValue(T object) that is called to generate the value to display for the given choice object, and method getIdValue(T object, int index) that is called to generate the option id. The built-in implementation of this interface is class _org.apache.wicket.markup.html.form.ChoiceRenderer_ which renders the two values using property expressions. -In the following code we want to show a list of Person objects using their full name as value to display and using their passport code as option id: +In the following code we want to show a list of Person objects using their full name as value to display and using their passport code as option id: Java code: [source,java] ---- -List persons; +List persons; //Initialize the list of persons here... ChoiceRenderer personRenderer = new ChoiceRenderer("fullName", "passportCode"); form.add(new DropDownChoice("persons", new Model(), persons, personRenderer)); ---- -The choice renderer can be assigned to the DropDownChoice using one of its constructor that accepts this type of parameter (like we did in the example above) or after its creation invoking setChoiceRenderer method. +The choice renderer can be assigned to the DropDownChoice using one of its constructors that accepts this type of parameter (like we did in the example above) or after its creation invoking setChoiceRenderer method. diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc index 262aae64c94..92985a36593 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc @@ -54,12 +54,12 @@ The initialization code for DropDownChoice is the following: [source,java] ---- Model listModel = new Model(); -ChoiceRenderer personRender = new ChoiceRenderer("fullName"); -personsList = new DropDownChoice("persons", listModel, loadPersons(), personRender); +ChoiceRenderer personRenderer = new ChoiceRenderer("fullName"); +personsList = new DropDownChoice("persons", listModel, loadPersons(), personRenderer); personsList.add(new FormComponentUpdatingBehavior()); ---- -As choice render we have used the basic implementation provided with the org.apache.wicket .markup.html.form.ChoiceRenderer class that we have seen in the previous paragraph. loadPersons() is just an utility method which generates a list of Person instances. The model for DropDownChoice is a simple instance of the Model class. +As choice renderer we have used the basic implementation provided with the org.apache.wicket .markup.html.form.ChoiceRenderer class that we have seen in the previous paragraph. loadPersons() is just an utility method which generates a list of Person instances. The model for DropDownChoice is a simple instance of the Model class. Here is the whole code of the page (except for the loadPersons() method): @@ -68,17 +68,17 @@ Here is the whole code of the page (except for the loadPersons() method): public class PersonListDetails extends WebPage { private Form form; private DropDownChoice personsList; - + public PersonListDetails(){ Model listModel = new Model(); ChoiceRenderer personRender = new ChoiceRenderer("fullName"); - + personsList = new DropDownChoice("persons", listModel, loadPersons(), personRender); personsList.add(new FormComponentUpdatingBehavior()); add(personsList); - form = new Form<>("form", new CompoundPropertyModel(listModel)); + form = new Form<>("form", new CompoundPropertyModel(listModel)); form.add(new TextField("name")); form.add(new TextField("surname")); form.add(new TextField("address")); diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc index 8579205bdcf..9d592d8a4b0 100644 --- a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc +++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc @@ -6,7 +6,7 @@ Like many people new to Wicket, you may need a little time to fully understand t [source,java] ---- /** - * + * * NOT TO DO: passing raw objects to components instead of using models! * */ @@ -21,4 +21,4 @@ public class CustomComponent extends Component{ } ---- -That's a bad practice and you must avoid it. By using models we do not only decouple our components from the data source, but we can also relay on them (if they are dynamic) to work with the most up-to-date version of our model object. If we decide to bypass models we lose all these advantages and we force model objects to be serialized. +That's a bad practice and you must avoid it. By using models we do not only decouple our components from the data source, but we can also rely on them (if they are dynamic) to work with the most up-to-date version of our model object. If we decide to bypass models we lose all these advantages and we force model objects to be serialized. diff --git a/wicket-user-guide/src/main/asciidoc/redirects.adoc b/wicket-user-guide/src/main/asciidoc/redirects.adoc index 975afb3aea1..c48c47bd0f9 100644 --- a/wicket-user-guide/src/main/asciidoc/redirects.adoc +++ b/wicket-user-guide/src/main/asciidoc/redirects.adoc @@ -13,7 +13,7 @@ Wicket will create an according BufferedHttpServletResponse instance that will b image::../img/lost-in-redirection-mockup2.png[] -After the buffered response is cached the HTTP status code of 302 get’s provided back to the browser resulting in an additional GET request to the redirect URL (which Wicket sets to the URL of the Form itself). There is a special handling code for this case in the WicketFilter instance that then looks up a Map of buffered responses within the WebApplication accordingly. If an appropriate already cached response for the current request is found, it get’s streamed back to the browser immediately. No additional form processing happens now. The following is a code snippet taken from WicketFilter: +After the buffered response is cached the HTTP status code of 302 gets provided back to the browser resulting in an additional GET request to the redirect URL (which Wicket sets to the URL of the Form itself). There is a special handling code for this case in the WicketFilter instance that then looks up a Map of buffered responses within the WebApplication accordingly. If an appropriate already cached response for the current request is found, it gets streamed back to the browser immediately. No additional form processing happens now. The following is a code snippet taken from WicketFilter: [source,java] ---- @@ -75,5 +75,3 @@ You could of course turn on the session stickiness between your load balancer (a image::../img/lost-in-redirection-mockup4.png[] Session replication would still provide you with failover in case one of the tomcat server dies for whatever reason and sticky sessions would ensure that the Lost In Redirection problem does not occur any more. - - diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc index 24ec9e00f45..23574268240 100644 --- a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_2.adoc @@ -1,6 +1,6 @@ -The _Request_ and _Response_ classes are located in package _org.apache.wicket.request_ and they provide an abstraction of the concrete request and response used by our web application. +The _Request_ and _Response_ classes are located in package _org.apache.wicket.request_ and they provide an abstraction of the concrete request and response used by our web application. -Both classes are declared as abstract but if our application class inherits from _WebApplication_ it will use their sub classes _ServletWebRequest_ and _ServletWebResponse_, both of them located inside the package _org.apache.wicket.protocol.http.servlet.ServletWebRequest_ and _ServletWebResponse_ wrap respectively a _HttpServletRequest_ and a _HttpServletResponse_ object. If we need to access to these low-level objects we can call _Request_'s method _getContainerRequest()_ and _Response_'s method _getContainerResponse()_. +Both classes are declared as abstract but if our application class inherits from _WebApplication_ it will use their sub classes _ServletWebRequest_ and _ServletWebResponse_, both of them located inside the package _org.apache.wicket.protocol.http.servlet.ServletWebRequest_ and _ServletWebResponse_ wrap respectively a _HttpServletRequest_ and a _HttpServletResponse_ object. If we need to access these low-level objects, we can call _Request_'s method _getContainerRequest()_ and _Response_'s method _getContainerResponse()_. diff --git a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc index c26c31204e4..49ce6869670 100644 --- a/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/requestProcessing/requestProcessing_4.adoc @@ -36,7 +36,7 @@ The Session class handles session attributes in much the same way as the standar By default class WebSession will use the underlying HTTP session to store attributes. Wicket will automatically add a prefix to the name of the attributes. This prefix is returned by the WebApplication's method getSessionAttributePrefix(). -=== Accessing to the HTTP session +=== Accessing the HTTP session If for any reason we need to directly access to the underlying _HttpSession_ object, we can retrieve it from the current request with the following code: diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc index a497e8405f7..1b14cd4445e 100644 --- a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_1.adoc @@ -4,7 +4,7 @@ Wicket pages can be divided into two categories: stateful and stateless pages. Stateful pages are those which rely on user session to store their internal state and to keep track of user interaction. On the contrary stateless pages are those which don't change their internal state during their lifecycle and they don't need to occupy space into user session. -From Wicket's point of view the biggest difference between these two types of page is that stateful pages are versioned, meaning that they will be saved into user session every time their internal state has changed. Wicket automatically assigns a session to the user the first time a stateful page is requested. Page versions are stored into user session using Java Serialization mechanism. +From Wicket's point of view the biggest difference between these two page types is that stateful pages are versioned, meaning that they will be saved into user session every time their internal state has changed. Wicket automatically assigns a session to the user the first time a stateful page is requested. Page versions are stored into user session using Java Serialization mechanism. Stateless pages are never versioned and that's why they don't require a valid user session. If we want to know whether a page is stateless or not, we can call the _isPageStateless()_ method of class _Page_. In order to build a stateless page we must comply with some rules to ensure that the page won't need to use user session. These rules are illustrated in paragraph 8.3 but before talking about stateless pages we must first understand how stateful pages are handled and why they are versioned. diff --git a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc index 4842b4958e5..16d5fd17232 100644 --- a/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc +++ b/wicket-user-guide/src/main/asciidoc/versioningCaching/versioningCaching_2.adoc @@ -89,7 +89,7 @@ A serializer based on Kryo library and another one based on Fast are provided by === Page caching -By default Wicket persists versions of pages into a session-relative file on disk, but it uses a two-levels cache to speed up this process. The first level of the cache uses a http session attribute called “wicket:persistentPageManagerData-” to store pages. The second level cache stores pages into application-scoped variables which are identified by a session id and a page id. +By default Wicket persists versions of pages into a session-relative file on disk, but it uses a two-level cache to speed up this process. The first level of the cache uses a http session attribute called “wicket:persistentPageManagerData-” to store pages. The second level cache stores pages into application-scoped variables which are identified by a session id and a page id. The following picture is an overview of these two caching levels: diff --git a/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc index d46846a4a56..a44dcd97bf6 100644 --- a/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc +++ b/wicket-user-guide/src/main/asciidoc/whyLearn/whyLearn_4.adoc @@ -3,7 +3,7 @@ Wicket is not the only component oriented framework available in the Java ecosys * *Wicket is 100% open source*: Wicket is a top Apache project and it doesn't depend on any private company. You don't have to worry about future licensing changes, Wicket will always be released under Apache license 2.0 and freely available. -* *Wicket is a community driven project*: The Wicket team supports and promotes the dialogue with the framework's users through two mailing lists http://wicket.apache.org/help/email.html[(one for users and another one for framework developers)] and an https://issues.apache.org/jira/browse/WICKET[Apache JIRA] (the issue tracking system). Moreover, as any other Apache project, Wicket is developed paying great attention to user feedbacks and to suggested features. +* *Wicket is a community driven project*: The Wicket team supports and promotes the dialogue with the framework's users through two mailing lists http://wicket.apache.org/help/email.html[(one for users and another one for framework developers)] and an https://issues.apache.org/jira/browse/WICKET[Apache JIRA] (the issue tracking system). Moreover, as any other Apache project, Wicket is developed paying great attention to user feedback and to suggested features. * *Wicket is just about Java and good old HTML*: almost all web frameworks force users to adopt special tags or to use server side code inside HTML markup. This is clearly in contrast with the concept of separation between presentation and business logic and it leads to a more confusing code in our pages. In Wicket we don't have to take care of generating HTML inside the page itself, and we won't need to use any tag other than standard HTML tags. All we have to do is to attach our components (Java instances) to the HTML tags using a simple tag attribute called _wicket:id_ (we will shortly see how to use it).