wicket-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dasho...@apache.org
Subject [07/22] wicket git commit: Moved wicket-7.x docs to asciidoctor
Date Wed, 23 Nov 2016 22:44:40 GMT
http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/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
new file mode 100644
index 0000000..c934f21
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_2.adoc
@@ -0,0 +1,67 @@
+
+The need of ensuring a consistent layout across our pages unveiled a serious limit of the HTML: the inability to apply inheritance to web pages and their markup. Wouldn't be great if we could write our layout once in a page and then inherit it in the other pages of our application? 
+One of the goals of Wicket is to overcome this kind of limit.
+
+=== Markup inheritance
+
+As we have seen in the previous chapter, Wicket pages are pure Java classes, so we can easily write a page which is a subclass of another parent page. But in Wicket inheritance is not limited to the classic object-oriented code inheritance. When a class subclasses a _WebPage_ it also inherits the HTML file of the parent class. This type of inheritance is called markup inheritance.
+To better illustrate this concept let's consider the following example where we have a page class called _GenericSitePage_ with the corresponding HTML file GenericSitePage.html. Now let's create a specific page called _OrderCheckOutPage_ where users can check out their orders on our web site. This class extends _GenericSitePage_ but we don't provide it with any corresponding HTML file.
+In this scenario _OrderCheckOutPage_ will use GenericSitePage.html as markup file:
+
+image::../img/markup-inheritance.png[]
+
+Markup inheritance comes in handy for page layout management as it helps us avoid the burden of checking that each page conforms to the site layout. However to fully take advantage of markup inheritance we must first learn how to use another important component of the framework that supports this feature: the panel.
+
+WARNING: If no markup is found (nor directly assigned to the class, neither inherited from an ancestor) a _MarkupNotFoundException_ is thrown.
+
+=== Panel class
+
+Class _org.apache.wicket.markup.html.panel.Panel_ is a special component which lets us reuse GUI code and HTML markup across different pages and different web applications. It shares a common ancestor class with WebPage class, which is _org.apache.wicket.MarkupContainer_:
+
+image::../img/page-panel-hierarchy.png[]
+
+_Illustration: Hierarchy of WebPage and Panel classes_
+
+Subclasses of _MarkupContainer_ can contain children components that can be added with method _add(Component...)_ (seen in <<whyLearn.adoc#_benefits_of_component_oriented_frameworks_for_web_development,chapter 3.3>>). _MarkupContainer_ implements a full set of methods to manage children components. The basic operations we can do on them are:
+
+* 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:
+
+[source,java]
+----
+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:
+
+[source,java]
+----
+Label name = (Label)get("innerContainer:name");
+----
+
+* replace a specific child component with a new component having the same id (with method _replace_).
+* iterate thought children components with the iterator returned by method _iterator_ or using visitor pattern1 with methods _visitChildren_.
+
+Both _Panel_ and _WebPage_ have their own associated markup file which is used to render the corresponding component. If such file is not provided, Wicket will apply markup inheritance looking for a markup file through their ancestor classes. When a panel is attached to a container, the content of its markup file is inserted into its related tag.
+
+While panels and pages have much in common, there are some notable differences between these two components that we should keep in mind. The main difference between them is that pages can be rendered as standalone entities while panels must be placed inside a page to be rendered. Another important difference is the content of their markup file: for both _WebPage_ and _Panel_ this is a standard HTML file, but _Panel_ uses a special tag to indicate which part of the whole file will be considered as markup source. This tag is _<wicket:panel>_. A markup file for a panel will typically look like this:
+
+[source,html]
+----
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+...
+</head>
+<body>
+   <wicket:panel>
+      <!-- Your markup goes here -->
+       </wicket:panel>
+</body>
+</html>
+----
+
+The HTML outside tag _<wicket:panel>_ will be removed during rendering phase. The space outside this tag can be used by both web developers and web designers to place some mock HTML to show how the final panel should look like.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc b/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc
new file mode 100644
index 0000000..291ba62
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_3.adoc
@@ -0,0 +1,172 @@
+
+Let's go back to our layout example. In <<layout.adoc#_header_footer_left_menu_content_etc,chapter 5.1>> we have divided our layout in common areas that must be part of every page. Now we will build a reusable template page for our web application combining pages and panels. The code examples are from project MarkupInheritanceExample.
+
+=== Panels and layout areas
+
+First, let's build a custom panel for each layout area (except for 'content' area). For example given the  header area
+
+image::../img/header-area.png[]
+
+we can build a panel called _HeaderPanel_ with a related markup file called HeaderPanel.html containing the HTML for this area:
+
+[source,html]
+----
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+...
+</head>
+<body>
+   <wicket:panel>
+      <table width="100%" style="border: 0px none;">
+      <tbody>
+    <tr>
+    <td>
+       <img alt="Jug4Tenda" src="wicketLayout_files/logo_jug4tenda.gif">
+     </td>
+      <td>
+    <h1>Gestione Anagrafica</h1>
+   </td>   
+      </tr>
+      </tbody>
+      </table>   
+   </wicket:panel>
+</body>
+<html>
+----
+
+The class for this panel simply extends base class _Panel_:
+
+[source,java]
+----
+package helloWorld.layoutTenda;
+
+import org.apache.wicket.markup.html.panel.Panel;
+
+public class HeaderPanel extends Panel {
+
+	public HeaderPanel(String id) {
+		super(id);		
+	}
+}
+----
+
+For each layout area we will build a panel like the one above that holds the appropriate HTML markup. In the end we will have the following set of panels:
+
+* HeaderPanel 
+* FooterPanel
+* MenuPanel
+
+Content area will change from page to page, so we don't need a reusable panel for it.
+
+=== Template page
+
+Now we can build a generic template page using our brand new panels. Its markup is quite straightforward :
+
+[source,html]
+----
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+...
+<!--Include CSS-->
+...
+</head>
+<body>
+<div id="header" wicket:id="headerPanel">header</div>
+<div id="body">
+	<div id="menu" wicket:id="menuPanel">menu</div>
+	<div id="content" wicket:id="contentComponent">content</div>
+</div>
+<div id="footer" wicket:id="footerPanel">footer</div>
+</body>
+</html>
+----
+
+The HTML code for this page implements the generic left-menu layout of our site. You can note the 4 _<div>_ tags used as containers for the corresponding areas.
+The page class contains the code to physically assemble the page and panels:
+
+[source,java]
+----
+package helloWorld.layoutTenda;
+
+import org.apache.wicket.markup.html.WebPage;
+import org.apache.wicket.Component;
+import org.apache.wicket.markup.html.basic.Label;
+
+public class JugTemplate extends WebPage {
+	public static final String CONTENT_ID = "contentComponent";
+
+	private Component headerPanel;
+	private Component menuPanel;
+	private Component footerPanel;
+ 
+              public JugTemplate(){
+		add(headerPanel = new HeaderPanel("headerPanel"));
+		add(menuPanel = new MenuPanel("menuPanel"));
+		add(footerPanel = new FooterPanel("footerPanel"));
+		add(new Label(CONTENT_ID, "Put your content here"));
+	}
+              
+             //getters for layout areas
+       //... 
+}
+----
+
+Done! Our template page is ready to be used. Now all the pages of our site will be subclasses of this parent page and they will inherit the layout and the HTML markup. They will only substitute the _Label_ inserted as content area with their custom content.
+
+=== Final example
+
+As final example we will build the login page for our site. We will call it _SimpleLoginPage_. First, we need a panel containing the login form. This will be the content area of our page. We will call it _LoginPanel_ and the markup is the following:
+
+[source,html]
+----
+<html>
+<head>
+</head>
+<body>
+   <wicket:panel>
+    <div style="margin: auto; width: 40%;">
+       <form  id="loginForm" method="get">
+         <fieldset id="login" class="center">
+            <legend >Login</legend>               
+            <span >Username: </span><input type="text" id="username"/><br/>                                                                  
+            <span >Password: </span><input type="password" id="password" />
+            <p>
+               <input type="submit" name="login" value="login"/>
+            </p>
+         </fieldset>
+      </form>
+    </div>   
+   </wicket:panel>
+</body>
+</html>
+----
+
+The class for this panel just extends _Panel_ class so we won't see the relative code. The form of this panel is for illustrative purpose only. We will see how to work with Wicket forms in chapters 
+<<_wicket_models_and_forms,11>> and 
+<<_wicket_forms_in_detail,12>>. Since this is a login page we don't want it to display the left menu area. That's not a big deal as _Component_ class exposes a method called _setVisible_ which sets whether the component and its children should be displayed. 
+
+The resulting Java code for the login page is the following:
+
+[source,java]
+----
+package helloWorld.layoutTenda;
+import helloWorld.LoginPanel;
+import org.apache.wicket.event.Broadcast;
+import org.apache.wicket.event.IEventSink;
+
+public class SimpleLoginPage extends JugTemplate {
+	public SimpleLoginPage(){
+		super();		
+		replace(new LoginPanel(CONTENT_ID));
+		getMenuPanel().setVisible(false);
+	}
+}
+----
+
+Obviously this page doesn't come with a related markup file. You can see the final page in the following picture:
+
+image::../img/final-login-page.png[]
+
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/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
new file mode 100644
index 0000000..15a814f
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_4.adoc
@@ -0,0 +1,100 @@
+
+With Wicket we can apply markup inheritance using another approach based on the tag _<wicket:child>_. This tag is used inside the parent's markup to define where the children pages/panels can “inject” their custom markup extending the markup inherited from the parent component. 
+An example of a parent page using the tag _<wicket:child>_ is the following:
+
+[source,html]
+----
+<html>
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+</head>
+<body>
+	This is parent body!
+	<wicket:child/>
+</body>
+</html>
+----
+
+The markup of a child page/panel must be placed inside the tag _<wicket:extend>_. Only the markup inside _<wicket:extend>_ will be included in final markup. Here is an example of child page markup:
+
+[source,java]
+----
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+</head>
+<body>
+    <wicket:extend>
+          This is child body!
+	</wicket:extend>
+</body>
+</html>
+----
+
+Considering the two pages seen above, the final markup generated for child page will be the following:
+
+[source,html]
+----
+<html>
+<head>
+	<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>
+    </wicket:child>
+</body>
+</html>
+----
+
+=== Our example revisited
+
+Applying _<wicket:child>_ tag to our layout example, we obtain the following markup for the main template page:
+
+[source,html]
+----
+<html>
+<head>
+	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+</head>
+<body>
+<div id="header" wicket:id="headerPanel">header</div>
+<div id="body">
+	<div id="menu" wicket:id="menuPanel">menu</div>
+	<wicket:child/>
+</div>
+<div id="footer" wicket:id="footerPanel">footer</div>
+</body>
+</html>
+----
+
+We have replaced the _<div>_ tag of the content area with the tag _<wicket:child>_. Going forward with our example we can build a login page creating class _SimpleLoginPage_ which extends the _JugTemplate_ page, but with a related markup file like this:
+
+[source,html]
+----
+<html>
+<head>
+</head>
+<body>
+   <wicket:extend>
+    <div style="margin: auto; width: 40%;">
+       <form  id="loginForm" method="get">
+         <fieldset id="login" class="center">
+            <legend >Login</legend>               
+            <span >Username: </span><input type="text" id="username"/><br/>                                                                  
+            <span >Password: </span><input type="password" id="password" />
+            <p>
+               <input type="submit" name="login" value="login"/>
+            </p>
+         </fieldset>
+      </form>
+    </div>   
+   </wicket:extend>
+</body>
+</html>
+----
+
+As we can see this approach doesn't require to create custom panels to use as content area and it can be useful if we don't have to handle a GUI with a high degree of complexity.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/layout/layout_5.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/layout/layout_5.adoc b/wicket-user-guide/src/main/asciidoc/layout/layout_5.adoc
new file mode 100644
index 0000000..225929b
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/layout/layout_5.adoc
@@ -0,0 +1,3 @@
+
+
+Wicket applies inheritance also to HTML markup making layout management much easier and less error-prone. Defining a master template page to use as base class for the other pages is a great way to build a consistent layout and use it across all the pages on the web site. During the chapter we have also introduced the _Panel_ component, a very important Wicket class that is primarily designed to let us divide our pages in smaller and reusable UI components.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/maven.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/maven.adoc b/wicket-user-guide/src/main/asciidoc/maven.adoc
new file mode 100644
index 0000000..b28b04f
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/maven.adoc
@@ -0,0 +1,3 @@
+
+
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/maven/maven_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/maven/maven_1.adoc b/wicket-user-guide/src/main/asciidoc/maven/maven_1.adoc
new file mode 100644
index 0000000..0342163
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/maven/maven_1.adoc
@@ -0,0 +1,59 @@
+
+
+
+As pointed out in the note in <<helloWorld.adoc#_configuration_of_wicket_applications,paragraph 4.2>>, Wicket can be started in two modes, DEVELOPMENT and DEPLOYMENT. When we are in DEVELOPMENT mode Wicket warns us at application startup with the following message:
+
+[source,java]
+----
+********************************************************************
+*** WARNING: Wicket is running in DEVELOPMENT mode.              ***
+***                               ^^^^^^^^^^^                    ***
+*** Do NOT deploy to your live server(s) without changing this.  ***
+*** See Application#getConfigurationType() for more information. ***
+********************************************************************
+----
+
+As we can read Wicket itself discourages us from using DEVELOPMENT mode into production environment. The running mode of our application can be configured in four different ways. The first one is adding a filter parameter inside deployment descriptor web.xml:
+
+[source,html]
+----
+<filter>      
+	<filter-name>wicket.MyApp</filter-name>
+	<filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
+	<init-param>
+		<param-name>applicationClassName</param-name>
+		<param-value>org.wicketTutorial.WicketApplication</param-value>
+	</init-param>
+	<init-param>
+            <param-name>configuration</param-name>
+            <param-value>deployment</param-value>
+	</init-param>
+</filter>
+----
+
+The additional parameter is written in bold. The same parameter can be also expressed as context parameter:
+
+[source,html]
+----
+<context-param>
+    <param-name>configuration</param-name>
+    <param-value>deployment</param-value>
+</context-param>
+----
+
+The third way to set the running mode is using system property wicket.configuration. This parameter can be specified in the command line that starts up the server:
+
+[source,java]
+----
+java -Dwicket.configuration=deployment ...
+----
+
+The last option is to set it in your Java code (e.g. in the init-method of your WebApplication):
+
+[source,java]
+----
+setConfigurationType(RuntimeConfigurationType.DEPLOYMENT);
+----
+
+Remember that system properties overwrite other settings, so they are ideal to ensure that on production machine the running mode will be always set to DEPLOYMENT. 
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/maven/maven_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/maven/maven_2.adoc b/wicket-user-guide/src/main/asciidoc/maven/maven_2.adoc
new file mode 100644
index 0000000..41d56af
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/maven/maven_2.adoc
@@ -0,0 +1,128 @@
+
+
+
+NOTE: In order to follow the instructions of this paragraph you must have Maven installed on your system. The installation of Maven is out of the scope of this guide but you can easily find an extensive documentation about it on Internet.
+Another requirement is a good Internet connection (a flat ADSL is enough) because Maven needs to connect to its central repository to download the required dependencies. 
+
+
+=== From Maven to our IDE
+
+Wicket project and its dependencies are managed using Maven. This tool is very useful also when we want to create a new project based on Wicket from scratch. With a couple of shell commands we can generate a new project properly configured and ready to be imported into our favourite IDE.
+The main step to create such a project is to run the command which generates project's structure and its artifacts. If we are not familiar with Maven or we simply don't want to type this command by hand, we can use the utility form on Wicket site at  http://wicket.apache.org/start/quickstart.html[http://wicket.apache.org/start/quickstart.html] :
+
+image::../img/quickstart-webpage.png[]
+
+Here we have to specify the root package of our project (GroupId), the project name (ArtifactId) and which version of Wicket we want to use (Version).
+Once we have run the resulting command in the OS shell, we will have a new folder with the same name of the project (i.e the ArtifactId). Inside this folder we can find a file called pom.xml. This is the main file used by Maven to manage our project. For example, using “org.wicketTutorial” as GroupId and “MyProject” as ArtifactId, we would obtain the following artifacts:
+
+[source,java]
+----
+ .\MyProject
+        |   pom.xml
+        |
+        \---src
+            +---main
+            |   +---java
+            |   |   \---org
+            |   |       \---wicketTutorial
+            |   |               HomePage.html
+            |   |               HomePage.java
+            |   |               WicketApplication.java
+            |   |
+            |   +---resources
+            |   |       log4j.properties
+            |   |
+            |   \---webapp
+            |       \---WEB-INF
+            |               web.xml
+            |
+            \---test
+                \---java
+                    \---org
+                        \---wicketTutorial
+                                TestHomePage.java
+
+----
+
+Amongst other things, file pom.xml contains a section delimited by tag <dependencies> which declares the dependencies of our project. By default the Maven archetype will add the following Wicket modules as dependencies:
+
+[source,xml]
+----
+...
+<dependencies>
+	<!--  WICKET DEPENDENCIES -->
+	<dependency>
+		<groupId>org.apache.wicket</groupId>
+		<artifactId>wicket-core</artifactId>
+		<version>${wicket.version}</version>
+	</dependency>
+	<dependency>
+		<groupId>org.apache.wicket</groupId>
+		<artifactId>wicket-ioc</artifactId>
+		<version>${wicket.version}</version>
+	</dependency>
+	<!-- OPTIONAL DEPENDENCY
+	<dependency>
+		<groupId>org.apache.wicket</groupId>
+		<artifactId>wicket-extensions</artifactId>
+		<version>${wicket.version}</version>
+	</dependency>
+	--> 
+	...
+</dependencies>
+...
+----
+
+If we need to use more Wicket modules or additional libraries, we can add the appropriate XML fragments here.
+
+=== Importing a Maven project into our IDE
+
+Maven projects can be easily imported into the most popular Java IDEs. However, the procedure needed to do this differs from IDE to IDE. In this paragraph we can find the instructions to import Maven projects into three of the most popular IDEs among Java developers : NetBeans, JetBrains IDEA and Eclipse.
+
+*NetBeans*
+Starting from version 6.7, NetBeans includes Maven support, hence we can start it and directly open the folder containing our project:
+
+image::../img/netbeans-maven-import.png[]
+
+*Intellj IDEA*
+Intellj IDEA comes with a Maven importing functionality that can be started under “File/New Project/Import from external model/Maven”. Then, we just have to select the pom.xml file of our project:
+
+image::../img/intellj-maven-import.png[]
+
+*Eclipse*
+If our IDE is Eclipse the import procedure is a little more complex. Before opening the new project we must generate the Eclipse project artifacts running the following command from project root:
+
+[source,java]
+----
+mvn eclipse:eclipse
+----
+
+  Now to import our project into Eclipse we must create a classpath variable called M2_REPO that must point to your local Maven repository. This can be done selecting “Window/Preferences” and searching for “Classpath Variables”. The folder containing our local Maven repository is usually under our user folder and is called .m2 (for example under Unix system is /home/<myUserName>/.m2/repository):
+
+image::../img/eclipse-classpath-variables.png[]
+
+Once we have created the classpath variable we can go to “File/Import.../Existing Project into Workspace”, select the directory of the project and press “Finish”:
+
+image::../img/eclipse-maven-import.png[]
+
+Once the project has been imported into Eclipse, we are free to use our favourite plug-ins to run it or debug it (like for example  [run-jetty-run] http://code.google.com/p/run-jetty-run/ ).  
+
+NOTE: Please note the option “Copy projects into workspace” in the previous illustration. If we select it, the original project generated with Maven won't be affected by the changes made inside Eclipse because we will work on a copy of it under the current workspace.
+
+NOTE: If we modify the pom.xml file (for example adding further dependencies) we must regenerate project's artifacts and refresh the project (F5 key) to reflect changes into Eclipse.
+
+=== Speeding up development with plugins.
+
+Now that we have our project loaded into our IDE we could start coding our components directly by hand. However it would be a shame to not leverage the free and good Wicket plugins available for our IDE. The following is a brief overview of the most widely used plugins for each of the three main IDEs considered so far.
+
+*NetBeans*
+NetBeans offers Wicket support through 'NetBeans Plugin for Wicket' hosted at  http://plugins.netbeans.org/plugin/3586/wicket-1-4-support[http://plugins.netbeans.org/plugin/3586/wicket-1-4-support] . This plugin is released under CDDL-1.0 license. 
+You can  find a nice introduction guide to this plugin at  http://netbeans.org/kb/docs/web/quickstart-webapps-wicket.html[http://netbeans.org/kb/docs/web/quickstart-webapps-wicket.html] .
+
+*Intellj IDEA*
+For JetBrain IDEA we can use WicketForge plugin, hosted at Google Code  http://code.google.com/p/wicketforge/[http://code.google.com/p/wicketforge/] . The plugin is released under ASF 2.0 license.
+
+*Eclipse*
+With Eclipse we can install one of the plugins that supports Wicket. As of the writing of this document, the most popular is probably Qwickie, available in the Eclipse Marketplace and hosted on Google Code at  http://code.google.com/p/qwickie/[http://code.google.com/p/qwickie/] .
+QWickie is released under ASF 2.0 license.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms.adoc
new file mode 100644
index 0000000..743ad8d
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms.adoc
@@ -0,0 +1,2 @@
+
+In Wicket the concept of “model” is probably the most important topic of the entire framework and it is strictly related to the usage of its components. In addition, models are also an important element for  internationalization, as we will see in paragraph 12.6. However, despite their fundamental role, in Wicket models are not difficult to understand but the best way to learn how they work is to use them with forms. That's why we haven't talked about models so far, and why this chapter discusses these two topics together.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_1.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_1.adoc
new file mode 100644
index 0000000..3023be0
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_1.adoc
@@ -0,0 +1,66 @@
+
+
+
+Model is essentially a  http://en.wikipedia.org/wiki/Facade_pattern[facade] interface which allows components to access and modify their data without knowing any detail about how they are managed or persisted. Every component has at most one related model, while a model can be shared among different components. In Wicket a model is any implementation of the interface _org.apache.wicket.model.IModel_:
+
+image::../img/uml-imodel.png[]
+
+The IModel interface defines just the methods needed to get and set a data object (getObject() and setObject()), decoupling components from concrete details about the persistence strategy adopted for data. In addition, the level of indirection introduced by models allows access data object only when it is really needed (for example during the rendering phase) and not earlier when it may not be ready to be used.
+
+Any component can get/set its model as well as its data object using the 4 public shortcut methods listed in the class diagram above. The two methods onModelChanged() and onModelChanging() are triggered by Wicket each time a model is modified: the first one is called after the model has been changed, the second one just before the change occurs. In the examples seen so far we have worked with Label component using its constructor which takes as input two string parameters, the component id and the text to display:
+
+[source,java]
+----
+add(new Label("helloMessage", "Hello WicketWorld!"));
+----
+
+This constructor internally builds a model which wraps the second string parameter. That's why we didn't mention label model in the previous examples. Here is the code of this constructor:
+
+[source,java]
+----
+public Label(final String id, String label) {
+	this(id, new Model<String>(label));
+}
+----
+
+Class _org.apache.wicket.model.Model_ is a basic implementation of _IModel_. It can wrap any object that implements the interface java.io.Serializable. The reason of this constraint over data object is that this model is stored in the web session, and we know from chapter 6 that data are stored into session using serialization.
+
+NOTE: In general, Wicket models support a detaching capability that allows us to work also with non-serializable objects as data model. We will see the detaching mechanism later in this chapter.
+
+Just like any other Wicket components, Label provides a constructor that takes as input the component id and the model to use with the component. Using this constructor the previous example becomes:
+
+[source,java]
+----
+add(new Label("helloMessage", new Model<String>("Hello WicketWorld!")));
+----
+
+NOTE: The Model class comes with a bunch of factory methods that makes it easier to build new model instances. For example the of(T object) method creates a new instance of Model which wraps any Object instance inside it. So instead of writing
+	
+	new Model<String>( [Hello WicketWorld!] 
+we can write
+	
+	Model.of( [Hello WicketWorld!] 
+If the data object is a List, a Map or a Set we can use similar methods called ofList, ofMap and ofSet.   
+From now on we will use these factory methods in our examples.
+
+It's quite clear that if our Label must display a static text it doesn't make much sense to build a model by hand like we did in the last code example.
+However is not unusual to have a Label that must display a dynamic value, like the input provided by a user or a value read from a database. Wicket models are designed to solve these kinds of problems.
+
+Let's say we need a label to display the current time stamp each time a page is rendered. We can implement a custom model which returns a new Date instance when the getObject() method is called:
+
+[source,java]
+----
+IModel timeStampModel = new Model<String>(){
+	@Override
+	public String getObject() {
+		return new Date().toString();
+	}
+};
+
+add(new Label("timeStamp", timeStampModel));
+----
+
+Even if sometimes writing a custom model could be a good choice to solve a specific problem, Wicket already provides a set of IModel implementations which should fit most of our needs. In the next paragraph we will see a couple of models that allow us to easily integrate JavaBeans with our web applications and in particular with our forms.
+
+NOTE: By default the class Component escapes HTML sensitive characters (like '<', '>' or '&') from the textual representation of its model object. The term 'escape' means that these characters will be replaced with their corresponding HTML  http://en.wikipedia.org/wiki/Character_entity_reference[entity] (for example '<' becomes '&lt; '). This is done for security reasons as a malicious user could attempt to inject markup or JavaScript into our pages. If we want to display the raw content stored inside a model, we can tell the Component class not to escape characters by calling the setEscapeModelStrings(false) method.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc
new file mode 100644
index 0000000..3019497
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_2.adoc
@@ -0,0 +1,128 @@
+
+
+
+One of the main goals of Wicket is to use JavaBeans and POJO as data model, overcoming the impedance mismatch between web technologies and OO paradigm. In order to make this task as easy as possible, Wicket offers two special model classes: _org.apache.wicket.model.PropertyModel_ and _org.apache.wicket.model.CompoundPropertyModel_. We will see how to use them in the next two examples, using the following JavaBean as the data object:
+
+[source,java]
+----
+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<Person> children;
+       
+	public Person(String name, String surname) {
+		this.name = name;
+		this.surname = surname;
+	}
+
+	public String getFullName(){
+   		return name + " " + surname;
+	} 
+
+	/* 	 
+	 * Getters and setters for private fields
+     */
+}
+----
+
+=== PropertyModel
+
+Let's say we want to display the name field of a Person instance with a label. We could, of course, use the Model class like we did in the previous example, obtaining something like this:
+
+[source,java]
+----
+Person person = new Person();		
+//load person's data...
+		
+Label label = new Label("name", new Model(person.getName()));
+----
+
+However this solution has a huge drawback: the text displayed by the label will be static and if we change the value of the field, the label won't update its content. Instead, to always display the current value of a class field, we should use the _org.apache.wicket.model.PropertyModel_ model class:
+
+[source,java]
+----
+Person person = new Person();		
+//load person's data...
+		
+Label label = new Label("name", new PropertyModel(person, "name"));
+----
+
+PropertyModel has just one constructor with two parameters: the model object (person in our example) and the name of the property we want to read/write ( [name] in our example). This last parameter is called property expression. Internally, methods getObject/setObject use property expression to get/set property's value. To resolve class properties PropertyModel uses class _org.apache.wicket.util.lang.Property_ Resolver which can access any kind of property, private fields included.
+
+Just like the Java language, property expressions support dotted notation to select sub properties. So if we want to display the name of the Person's spouse we can write:
+
+[source,java]
+----
+Label label = new Label("spouseName", new PropertyModel(person, "spouse.name"));
+----
+
+NOTE: PropertyModel is null-safe, which means we don't have to worry if property expression includes a null value in its path. If such a value is encountered, an empty string will be returned.
+
+If property is an array or a List, we can specify an index after its name. For example, to display the name of the first child of a Person we can write the following property expression:
+
+[source,java]
+----
+Label label = new Label("firstChildName", new PropertyModel(person, "children.0.name"));
+----
+
+Indexes and map keys can be also specified using squared brackets: 
+
+[source,java]
+----
+children[0].name ...
+mapField[key].subfield ...
+----
+
+=== CompoundPropertyModel and model inheritance
+
+Class _org.apache.wicket.model.CompoundPropertyModel_ is a particular kind of model which is usually used in conjunction with another Wicket feature called model inheritance. With this feature, when a component needs to use a model but none has been assigned to it, it will search through the whole container hierarchy for a parent with an inheritable model. Inheritable models are those which implement interface _org.apache.wicket.model.IComponentInheritedModel_ and _CompoundPropertyModel_ is one of them. Once a _CompoundPropertyModel_ has been inherited by a component, it will behave just like a PropertyModel using the id of the component as property expression. As a consequence, to make the most of CompoundPropertyModel we must assign it to one of the containers of a given component, rather than directly to the component itself.
+
+For example if we use CompoundPropertyModel with the previous example (display spouse's name), the code would become like this:
+
+[source,java]
+----
+//set CompoundPropertyModel as model for the container of the label
+setDefaultModel(new CompoundPropertyModel(person));
+
+Label label = new Label("spouse.name");	
+
+add(label);
+----
+
+Note that now the id of the label is equal to the property expression previously used with PropertyModel. Now as a further example let's say we want to extend the code above to display all of the main informations of a person (name, surname, address and email). All we have to do is to add one label for every additional information using the relative property expression as component id:
+
+[source,java]
+----
+//Create a person named 'John Smith'
+Person person = new Person("John", "Smith");
+setDefaultModel(new CompoundPropertyModel(person));
+
+add(new Label("name"));
+add(new Label("surname"));
+add(new Label("address"));
+add(new Label("email"));
+add(new Label("spouse.name"));
+----
+
+CompoundPropertyModel can save us a lot of boring coding if we choose the id of components according to properties name. However it's also possible to use this type of model even if the id of a component does not correspond to a valid property expression. The method bind(String property) allows to create a property model from a given CompoundPropertyModel using the provided parameter as property expression. For example if we want to display the spouse's name in a label having  [xyz] as id, we can write the following code:
+
+[source,java]
+----
+//Create a person named 'John Smith'
+Person person = new Person("John", "Smith");
+CompoundPropertyModel compoundModel;
+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.
+
+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.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc
new file mode 100644
index 0000000..db125ec
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_3.adoc
@@ -0,0 +1,192 @@
+
+
+
+Web applications use HTML forms to collect user input and send it to the server. Wicket provides _org.apache.wicket.markup.html.form.Form_ class to handle web forms. This component must be bound to <form> tag. The following snippet shows how to create a very basic Wicket form in a page:
+
+Html:
+
+[source,html]
+----
+<form wicket:id="form">
+    <input type="submit" value="submit"/>
+</form>
+----
+
+
+Java code:
+
+[source,java]
+----
+Form form = new Form("form"){
+    @Override
+    protected void onSubmit() {
+    	System.out.println("Form submitted.");
+    }
+};
+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). 
+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
+
+A form should contain some input fields (like text fields, check boxes, radio buttons, drop-down lists, text areas, etc.) to interact with users. Wicket provides an abstraction for all these kinds of elements with component org.apache.wicket.markup.html.form.FormComponent:
+
+image::../img/uml-form-component.png[]
+
+The purpose of FormComponent is to store the corresponding user input into its model when the form is submitted. The form is responsible for mapping input values to the corresponding components, avoiding us the burden of manually synchronizing models with input fields and vice versa.
+
+=== Login form
+
+As first example of interaction between the form and its models, we will build a classic login form which asks for username and password (project LoginForm).
+
+WARNING: The topic of security will be discussed later in chapter 22. The following form is for example purposes only and is not suited for a real application.
+If you need to use a login form you should consider to use component _org.apache.wicket.authroles.authentication.panel.SignInPanel_ shipped with Wicket.
+
+This form needs two text fields, one of which must be a password field. We should also use a label to display the result of login process1. For the sake of simplicity, the login logic is all inside onSubmit and is quite trivial.
+
+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(""));			
+		loginStatus = new Label("loginStatus", Model.of(""));
+			
+		add(usernameField);
+		add(passwordField);
+		add(loginStatus);
+	}
+
+	public final void onSubmit() {
+		String username = (String)usernameField.getDefaultModelObject();
+		String password = (String)passwordField.getDefaultModelObject();
+
+		if(username.equals("test") && password.equals("test"))
+			loginStatus.setDefaultModelObject("Congratulations!");
+		else
+			loginStatus.setDefaultModelObject("Wrong username or password!");			
+	}
+}
+----
+
+Inside form's constructor we build the three components used in the form and we assign them a model containing an empty string:
+
+[source,java]
+----
+usernameField = new TextField("username", Model.of(""));
+passwordField = new PasswordTextField("password", Model.of(""));			
+loginStatus = new Label("loginStatus", Model.of(""));
+----
+
+If we don't provide a model to a form component, we will get the following exception on form submission:
+
+[source,java]
+----
+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 <input> tag with the attribute type set to  [text] PasswordTextField is a subtype of TextFiled and it must be used with an <input> tag with the attribute type set to [password] For security reasons component PasswordTextField cleans its value at each request, so it wil 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:
+
+Html:
+
+[source,html]
+----
+<html>
+	<head>
+  		<title>Login page</title>
+	</head>
+	<body>
+		<form id="loginForm" method="get" wicket:id="loginForm">
+  			<fieldset>
+    			<legend style="color: #F90">Login</legend>
+    				<p wicket:id="loginStatus"></p>
+    				<span>Username: </span><input wicket:id="username" type="text" id="username" /><br/>
+    				<span>Password: </span><input wicket:id="password" type="password" id="password" />
+    				<p>
+    					<input type="submit" name="Login" value="Login"/>
+    				</p>
+  	   	    </fieldset>
+		</form>
+	</body>
+</html>
+----
+
+Java code:
+
+[source,java]
+----
+public class HomePage extends WebPage {
+ 
+   public HomePage(final PageParameters parameters) {
+		
+		super(parameters);
+    	add(new LoginForm("loginForm"));
+
+    }
+}
+----
+
+The example shows how Wicket form components can be used to store user input inside their model. However we can dramatically improve the form code using CompoundPropertyModel and its ability to access the properties of its model object. The revisited code is the following (the LoginFormRevisited project):
+
+[source,java]
+----
+public class LoginForm extends Form{
+		
+		private String username;
+		private String password;
+		private String loginStatus;
+		
+		public LoginForm(String id) {
+			super(id);			
+			setDefaultModel(new CompoundPropertyModel(this));
+			
+			add(new TextField("username"));
+			add(new PasswordTextField("password"));
+			add(new Label("loginStatus"));
+		}
+
+		public final void onSubmit() {			
+			if(username.equals("test") && password.equals("test"))
+				loginStatus = "Congratulations!";
+			else
+				loginStatus = "Wrong username or password !";			
+		}
+	}
+----
+
+In this version the form itself is used as model object for its CompoundPropertyModel. This allows children components to have direct access to form fields and use them as backing objects, without explicitly creating a model for themselves.
+
+NOTE: Keep in mind that when CompoundPropertyModel is inherited, it does not consider the ids of traversed containers for the final property expression, but it will always use the id of the visited child. To understand this potential pitfall, let's consider the following initialization code of a page:
+
+[source,java]
+----
+//Create a person named 'John Smith'
+Person person = new Person("John", "Smith");
+//Create a person named 'Jill Smith'
+Person spouse = new Person("Jill", "Smith");
+//Set Jill as John's spouse
+person.setSpouse(spouse);
+
+setDefaultModel(new CompoundPropertyModel(person));
+WebMarkupContainer spouseContainer = new WebMarkupContainer("spouse");
+Label name;
+spouseContainer.add(name = new Label("name"));
+
+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.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc
new file mode 100644
index 0000000..f299e61
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_4.adoc
@@ -0,0 +1,59 @@
+
+
+
+Class _org.apache.wicket.markup.html.form.DropDownChoice_ is the form component needed to display a list of possible options as a drop-down list where users can select one of the proposed options. This component must be used with <select> tag:
+
+Html:
+
+[source,html]
+----
+<form wicket:id="form">
+	Select a fruit: <select wicket:id="fruits"></select>
+<div><input type="submit" value="submit"/></div>
+</form>
+----
+
+Java code:
+
+[source,java]
+----
+List<String> fruits = Arrays.asList("apple", "strawberry", "watermelon"); 
+form.add(new DropDownChoice<String>("fruits", new Model(), fruits));
+----
+
+Screenshot of generated page:
+
+image::../img/dropdown-choice.png[]
+
+In addition to the component id, in order to build a DropDownChoice we need to provide to its constructor two further parameters:
+
+* a model containing the current selected item. This parameter is not required if we are going to inherit a CompoundPropertyModel for this component.
+* a list of options to display which can be supplied as a model or as a regular java.util.List.
+
+In the example above the possible options are provided as a list of String objects. Now let's take a look at the markup generated for them:
+
+[source,html]
+----
+<select name="fruits" wicket:id="fruits">
+	<option value="" selected="selected">Choose One</option>
+	<option value="0">apple</option>
+	<option value="1">strawberry</option>
+	<option value="2">watermelon</option>
+</select>
+----
+
+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_ inte
 rface. 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: 
+
+Java code:
+
+[source,java]
+----
+List<Person> persons; 
+//Initialize the list of persons here...
+ChoiceRenderer personRenderer = new ChoiceRenderer("fullName", "passportCode");
+form.add(new DropDownChoice<String>("persons", new Model<Person>(), 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.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc
new file mode 100644
index 0000000..f7d4b1c
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_5.adoc
@@ -0,0 +1,105 @@
+
+
+
+Models that implement the interface _org.apache.wicket.model.IChainingModel_ can be used to build a chain of models. These kinds of models are able to recognize whether their model object is itself an implementation of IModel and if so, they will call getObject on the wrapped model and the returned value will be the actual model object. In this way we can combine the action of an arbitrary number of models, making exactly a chain of models. Chaining models allows to combine different data persistence strategies, similarly to what we do with chains of  http://java.sun.com/developer/technicalArticles/Streams/ProgIOStreams[I/O streams.] To see model chaining in action we will build a page that implements the List/Detail View pattern, where we have a drop-down list of Person objects and a form to display and edit the data of the current selected Person.
+
+The example page will look like this:
+
+image::../img/model-chaining.png[]
+
+What we want to do in this example is to chain the model of the DropDownChoice (which contains the selected Person) with the model of the Form. In this way the Form will work with the selected Person as backing object. The DropDownChoice component can be configured to automatically update its model each time we change the selected item on the client side. All we have to do is to override method wantOnSelectionChangedNotifications to make it return true. In practice, when this method returns true, DropDownChoice will submit its value every time JavaScript event onChange occurs, and its model will be consequently updated. To leverage this functionality, DropDownChoice doesn't need to be inside a form.
+
+The following is the resulting markup of the example page:
+
+[source,html]
+----
+...
+<body>
+	List of persons <select wicket:id="persons"></select> <br/>
+	<br/>
+	<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>	
+						<input type="submit" value="Save"/>
+					</form>
+				</body>				
+----
+
+The initialization code for DropDownChoice is the following:
+
+[source,java]
+----
+Model<Person> listModel = new Model<Person>();
+ChoiceRenderer<Person> personRender = new ChoiceRenderer<Person>("fullName");
+personsList = new DropDownChoice<Person>("persons", listModel, loadPersons(), personRender){
+		
+		@Override
+		protected boolean wantOnSelectionChangedNotifications() {
+			return true;
+		}
+		
+};
+----
+
+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.
+
+Here is the whole code of the page (except for the loadPersons() method):
+
+[source,java]
+----
+public class PersonListDetails extends WebPage {
+  private Form form;
+  private DropDownChoice<Person> personsList;
+  
+  public PersonListDetails(){
+    Model<Person> listModel = new Model<Person>();
+    ChoiceRenderer<Person> personRender = new ChoiceRenderer<Person>("fullName");
+    
+    personsList = new DropDownChoice<Person>("persons", listModel, loadPersons(),
+                                                         personRender){
+      @Override
+      protected boolean wantOnSelectionChangedNotifications() {
+        return true;
+      }
+	    };    
+
+	    add(personsList);
+
+	    form = new Form("form", new CompoundPropertyModel<Person>(listModel));    
+	    form.add(new TextField("name"));
+	    form.add(new TextField("surname"));
+	    form.add(new TextField("address"));
+	    form.add(new TextField("email"));
+
+	    add(form);
+	  }
+	       //loadPersons()
+	       //...
+	}
+----
+
+The two models work together as a pipeline where the output of method getObject of Model is the model object of CompoundPropertyModel. As we have seen, model chaining allows us to combine the actions of two or more models without creating new custom implementations.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc
new file mode 100644
index 0000000..d925aa5
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_6.adoc
@@ -0,0 +1,81 @@
+
+
+
+In chapter 6 we have seen how Wicket uses serialization to store page instances. When an object is serialized, all its referenced objects are recursively serialized. For a page this means that all its children components, their related models as well as the model objects inside them will be serialized. 
+For model objects this could be a serious issue for (at least) two main reasons:
+
+1. The model object could be a very large instance, hence serialization would become very expensive in terms of time and memory.
+2. We simply may not be able to use a serializable object as model object. In paragraphs 1.4 and 9.2 we stated that Wicket allows us to use a POJO as backing object, but  http://en.wikipedia.org/wiki/Plain_Old_Java_Object#Definition[POJOs] are ordinary objects with no prespecified interface, annotation or superclass, hence they are not required to implement the standard Serializable interface.
+
+To cope with these problems IModel extends another interface called IDetachable.
+
+image::../img/detachable-models.png[]
+
+This interface provides a method called detach() which is invoked by Wicket at the end of web request processing when data model is no more needed but before serialization occurs. Overriding this method we can clean any reference to data object keeping just the information needed to retrieve it later (for example the id of the table row where our data are stored). In this way we can avoid the serialization of the object wrapped into the model overcoming both the problem with non-serializable objects and the one with large data objects.
+
+Since IModel inherits from IDetachable, every model of Wicket is “detachable”, although not all of them implement a detaching policy (like the Model class). 
+Usually detaching operations are strictly dependent on the persistence technology adopted for model objects (like a relational db, a NoSQL db, a queue, etc), so it's not unusual to write a custom detachable model suited for the persistence technology chosen for a given project. To ease this task Wicket provides abstract model LoadableDetachableModel. This class internally holds a transient reference to a model object which is initialized the first time getObject()is called to precess a request. The concrete data loading is delegated to abstract method T load(). The reference to a model object is automatically set to null at the end of the request by the detach() method.
+
+The following class diagram summarizes the methods defined inside LoadableDetachableModel.
+
+image::../img/loadable-detachable-model.png[]
+
+onDetach and onAttach can be overridden in order to obtain further control over the detaching procedure.
+
+Now as example of a possible use of LoadableDetachableModel, we will build a model designed to work with entities managed via  http://en.wikipedia.org/wiki/Java_Persistence_API[JPA.] To understand the following code a basic knowledge of JPA is required even if we won't go into the detail of this standard.
+
+WARNING: The following model is provided for example purposes only and is not intended to be used in production environment. Important aspects such as transaction management are not taken into account and you should rework the code before considering to use it.
+
+[source,java]
+----
+public class JpaLoadableModel<T> extends LoadableDetachableModel<T> {
+  
+  private EntityManagerFactory entityManagerFactory;
+  private Class<T> entityClass;
+  private Serializable identifier;
+  private List<Object> constructorParams;
+  
+  public JpaLoadableModel(EntityManagerFactory entityManagerFactory, T entity) {
+     
+	super();
+     
+	PersistenceUnitUtil util = entityManagerFactory.getPersistenceUnitUtil();
+	      
+		this.entityManagerFactory = entityManagerFactory;
+	    this.entityClass = (Class<T>) entity.getClass();
+	    this.identifier = (Serializable) util.getIdentifier(entity);
+
+	    setObject(entity);
+	}
+
+	@Override
+	protected T load() {
+	   T entity = null;
+
+	   if(identifier != null) {  
+	       EntityManager entityManager = entityManagerFactory.createEntityManager();
+	       entity = entityManager.find(entityClass, identifier);
+	     }
+	     return entity;
+	   }
+
+	@Override
+	protected void onDetach() {
+	   super.onDetach();
+
+	     T entity = getObject();
+	     PersistenceUnitUtil persistenceUtil = entityManagerFactory.getPersistenceUnitUtil();
+
+	     if(entity == null) return;
+
+	     identifier = (Serializable) persistenceUtil.getIdentifier(entity);    
+	  }
+	}
+----
+
+The constructor of the model takes as input two parameters: an implementation of the JPA interface  javax.persistence.EntityManagerFactory to manage JPA entities and the entity that must be handled by this model. Inside its constructor the model saves the class of the entity and its id (which could be null if the entity has not been persisted yet). These two informations are required to retrieve the entity at a later time and are used by the load method.
+
+onDetach is responsible for updating the entity id before detachment occurs. The id can change the first time an entity is persisted (JPA generates a new id and assigns it to the entity). Please note that this model is not responsible for saving any changes occurred to the entity object before it is detached. If we don't want to loose these changes we must explicitly persist the entity before the detaching phase occurs.
+
+WARNING: Since the model of this example holds a reference to the EntityManager Factory, the implementation in use must be serializable.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_7.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_7.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_7.adoc
new file mode 100644
index 0000000..8d99611
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_7.adoc
@@ -0,0 +1,32 @@
+
+
+
+Sometimes our custom components may need to use more than a single model to work properly. In such a case we must manually detach the additional models used by our components. In order to do this we can overwrite the Component's onDetach method that is called at the end of the current request. The following is the generic code of a component that uses two models:
+
+[source,java]
+----
+/**
+ * 
+ * fooModel is used as main model while beeModel must be manually detached
+ *
+ */
+public class ComponetTwoModels extends Component{
+
+	private IModel<Bee> beeModel;
+
+	public ComponetTwoModels(String id, IModel<Foo> fooModel, IModel<Bee> beeModel) {
+		super(id, fooModel);
+		this.beeModel = beeModel;
+	}
+
+	@Override
+	public void onDetach() {
+               if(beeModel != null)
+	   beeModel.detach();
+             
+              super.onDetach();
+	}
+}
+----
+
+When we overwrite onDetach we must call the super class implementation of this method, usually as last line in our custom implementation.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_8.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_8.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_8.adoc
new file mode 100644
index 0000000..ac6dc44
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_8.adoc
@@ -0,0 +1,24 @@
+
+
+
+Like many people new to Wicket, you may need a little time to fully understand the power and the advantages of using models. Taking your first steps with Wicket you may be tempted to pass row objects to your components instead of using models:
+
+[source,java]
+----
+/**
+ * 
+ * NOT TO DO: passing row objects to components instead of using models!
+ *
+ */
+public class CustomComponent extends Component{
+	private FooBean fooBean;
+
+	public CustomComponent(String id, FooBean fooBean) {
+		super(id);
+		this.fooBean = fooBean;
+	}
+	//...some other ugly code :)...
+}
+----
+
+That's a bad practice and you must avoid it. 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.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc
new file mode 100644
index 0000000..e24bbca
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/modelsforms/modelsforms_9.adoc
@@ -0,0 +1,5 @@
+
+
+
+Models are at the core of Wicket and they are the basic ingredient needed to taste the real power of the framework. In this chapter we have seen how to use models to bring data to our components without littering their code with technical details about their persistence strategy.
+We have also introduced Wicket forms as complementary topic. With forms and models we are able to bring our applications to life allowing them to interact with users. But what we have seen in this chapter about Wicket forms is just the tip of the iceberg. That's why the next chapter is entirely dedicated to them.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/monitoring.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/monitoring.adoc b/wicket-user-guide/src/main/asciidoc/monitoring.adoc
new file mode 100644
index 0000000..40fb294
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/monitoring.adoc
@@ -0,0 +1,10 @@
+
+The wicket-metrics module is available since Wicket 7.3.0 and contains a life measurement implementation to collect data of applications and visualize it.
+
+You can see how many request your application served, how often components are created, initalized, configured or their detach method has been invoked and a lot of other additional information.
+
+The module itself is using  https://dropwizard.github.io/metrics/3.1.0/[Metrics of dropwizard] and  https://eclipse.org/aspectj/[AspectJ] so that if you turn of the measurement it has no longer any effect
+
+to your web application.
+
+Keep in mind that AspectJ is licensed under the Eclipse Public License and you should provide the required license information.

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc
new file mode 100644
index 0000000..cccb985
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_1.adoc
@@ -0,0 +1,86 @@
+
+This is a little example how to setup wicket-metrics within a Apache Tomcat.
+
+(1)  Add the maven dependency to your project
+[source,java]
+----
+<dependency>
+	<groupId>org.apache.wicket.experimental.wicket7</groupId>
+	<artifactId>wicket-metrics</artifactId>
+	<version>0.X-SNAPSHOT</version>
+</dependency>
+----
+
+(2) Just drop the jars of aspectjrt and aspectjweaver into the tomcat lib folder - you can download it from here  http://mvnrepository.com/artifact/org.aspectj/[http://mvnrepository.com/artifact/org.aspectj/] (the metrics dependency is shipped with the project)
+
+(3) Add the java agent to the jvm start options of your tomcat: -javaagent:/pathToServer/lib/aspectjweaver-x.x.x.jar
+
+(4) Add an aop.xml to your project's META-INF folder at the root of your classpath with the metrics you want to use (aspect tags) - if you don't want to enable a metrics just remove the aspect tag:
+[source,java]
+----
+<!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/aspectj.dtd">
+<aspectj>
+    <weaver options="-nowarn">
+        <include within="org.apache.wicket..*"/>
+    </weaver>
+    <aspects>
+		<!-- required -->
+		<aspect name="org.apache.wicket.metrics.aspects.WicketFilterInitAspect" />
+
+		<!-- optional -->
+		<aspect name="org.apache.wicket.metrics.aspects.model.LoadableDetachableModelLoadAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.requesthandler.IRequestHandlerDetachAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.requesthandler.IRequestHandlerRespondAspect" />
+ 		<aspect name="org.apache.wicket.metrics.aspects.resource.IResourceCreateAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.behavior.BehaviorCreateAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.component.ComponentCreateAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnConfigureAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnDetachAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnInitializeAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.component.ComponentOnRenderAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.component.ComponentSetResponsePageAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.ajax.IPartialPageRequestHandlerAddAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.ajax.IPartialPageRequestHandlerAppendJavaScriptAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.ajax.IPartialPageRequestHandlerPrependJavaScriptAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.resource.ResourceReferenceCreateAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.markup.WicketTagCreateAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.request.WicketFilterRequestCycleUrlAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.request.WicketFilterRequestCycleAspect" />
+		<aspect name="org.apache.wicket.metrics.aspects.session.SessionCountListenerAspect" />
+    </aspects>
+</aspectj>
+----
+
+* If you use the SessionCountListenerAspect you have to ensure that metadata-complete= [false] is set otherwise you have to add the listener yourself:
+[source,java]
+----
+<listener>
+	<listener-class>
+	   org.apache.wicket.metrics.aspects.session.SessionCountListener
+	</listener-class>
+</listener>
+----
+
+(5 - optional) To enable the JMX measurement write the following line into your init method of your Application (Now you are able to connect with jvisualvm to your server and have a look at the data):
+[source,java]
+----
+WicketMetrics.getSettings().startJmxReporter();
+----
+
+To deactivate:
+[source,java]
+----
+WicketMetrics.getSettings().stopJmxReporter();
+----
+
+To disable measurement:
+[source,java]
+----
+WicketMetrics.getSettings().setEnabled(false);
+----
+
+*IMPORTANT INFORMATION*
+** It is only possible to collect metrics for *one wicket filter per webapp* - don't declare more then one if you want to use wicket-metrics
+** The WicketFilterInitAspect is required so that the application can be resolved - otherwise runtime exceptions will be thrown
+** If you use the SessionCountListener you have to clear the session store if you restart the server - otherwise physically stored session will corrupt the data, because the count is initialized with 0.
+** If you have set wicket-metrics as dependency you can open  [wicket-metrics.template.xml] to get a full template of the  [aop.xml] ** For the weaver options refer to the AspectJ LTW configuration documentation: https://eclipse.org/aspectj/doc/next/devguide/ltw-configuration.html

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc
new file mode 100644
index 0000000..7244fb8
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_2.adoc
@@ -0,0 +1,88 @@
+
+To visualize the metrics with Graphite a little additional configuration is required:
+
+(1) Add the additional maven dependency to your project:
+[source,java]
+----
+<dependency>
+	<groupId>io.dropwizard.metrics</groupId>
+	<artifactId>metrics-graphite</artifactId>
+	<version>${metrics.graphite.version}</version>
+</dependency>
+----
+
+* the metrics.graphite.version should be the same as the metrics version of the wicket-metrics dependency. Check the Maven dependencies to ensure
+this.
+
+(2) Add the following code to your Application's init method:
+[source,java]
+----
+	private GraphiteReporter reporter;
+	
+	@Override
+	protected void init()
+	{
+		MetricRegistry metricRegistry = WicketMetrics.getMetricRegistry();
+		final Graphite graphite = new Graphite(new InetSocketAddress("127.0.0.1", 2003));
+		reporter = GraphiteReporter.forRegistry(metricRegistry).prefixedWith("WebApplications")
+			.convertRatesTo(TimeUnit.SECONDS).convertDurationsTo(TimeUnit.MILLISECONDS)
+			.filter(MetricFilter.ALL).build(graphite);
+		
+		// Collects data every 5 seconds
+		reporter.start(5, TimeUnit.SECONDS);
+	}
+
+	@Override
+	protected void onDestroy()
+	{
+		super.onDestroy();
+		reporter.stop();
+	}
+----
+
+(3) Install and setup graphite on your system. Example installation for Mac (beware that this is only a quickstart setup!):
+
+- (1) Install homebrew:  http://brew.sh/[brew] 
+- (2) Install  https://git-scm.com/[Git] 
+
+- (3) brew install python
+
+- (4) brew install cairo
+
+- (5) brew install py2cairo
+
+- (6) pip install Django==1.5
+
+- (7) pip install  [django-tagging<0.4] 
+- (8) sudo pip install carbon
+
+- (9) pip install whisper
+
+- (10) sudo pip install graphite-web
+
+- (11) sudo pip install Twisted==11.1.0 
+
+- (12) sudo chown -R <your username>:staff /opt/graphite
+
+- (13) cp /opt/graphite/conf/carbon.conf{.example,}
+
+- (14) cp /opt/graphite/conf/storage-schemas.conf{.example,}
+
+- (15) cd /opt/graphite/webapp/graphite
+
+- (16) cp local_settings.py{.example,}
+
+- (17) python manage.py syncdb
+
+- (18) python /opt/graphite/bin/carbon-cache.py start
+
+- (19) python /opt/graphite/bin/run-graphite-devel-server.py /opt/graphite
+
+- (20) Go to http://localhost:8080
+
+* (18) and (19) have to be executed if the mac has been restarted 
+
+(4) Now start your tomcat server configured like mentioned in the previous chapter.
+
+image::../img/wicket_metrics_graphite.png[]
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc
new file mode 100644
index 0000000..5e655fc
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_3.adoc
@@ -0,0 +1,20 @@
+
+The data which is going to be measured depends on the wicket-metrics implementation. So it doesn't make any sense to collect time data
+
+about setResponsePage, but it does for the constructor of components, to see if a component needs a long time to be created. You can
+
+get the information about which data has been collected from out of the mbeans.
+
+Here are some information about them:
+
+* max - the maximal time for a task (created, initialized, etc.)
+
+* min - the minimal time for a task (created, initialized, etc.)
+
+* count - how often something happened (request count)
+
+The structure is separated in the way that under core there are the kind of components measured and below that the type of operation
+
+(created, initialized, detached). In this category every component is listed dynamically.
+
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc
new file mode 100644
index 0000000..e199e1e
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/monitoring/monitoring_4.adoc
@@ -0,0 +1,42 @@
+
+There are only a two steps required to write own measurements for life data statistics in Wicket:
+
+(1) Write a class which is named very close to what it measures. This class should extends WicketMetrics and should annotated with _Aspect and provide one method with a join point scanning for the target signature.
+[source,java]
+----
+	@Aspect
+	public class MySpecialAspect extends WicketMetrics
+	{
+		@Around("execution(* my.package.MyClass.myMethod(..))")
+		public Object aroundRequestProcessed(ProceedingJoinPoint joinPoint) throws Throwable
+		{
+			return measureTime("mycategory/someinformation/", joinPoint);
+		}
+	}
+----
+* To measure time you need _Around because measureTime of WicketMetrics requires the joinPoint - the class name is appended with a slash at the end
+
+* To only mark that a method is called you can use mark of WicketMetrics and apply null as a second parameter - if you apply a join point to mark the class name is appended with a slash at the end
+
+(2) Add the class to your aop.xml and of course the package to scan for classes that are target for your measurements:
+[source,java]
+----
+<!DOCTYPE aspectj PUBLIC "-//AspectJ//DTD//EN" "http://www.eclipse.org/aspectj/dtd/aspectj.dtd">
+<aspectj>
+    <weaver options="-nowarn">
+    	<include within="org.apache.wicket..*"/>
+        <include within="my.components.package..*"/>
+    </weaver>
+    <aspects>
+    	<!-- required -->
+    	<aspect name="org.apache.wicket.metrics.aspects.WicketFilterInitAspect" />
+    	
+    	<!-- own aspects -->
+    	<aspect name="my.aspect.package.MySpecialAspect" />
+    	
+    	<!-- wickets own metrics -->
+    	.....
+    </aspects>
+</aspectj>
+----
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc
new file mode 100644
index 0000000..aff2803
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets.adoc
@@ -0,0 +1,10 @@
+
+http://en.wikipedia.org/wiki/WebSocket[WebSockets]
+This means that once the browser establish a web socket connection to the server the server can push data back to the browser without the browser explicitly asking again and again whether there is something new for it.
+
+Wicket Native WebSockets modules provide functionality to integrate with the non-standard APIs provided by different web containers (like http://tomcat.apache.org/[Apache Tomcat]
+
+WARNING: Native WebSocket works only when both the browser and the web containers support WebSocket technology. There are no plans to add support to fallback to long-polling, streaming or any other technology that simulates two way communication. Use it only if you really know that you will run your application in an environment that supports WebSockets.
+Currently supported web containers are Jetty 7.5+ , Tomcat 7.0.27+ and JBoss WildFly 8.0.0+.
+Supported browsers can be found at http://caniuse.com/#search=websocket[caniuse.com]
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc
new file mode 100644
index 0000000..b960ffe
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_1.adoc
@@ -0,0 +1,10 @@
+
+Each of the modules provide a specialization of _org.apache.wicket.protocol.http.WicketFilter_ that registers implementation specific endpoint when an HTTP request is http://en.wikipedia.org/wiki/WebSocket#WebSocket_protocol_handshake[upgraded]
+
+WebSockets communication can be used in a Wicket page by using _org.apache.wicket.protocol.ws.api.WebSocketBehavior_ or in a IResource by exteding _org.apache.wicket.protocol.ws.api.WebSocketResource_.
+When a client is connected it is being registered in a application scoped registry using as a key the application name, the client http session id, and the id of the page or the resource name that registered it. Later when the server needs to push a message it can use this registry to filter out which clients need to receive the message.
+
+When a message is received from the client Wicket wraps it in _IWebSocketMessage_ and calls WebSocketBehavior1.*onMessage()* or WebSocketResource1.*onMessage()* where the application logic can react on it.
+The server can push plain text and binary data to the client, but it can also add components for re-render, prepend/append JavaScript as it can do with 
+<<_working_with_ajax,Ajax>>.
+

http://git-wip-us.apache.org/repos/asf/wicket/blob/7eba9998/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc
----------------------------------------------------------------------
diff --git a/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc
new file mode 100644
index 0000000..151f729
--- /dev/null
+++ b/wicket-user-guide/src/main/asciidoc/nativewebsockets/nativewebsockets_2.adoc
@@ -0,0 +1,135 @@
+
+* *Classpath dependency*
+
+Depending on the web container that is used the application has to add a dependency to either:
+
+- for Jetty 9.0.x
+[source,java]
+----
+<dependency>
+  <groupId>org.apache.wicket</groupId>
+  <artifactId>wicket-native-websocket-jetty9</artifactId>
+  <version>...</version>
+</dependency>
+----
+
+- for Jetty 7.x and 8.x
+[source,java]
+----
+<dependency>
+  <groupId>org.apache.wicket</groupId>
+  <artifactId>wicket-native-websocket-jetty</artifactId>
+  <version>...</version>
+</dependency>
+----
+
+- for Tomcat 7.0.27+ (the old, non-JSR356 implementation)
+[source,java]
+----
+<dependency>
+  <groupId>org.apache.wicket</groupId>
+  <artifactId>wicket-native-websocket-tomcat</artifactId>
+  <version>...</version>
+</dependency>
+----
+
+- for JSR356 complaint implementations (at the moment are supported: Tomcat 8.0+, Tomcat 7.0.47+, Jetty 9.1.0+ and JBoss Wildfly 8.0.0+)
+[source,java]
+----
+<dependency>
+  <groupId>org.apache.wicket</groupId>
+  <artifactId>wicket-native-websocket-javax</artifactId>
+  <version>...</version>
+</dependency>
+----
+
+NOTE: All web containers providing JSR356 implementation are built with Java 7. This is the reason why _wicket-native-websocket-javax_ module is available only with Wicket 7.x. If your application runs with JRE 7.x then you can
+use _wicket-native-websocket-javax_ together with the latest version of Wicket 6.x. Beware that the API/implementation of _wicket-native-websocket-javax_ may change before Wicket 7.0.0 is released!
+
+NOTE: The examples above show snippets for Maven's pom.xml but the application can use any other dependency management tool like http://www.gradle.org/[Gradle]
+
+* *web.xml*
+
+In _WEB-INF/web.xml_ replace the usage of *WicketFilter* with any of the following depending on the web container that is used:
+
+For Jetty 9.0.x:
+[source,java]
+----
+<filter-class>org.apache.wicket.protocol.ws.jetty9.Jetty9WebSocketFilter</filter-class>
+----
+
+For Jetty 7.5+ and 8.x:
+[source,java]
+----
+<filter-class>org.apache.wicket.protocol.ws.jetty7.Jetty7WebSocketFilter</filter-class>
+----
+
+For Tomcat 7.0.27+ (old implementation):
+[source,java]
+----
+<filter-class>org.apache.wicket.protocol.ws.tomcat7.Tomcat7WebSocketFilter</filter-class>
+----
+
+For JSR356 complaint web containers (at the moment: Tomcat 7.0.47+, Tomcat 8.x and Jetty 9.1.x):
+[source,java]
+----
+<filter-class>org.apache.wicket.protocol.ws.javax.JavaxWebSocketFilter</filter-class>
+----
+
+
+
+* *WebSocketBehavior*
+
+_org.apache.wicket.protocol.ws.api.WebSocketBehavior_ is similar to Wicket Ajax behaviors that you may have used.
+Add WebSocketBehavior to the page (or to any component in the page) that will use web socket communication:
+
+[source,java]
+----
+public class MyPage extends WebPage {
+ 
+  public MyPage()
+  {
+    add(new WebSocketBehavior() {
+      @Override
+      protected void onMessage(WebSocketRequestHandler handler, TextMessage message)
+      {
+        String msg = message.getText();
+        // do something with msg
+      }
+    });
+  }
+}
+----
+
+Use _message.getText()_ to read the message sent by the client and use _handler.push(String)_ to push a text message to the connected client. Additionally you can use _handler.add(Component...)_ to add Wicket components for re-render, _handler1.prependJavaScript(CharSequence)_ and _handler1.appendJavaScript(CharSequence)_ as you do with _AjaxRequestTarget_.
+
+* *WebSocketResource*
+
+Wicket allows one thread at a time to use a page instance to simplify the usage of the pages in multithreaded enviroment. When a WebSocket message is sent to a page Wicket needs to acquire the lock to that page to be able to pass the _IWebSocketMessage_ to the _WebSocketBehavior_. This may be problematic when the application needs to send many messages from the client to the server.
+For this reason Wicket provides _WebSocketResource_ - an IResource implemetation that provides the same APIs as _WebSocketBehavior_. The benefit is that there is no need of synchronization as with the pages and the drawback is that _WebSocketRequesthandler1.add(Component...)_ method cannot be used because there is no access to the components in an _IResource_.
+
+To register such WebSocket resource add such line to _YourApplication1.init()_ method:
+[source,java]
+----
+getSharedResources().add("someName", new MyWebSocketResource());
+----
+
+and 
+[source,java]
+----
+  page.add(new BaseWebSocketBehavior("someName"));
+----
+to any page. This will prepare the JavaScript connection for you.
+
+* *WebSocket connection registry*
+
+To push data to one or more clients the application can use the _IWebSocketConnectionRegistry_ to find all registered connections and send data to all/any of them:
+
+[source,java]
+----
+Application application = Application.get(applicationName);
+WebSocketSettings webSocketSettings = WebSocketSettings.Holder.get(application);
+IWebSocketConnectionRegistry webSocketConnectionRegistry = webSocketSettings.getConnectionRegistry();
+IWebSocketConnection connection = webSocketConnectionRegistry.getConnection(application, sessionId, key);
+----
+


Mime
View raw message