You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@wicket.apache.org by mg...@apache.org on 2013/02/19 09:00:23 UTC
[3/10] git commit: models in progress
models in progress
Project: http://git-wip-us.apache.org/repos/asf/wicket/repo
Commit: http://git-wip-us.apache.org/repos/asf/wicket/commit/73cf82c7
Tree: http://git-wip-us.apache.org/repos/asf/wicket/tree/73cf82c7
Diff: http://git-wip-us.apache.org/repos/asf/wicket/diff/73cf82c7
Branch: refs/heads/reference-guide
Commit: 73cf82c7f992bbd0abd11c69400b253fd45fb42b
Parents: 0002f81
Author: Michael Mosmann <mi...@mosmann.de>
Authored: Fri Feb 8 17:22:59 2013 +0100
Committer: Michael Mosmann <mi...@mosmann.de>
Committed: Fri Feb 8 17:22:59 2013 +0100
----------------------------------------------------------------------
.../models/dynamic/CustomModelFormPage.html | 11 ++
.../models/dynamic/CustomModelFormPage.java | 35 ++++++
.../reference/models/dynamic/PersonBean.java | 18 +++
.../src/documentation/source/models.rst | 90 +++++++++++++++
4 files changed, 154 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/wicket/blob/73cf82c7/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.html
----------------------------------------------------------------------
diff --git a/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.html b/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.html
new file mode 100644
index 0000000..712591e
--- /dev/null
+++ b/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.html
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<html xmlns="http://www.w3.org/1999/xhtml" xmlns:wicket="http://wicket.apache.org">
+<head>
+ <title>Custom Model Form</title>
+</head>
+<body>
+ <form wicket:id="form">
+ <input wicket:id="personName"/>
+ </form>
+</body>
+</html>
http://git-wip-us.apache.org/repos/asf/wicket/blob/73cf82c7/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.java
----------------------------------------------------------------------
diff --git a/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.java b/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.java
new file mode 100644
index 0000000..6e951a8
--- /dev/null
+++ b/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.java
@@ -0,0 +1,35 @@
+package org.apache.wicket.reference.models.dynamic;
+
+import org.apache.wicket.markup.html.WebPage;
+import org.apache.wicket.markup.html.form.Form;
+import org.apache.wicket.markup.html.form.RequiredTextField;
+import org.apache.wicket.model.Model;
+
+public class CustomModelFormPage extends WebPage
+{
+ public CustomModelFormPage()
+ {
+ final PersonBean person = new PersonBean();
+
+ Form<Void> personForm = new Form<Void>("form");
+
+//#customModel
+personForm.add(new RequiredTextField<String>("personName", new Model<String>()
+{
+ @Override
+ public String getObject()
+ {
+ return person.getName();
+ }
+
+ @Override
+ public void setObject(String object)
+ {
+ person.setName(object);
+ }
+}));
+//#customModel
+
+ add(personForm);
+ }
+}
http://git-wip-us.apache.org/repos/asf/wicket/blob/73cf82c7/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/PersonBean.java
----------------------------------------------------------------------
diff --git a/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/PersonBean.java b/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/PersonBean.java
new file mode 100644
index 0000000..7331789
--- /dev/null
+++ b/wicket-reference-guide/models/src/main/java/org/apache/wicket/reference/models/dynamic/PersonBean.java
@@ -0,0 +1,18 @@
+package org.apache.wicket.reference.models.dynamic;
+
+import java.io.Serializable;
+
+public class PersonBean implements Serializable
+{
+ String name;
+
+ public String getName()
+ {
+ return name;
+ }
+
+ public void setName(String name)
+ {
+ this.name = name;
+ }
+}
http://git-wip-us.apache.org/repos/asf/wicket/blob/73cf82c7/wicket-reference-guide/src/documentation/source/models.rst
----------------------------------------------------------------------
diff --git a/wicket-reference-guide/src/documentation/source/models.rst b/wicket-reference-guide/src/documentation/source/models.rst
index 5ed2adc..e5d5be4 100644
--- a/wicket-reference-guide/src/documentation/source/models.rst
+++ b/wicket-reference-guide/src/documentation/source/models.rst
@@ -3,6 +3,96 @@ Model
.. toctree::
:maxdepth: 3
+In Wicket, a model holds a value for a component to display and/or edit. How exactly this value is held is determined by a given model's implementation of the :ref:`IModel <models--imodel-label>` interface. The IModel interface decouples a component from the model object which forms its value. This in turn decouples the whole Wicket framework from any and all details of model storage, such as the details of a given persistence technology. As far as Wicket itself is concerned, a model is anything that implements the IModel interface, no matter how it might do that. Although there are some refinements described below, conceptually, IModel looks like this:
+
+.. _models--imodel-label:
+
+.. todo:: replace with real code
+
+IModel.java::
+
+ public interface IModel<T> ...
+ {
+ T getObject();
+
+ void setObject(final T object);
+ }
+
+The IModel interface defines a simple contract for getting and setting a value. The nature of the Object retrieved or set will depend on the component referencing the model. For a Label component, the value must be something which can be converted to a String (see :doc:`converter`) which will be displayed when the label is rendered. For a ListView, it must be a java.util.List containing the values to be displayed as a list.
+
+Different frameworks implement the model concept differently. Swing has a number of component-specific model interfaces. Struts requires that the model be a Java Bean and there is no explicit model interface. The IModel interface in Wicket allows models to be generic (as in Struts) but it can do things that would not be possible if components accessed their model directly (as in Swing). For example, Wicket applications can use or provide IModel implementations that read a model value from a resource file or retrieve a model value from a database only when needed.
+
+The use of a single model interface (as compared to having multiple interfaces, or having no model interface at all) has a number of advantages:
+
+* Wicket provides IModel implementations you can use with any component. These models can do things such as retrieve the value from a resource file, or read and write the value from a Java Bean property.
+* Wicket also provides IModel implementations that defer retrieving the value until it is actually needed, and remove it from the servlet Session when the request is complete. This reduces session memory consumption and is particularly useful with large values such as lists.
+* Unlike Swing, you do not have to implement an extra interface or helper class for each different component. Especially for the most often used components such as Labels and TextFields you can easily bind to a bean property.
+* In many cases you can provide the required value directly to the component and it will wrap a default model implementation around it for you.
+* And while you do not have to use beans as your models as you must with Struts, you may still easily use beans if you wish. Wicket provides the appropriate model implementations.
+
+
+Simple Models
+-------------
+
+The HelloWorld example program demonstrates the simplest model type in Wicket:
+
+.. includecode:: ../../../helloworld/src/main/java/org/apache/wicket/reference/helloworld/HelloWorld.java#docu
+
+The constructor for this page constructs a Label component. The first parameter to the Label component's constructor is the Wicket id, which associates the Label with a tag in the HelloWorld.html markup file:
+
+.. includecode:: ../../../helloworld/src/main/java/org/apache/wicket/reference/helloworld/HelloWorld.html
+
+The second parameter to the Label component's constructor is the model data for the Label, providing content that replaces any text inside the <span> tag to which the Label is associated. The model data passed to the Label constructor above is apparently a String. Internally Label creates a Model for the String. :ref:`Model<_models--model-label>` is a simple default implementation of IModel.
+
+
+.. todo:: replace with real code
+
+.. _models--model-label:
+
+Thus instead we could have created our label this way::
+
+ add(new Label("message", new Model<String>("Hello World!")));
+
+or::
+
+ add(new Label("message", Model.of("Hello World!")));
+
+
+The Label constructor that takes a String is simply a convenience.
+
+
+
+Dynamic Models
+--------------
+
+The data we gave to the model in the previous example, the string "Hello World", is constant. No matter how many times Wicket asks for the model data, it will get the same thing. Now consider a slightly more complex example:
+
+.. todo:: replace with real code
+
+ Label name = new Label ("name", Model.of(person.getName()));
+
+The model data is still a String, the value of person.getName() is set at the time the model is created. Recall that Java strings are immutable: this string will never change. Even if person.getName() would later return a different value, the model data is unchanged. So the page will still display the old value to the user even if it is reloaded. Models like this, whose values never change, are known as static models.
+
+In many cases the underlying data can change, and you want the user to see those changes. For example, the user might use a form to change a person's name. Models which can automatically reflect change are known as dynamic models. While the :ref:`Model<_models--model-label>` class is static, most of the other core Wicket model classes are dynamic.
+
+
+.. todo:: replace with real code
+
+It's instructive to see how to make a dynamic model by subclassing Model.
+
+.. includecode:: ../../../models/src/main/java/org/apache/wicket/reference/models/dynamic/CustomModelFormPage.java#customModel
+
+It would be inconvenient to have to do this for every component that needs a dynamic model. Instead, you can use the PropertyModel class or one of the other classes described below.
+
+
+
+Ignore Following Stuff
+----------------------
+
+
+
+
+
Models are a important part of any wicket application. Despite it's simple interface its a complex topic. But let's start with some easy examples.
A very simple Model