You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by ad...@apache.org on 2017/08/12 15:12:06 UTC
wicket git commit: WICKET-6438 8.x reference guide needs a few minor
improvements
Repository: wicket
Updated Branches:
refs/heads/master 2cb93c323 -> 075d8371e
WICKET-6438 8.x reference guide needs a few minor improvements
Project: http://git-wip-us.apache.org/repos/asf/wicket/repo
Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/075d8371
Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/075d8371
Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/075d8371
Branch: refs/heads/master
Commit: 075d8371ef3eb2e5f3bdadf008ae904cafd222b3
Parents: 2cb93c3
Author: ozeray <ah...@yahoo.com>
Authored: Sun Aug 6 03:12:03 2017 +0300
Committer: Andrea Del Bene <ad...@apache.org>
Committed: Sat Aug 12 17:13:05 2017 +0200
----------------------------------------------------------------------
.../src/main/asciidoc/contributing.adoc | 16 ++++++-----
.../src/main/asciidoc/helloWorld.adoc | 1 -
.../main/asciidoc/helloWorld/helloWorld_2.adoc | 2 +-
.../main/asciidoc/helloWorld/helloWorld_3.adoc | 2 +-
.../src/main/asciidoc/img/comsysto-logo.png | Bin 9926 -> 12166 bytes
.../main/asciidoc/img/page-panel-hierarchy.png | Bin 161128 -> 75309 bytes
.../src/main/asciidoc/introduction.adoc | 6 ++--
.../asciidoc/keepControl/keepControl_1.adoc | 2 +-
.../asciidoc/keepControl/keepControl_2.adoc | 4 +--
.../asciidoc/keepControl/keepControl_4.adoc | 10 ++++---
.../asciidoc/keepControl/keepControl_5.adoc | 23 ++++++++++++---
.../src/main/asciidoc/layout/layout_2.adoc | 4 +--
.../src/main/asciidoc/layout/layout_4.adoc | 20 ++++++-------
.../asciidoc/wicketstuff/wicketstuff_1.adoc | 28 +++++++++++++++++--
14 files changed, 79 insertions(+), 39 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/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
index fab207f..e338e23 100644
--- a/wicket-user-guide/src/main/asciidoc/contributing.adoc
+++ b/wicket-user-guide/src/main/asciidoc/contributing.adoc
@@ -3,23 +3,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]
+* 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]
----
-git clone https://github.com/apache/wicket.git
+git clone https://github.com/<<your github username>>/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)
+* 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)
-* Navigate to _wicket/wicket-user-guide/target/guide/8.x_ and open one of the following files in a browser / pdf viewer:
-** _guide/single.html_ (single page version)
-** _guide/single.pdf_ (single page pdf version)
+* Navigate to _wicket/wicket-user-guide/target/generated-docs_ and open one of the following files in a browser / pdf viewer:
+** _single.html_ (single page version)
+** _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 Apache Wicket's GIT repository and *create a pull request* on github
+* *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!*
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/helloWorld.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/helloWorld.adoc b/wicket-user-guide/src/main/asciidoc/helloWorld.adoc
index b50e96c..52bec1b 100644
--- a/wicket-user-guide/src/main/asciidoc/helloWorld.adoc
+++ b/wicket-user-guide/src/main/asciidoc/helloWorld.adoc
@@ -4,7 +4,6 @@ Both frameworks share the same component-based architecture: in AWT we have a _W
image::../img/uml-component.png[]
-["plantuml", "uml-component", "svg"]
....
@startuml
package java.awt {
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_2.adoc b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_2.adoc
index f2b3c52..356f536 100644
--- a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_2.adoc
@@ -9,7 +9,7 @@ A Wicket application is a standard Java EE web application, hence it is deployed
image::../img/webinf.png[]
-_Illustration : The standard directory structure of a Wicket application_
+_Illustration: The standard directory structure of a Wicket application_
The content of web.xml declares a servlet filter (class _org.apache.wicket.Protocol.http.WicketFilter_) which dispatches web requests to our Wicket application:
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
index dc4275c..19f353d 100644
--- a/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
+++ b/wicket-user-guide/src/main/asciidoc/helloWorld/helloWorld_3.adoc
@@ -8,7 +8,7 @@ By default this HTML file must have the same name of the related page class and
image::../img/samepackage.png[]
-_Illustration :Page class and its related HTML file_
+_Illustration: Page class and its related HTML file_
If you don't like to put class and html side by side (let's say you want all your HTML files in a separated folder) you can use Wicket settings to specify where HTML files can be found. We will cover this topic later in <<resources.adoc#_customizing_resource_loading,chapter 16.14>>.
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/img/comsysto-logo.png
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/img/comsysto-logo.png b/wicket-user-guide/src/main/asciidoc/img/comsysto-logo.png
index a0997b3..a06efd4 100644
Binary files a/wicket-user-guide/src/main/asciidoc/img/comsysto-logo.png and b/wicket-user-guide/src/main/asciidoc/img/comsysto-logo.png differ
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/img/page-panel-hierarchy.png
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/img/page-panel-hierarchy.png b/wicket-user-guide/src/main/asciidoc/img/page-panel-hierarchy.png
index f46f295..66cd0fd 100644
Binary files a/wicket-user-guide/src/main/asciidoc/img/page-panel-hierarchy.png and b/wicket-user-guide/src/main/asciidoc/img/page-panel-hierarchy.png differ
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/introduction.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/introduction.adoc b/wicket-user-guide/src/main/asciidoc/introduction.adoc
index cd45f32..8a5b29e 100644
--- a/wicket-user-guide/src/main/asciidoc/introduction.adoc
+++ b/wicket-user-guide/src/main/asciidoc/introduction.adoc
@@ -14,8 +14,7 @@ For those who need further documentation on Wicket, there are http://wicket.apa
Hope you'll find this guide helpful. Have fun with Wicket!
-Editors:
-
+Editors: +
*Andrea Del Bene, adelbene@apache.org* +
*Martin Grigorov* +
*Tobias Soloschenko* +
@@ -27,8 +26,7 @@ Editors:
*Joachim Rohde*
-*PS*: this guide is based on Wicket 6. However if you are using an older version you should find this guide useful as well, but it's likely that the code and the snippets won't work with your version.
-
+*PS*: this guide is based on Wicket 8. However if you are using an older version you should find this guide useful as well, but it's likely that the code and the snippets won't work with your version. +
*PPS*: although I've tried to do my best working on this tutorial, this document is a work in progress and may contain errors and/or omissions. That's why any feedback of any kind is REALLY appreciated!
Project started by
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_1.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_1.adoc
index 39e2e48..c5579f1 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_1.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_1.adoc
@@ -5,4 +5,4 @@ Class _Component_ provides two getter methods to determinate if a component is v
Even if nothing prevents us from overriding these two methods to implement a custom logic to determinate the state of a component, we should keep in mind that methods _isVisible_ and _isEnabled_ are called multiple times before a component is fully rendered. Hence, if we place non-trivial code inside these two methods, we can sensibly deteriorate the responsiveness of our pages.
-As we will see in the next chapter, class _Component_ provides method _onConfigure_ which is more suited to contain code that contributes to determinate component states because it is called just once during rendering phase.
+As we will see in the next chapter, class _Component_ provides method _onConfigure_ which is more suited to contain code that contributes to determinate component states because it is called just once during rendering phase of a request.
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_2.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_2.adoc
index 975614d..0707fa3 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_2.adoc
@@ -1,5 +1,5 @@
-To modify tag attributes we can use class _org.apache.wicket.AttributeModifier_. This class extends _org.apache.wicket.behavior.Behavior_ and can be added to any component via the _Component_'s _add_ method. Class _Behavior_ is used to expand component functionalities and it can also modify component markup. We will see this class in detail later in <<advanced.adoc#_enriching_components_with_behaviors,chapter 19.1>>.
+To modify tag attributes in a component's HTML markup we can use class _org.apache.wicket.AttributeModifier_. This class extends _org.apache.wicket.behavior.Behavior_ and can be added to any component via the _Component_'s _add_ method. Class _Behavior_ is used to expand component functionalities and it can also modify component markup. We will see this class in detail later in <<advanced.adoc#_enriching_components_with_behaviors,chapter 19.1>>.
As first example of attribute manipulation let's consider a _Label_ component bound to the following markup:
@@ -8,7 +8,7 @@ As first example of attribute manipulation let's consider a _Label_ component bo
<span wicket:id="simpleLabel"></span>
----
-Suppose we want to add some style to label content making it red and bolded. We can add to the label an _AttributeModifier_ which creates the tag attribute _style_ with value _ :[color:red;font-weight:bold]
+Suppose we want to add some style to label content making it red and bolded. We can add to the label an _AttributeModifier_ which creates the tag attribute _style_ with value _color:red;font-weight:bold_:
[source,java]
----
label.add(new AttributeModifier("style", "color:red;font-weight:bold"));
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
index 422c68c..12ec5ec 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_4.adoc
@@ -1,15 +1,15 @@
-Create custom panels is a great way to handle complex user interfaces. However, sometimes we may need to create a panel which is used only by a specific page and only for a specific task.
+Creating custom panels is a great way to handle complex user interfaces. However, sometimes we may need to create a panel which is used only by a specific page and only for a specific task.
-In situations like these component _org.apache.wicket.markup.html.WebMarkupContainer_ is better suited than custom panels because it can be directly attached to a tag in the parent markup without needing a corresponding html file (hence it is less reusable). Let's consider for example the main page of a mail service where users can see a list of received mails. Suppose that this page shows a notification box where user can see if new messages have arrived. This box must be hidden if there are no messages to display and it would be nice if we could handle it as if it was a Wicket component.
+In situations like these _org.apache.wicket.markup.html.WebMarkupContainer_ component is better suited than custom panels because it can be directly attached to a tag in the parent markup without needing a corresponding html file (hence it is less reusable). Let's consider for example the main page of a mail service where users can see a list of received mails. Suppose that this page shows a notification box where user can see if new messages have arrived. This box must be hidden if there are no messages to display and it would be nice if we could handle it as if it was a Wicket component.
Suppose also that this information box is a _<div>_ tag like this inside the page:
[source,html]
----
<div wicket:id="informationBox">
- //here's the body
- You've got <span wicket:id="messagesNumber"></span> new messages.
+ //here's the body
+ You've got <span wicket:id="messagesNumber"></span> new messages.
</div>
----
@@ -27,3 +27,5 @@ informationBox.setVisible(false);
----
As you can see in the snippet above we can handle our information box from Java code as we do with any other Wicket component.
+
+Note also that we may later choose to make information box visible by calling _setVisible(true)_, upon for example an AJAX request (we will be covering such an example in <<_working_with_hidden_components, chapter 19.2.8>>).
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc
----------------------------------------------------------------------
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 dd78fc9..e44f3f1 100644
--- a/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc
+++ b/wicket-user-guide/src/main/asciidoc/keepControl/keepControl_5.adoc
@@ -13,10 +13,10 @@ In the following example we have defined a fragment in a page and we used it as
...
<body>
...
- <div wicket:id="contentArea"></div>
- <wicket:fragment wicket:id="fragmentId">
- <!-- Fragment markup goes here -->
- </wicket:fragment>
+ <div wicket:id="contentArea"></div>
+ <wicket:fragment wicket:id="fragmentId">
+ <p>News available</p>
+ </wicket:fragment>
</body>
</html>
----
@@ -29,6 +29,21 @@ Fragment fragment = new Fragment ("contentArea", "fragmentId", this);
add(fragment);
----
+When the page is rendered, markup inside the fragment will be inserted *inside div element*:
+
+[source,html]
+----
+<html>
+ ...
+<body>
+...
+ <div wicket:id="contentArea">
+ <p>News available</p>
+ </div>
+</body>
+</html>
+----
+
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:
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/layout/layout_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_2.adoc b/wicket-user-guide/src/main/asciidoc/layout/layout_2.adoc
index fba873e..ec71d00 100644
--- a/wicket-user-guide/src/main/asciidoc/layout/layout_2.adoc
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_2.adoc
@@ -26,7 +26,7 @@ Subclasses of _MarkupContainer_ can contain children components that can be adde
* add one or more children components (with method _add_).
* remove a specific child component (with method _remove_).
-* retrieve a specific child component with method _get(String)_. The string parameter is the id of the component or its relative path if the component is nested inside other _MarkupContainer_s_. This path is a colon-separated string containing also the ids of the intermediate containers traversed to get to the child component. To illustrate an example of component path, let's consider the code of the following page:
+* retrieve a specific child component with method _get(String)_. The string parameter is the id of the component or its relative path if the component is nested inside other _MarkupContainers_. This path is a colon-separated string containing also the ids of the intermediate containers traversed to get to the child component. To illustrate an example of component path, let's consider the code of the following page:
[source,java]
----
@@ -34,7 +34,7 @@ MyPanel myPanel = new MyPanel ("innerContainer");
add(myPanel);
----
-Component _MyPanel_ is a custom panel containing only a label having _ [name] as id. Under those conditions we could retrieve this label from the container page using the following path expression:
+Component _MyPanel_ is a custom panel containing only a label having *"name"* as id. Under those conditions we could retrieve this label from the container page using the following path expression:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
index 15a814f..c24efba 100644
--- a/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
@@ -9,8 +9,8 @@ An example of a parent page using the tag _<wicket:child>_ is the following:
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
- This is parent body!
- <wicket:child/>
+ This is parent body!
+ <wicket:child/>
</body>
</html>
----
@@ -25,8 +25,8 @@ The markup of a child page/panel must be placed inside the tag _<wicket:extend>_
</head>
<body>
<wicket:extend>
- This is child body!
- </wicket:extend>
+ This is child body!
+ </wicket:extend>
</body>
</html>
----
@@ -37,14 +37,14 @@ Considering the two pages seen above, the final markup generated for child page
----
<html>
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
- This is parent body!
- <wicket:child>
- <wicket:extend>
- This is child body!
- </wicket:extend>
+ This is parent body!
+ <wicket:child>
+ <wicket:extend>
+ This is child body!
+ </wicket:extend>
</wicket:child>
</body>
</html>
http://git-wip-us.apache.org/repos/asf/wicket/blob/075d8371/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc
index 6d3633d..ee97c9e 100644
--- a/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc
+++ b/wicket-user-guide/src/main/asciidoc/wicketstuff/wicketstuff_1.adoc
@@ -1,7 +1,7 @@
-WicketStuff is an umbrella project that gathers different Wicket-related projects developed and maintained by the community. The project is hosted on GitHub at https://github.com/wicketstuff/core[https://github.com/wicketstuff/core] .
+WicketStuff is an umbrella project that gathers different Wicket-related projects developed and maintained by the community. The project is hosted on GitHub at https://github.com/wicketstuff/core[https://github.com/wicketstuff/core].
Every module is structured as a parent Maven project containing the actual project that implements the new functionality and an example project that illustrates how to use it in our code. The resulting directory structure of each module is the following:
[source,java]
@@ -12,7 +12,31 @@ Every module is structured as a parent Maven project containing the actual proje
\---<module name>-examples
----
-So far we have introduced only modules Kryo Serializer and JavaEE Inject, but WicketStuff comes with many other modules that can be used in our applications. Some of them come in handy to improve the user experience of our pages with complex components or integrating some popular web services (like http://maps.google.com/[Google Maps] ) and JavaScript libraries (like http://www.tinymce.com/[TinyMCE] ).
+In order to enjoy extra components, utilities and/or functionality introduced by WicketStuff modules in our Wicket projects, we can import the respective module dependency in our *pom.xml* as shown below:
+
+[source,java]
+----
+<dependency>
+ <groupId>org.wicketstuff</groupId>
+ <artifactId>wicketstuff-<module name></artifactId>
+ <version><wicketstuff version></version>
+</dependency>
+----
+
+where _<wicketstuff version>_ is the version of WicketStuff artifact (e.g. 8.0.0-SNAPSHOT), and _<module name>_ corresponds to the name of WicketStuff module we want to use. As an illustration, to have access to Java 8 lambda style _ComponentFactory_ methods for adding _Links_ or _AjaxButtons_ to our pages, the following dependency declaration will suffice:
+
+[source,java]
+----
+<dependency>
+ <groupId>org.wicketstuff</groupId>
+ <artifactId>wicketstuff-lambda-components</artifactId>
+ <version>8.0.0-SNAPSHOT</version>
+</dependency>
+----
+
+Please refer to <<_module_wicketstuff_lambda_components,Appendix B.7>> for more details about Lambda Components.
+
+So far we have introduced only modules Kryo Serializer and JavaEE Inject, but WicketStuff comes with many other modules that can be used in our applications. Some of them come in handy to improve the user experience of our pages with complex components or integrating some popular web services (like http://maps.google.com/[Google Maps]) and JavaScript libraries (like http://www.tinymce.com/[TinyMCE]).
This appendix provides a quick overview of what WicketStuff offers to enhance the usability and the visually-appealing of our pages.