From 2af72ba9636bec70046394c41744f89ce4572e35 Mon Sep 17 00:00:00 2001
From: Ilia Motornyi <elmot@vaadin.com>
Date: Thu, 3 Dec 2015 14:59:05 +0000
Subject: Revert "Merge branch 'documentation'"

This reverts commit f6874bde3d945c8b2d1b5c17ab50e2d0f1f8ff00.

Change-Id: I67ee1c30ba3e3bcc3c43a1dd2e73a822791514bf
---
 .../datamodel/datamodel-itembinding.asciidoc       | 377 ---------------------
 1 file changed, 377 deletions(-)
 delete mode 100644 documentation/datamodel/datamodel-itembinding.asciidoc

(limited to 'documentation/datamodel/datamodel-itembinding.asciidoc')

diff --git a/documentation/datamodel/datamodel-itembinding.asciidoc b/documentation/datamodel/datamodel-itembinding.asciidoc
deleted file mode 100644
index fd21b72267..0000000000
--- a/documentation/datamodel/datamodel-itembinding.asciidoc
+++ /dev/null
@@ -1,377 +0,0 @@
----
-title: Creating Forms by Binding Fields to Items
-order: 4
-layout: page
----
-
-[[datamodel.itembinding]]
-= Creating Forms by Binding Fields to Items
-
-Most applications in existence have forms of some sort. Forms contain fields,
-which you want to bind to a data source, an item in the Vaadin data model.
-[classname]#FieldGroup# provides an easy way to bind fields to the properties of
-an item. You can use it by first creating a layout with some fields, and then
-call it to bind the fields to the data source. You can also let the
-[classname]#FieldGroup# create the fields using a field factory. It can also
-handle commits. Notice that [classname]#FieldGroup# is not a user interface
-component, so you can not add it to a layout.
-
-[[datamodel.itembinding.simple]]
-== Simple Binding
-
-Let us start with a data model that has an item with a couple of properties. The
-item could be any item type, as described earlier.
-
-
-----
-// Have an item
-PropertysetItem item = new PropertysetItem();
-item.addItemProperty("name", new ObjectProperty<String>("Zaphod"));
-item.addItemProperty("age", new ObjectProperty<Integer>(42));
-----
-
-Next, you would design a form for editing the data. The [classname]#FormLayout#
-(
-<<dummy/../../../framework/layout/layout-formlayout#layout.formlayout,"FormLayout">>
-is ideal for forms, but you could use any other layout as well.
-
-
-----
-// Have some layout and create the fields
-FormLayout form = new FormLayout();
-
-TextField nameField = new TextField("Name");
-form.addComponent(nameField);
-
-TextField ageField = new TextField("Age");
-form.addComponent(ageField);
-----
-
-Then, we can bind the fields to the data as follows:
-
-
-----
-// Now create the binder and bind the fields
-FieldGroup binder = new FieldGroup(item);
-binder.bind(nameField, "name");
-binder.bind(ageField, "age");
-----
-
-The above way of binding is not different from simply calling
-[methodname]#setPropertyDataSource()# for the fields. It does, however, register
-the fields in the field group, which for example enables buffering or validation
-of the fields using the field group, as described in
-<<datamodel.itembinding.buffering>>.
-
-Next, we consider more practical uses for a [classname]#FieldGroup#.
-
-
-[[datamodel.itembinding.fieldfactory]]
-== Using a [interfacename]#FieldFactory# to Build and Bind Fields
-
-Using the [methodname]#buildAndBind()# methods, [classname]#FieldGroup# can
-create fields for you using a [interfacename]#FieldGroupFieldFactory#, but you
-still have to add them to the correct position in your layout.
-
-
-----
-// Have some layout
-FormLayout form = new FormLayout();
-        
-// Now create a binder that can also create the fields
-// using the default field factory
-FieldGroup binder = new FieldGroup(item);
-form.addComponent(binder.buildAndBind("Name", "name"));
-form.addComponent(binder.buildAndBind("Age", "age"));
-----
-
-
-[[datamodel.itembinding.formclass]]
-== Binding Member Fields
-
-The [methodname]#bindMemberFields()# method in [classname]#FieldGroup# uses
-reflection to bind the properties of an item to field components that are member
-variables of a class. Hence, if you implement a form as a class with the fields
-stored as member variables, you can use this method to bind them super-easy.
-
-The item properties are mapped to the members by the property ID and the name of
-the member variable. If you want to map a property with a different ID to a
-member, you can use the [literal]#++@PropertyId++# annotation for the member,
-with the property ID as the parameter.
-
-For example:
-
-
-----
-// Have an item
-PropertysetItem item = new PropertysetItem();
-item.addItemProperty("name", new ObjectProperty<String>("Zaphod"));
-item.addItemProperty("age", new ObjectProperty<Integer>(42));
-
-// Define a form as a class that extends some layout
-class MyForm extends FormLayout {
-    // Member that will bind to the "name" property
-    TextField name = new TextField("Name");
-    
-    // Member that will bind to the "age" property 
-    @PropertyId("age")
-    TextField ageField = new TextField("Age");
-    
-    public MyForm() {
-        // Customize the layout a bit
-        setSpacing(true);
-        
-        // Add the fields
-        addComponent(name);
-        addComponent(ageField);
-    }
-}
-        
-// Create one
-MyForm form = new MyForm();
-        
-// Now create a binder that can also creates the fields
-// using the default field factory
-FieldGroup binder = new FieldGroup(item);
-binder.bindMemberFields(form);
-
-// And the form can be used in an higher-level layout
-layout.addComponent(form);
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#datamodel.itembinding.formclass.extended[on-line example, window="_blank"].
-
-[[datamodel.itembinding.formclass.customcomponent]]
-=== Encapsulating in [classname]#CustomComponent#
-
-Using a [classname]#CustomComponent# can be better for hiding the implementation
-details than extending a layout. Also, the use of the [classname]#FieldGroup#
-can be encapsulated in the form class.
-
-Consider the following as an alternative for the form implementation presented
-earlier:
-
-
-----
-// A form component that allows editing an item
-class MyForm extends CustomComponent {
-    // Member that will bind to the "name" property
-    TextField name = new TextField("Name");
-    
-    // Member that will bind to the "age" property 
-    @PropertyId("age")
-    TextField ageField = new TextField("Age");
-    
-    public MyForm(Item item) {
-        FormLayout layout = new FormLayout();
-        layout.addComponent(name);
-        layout.addComponent(ageField);
-        
-        // Now use a binder to bind the members
-        FieldGroup binder = new FieldGroup(item);
-        binder.bindMemberFields(this);
-
-        setCompositionRoot(layout);
-    }
-}
-        
-// And the form can be used as a component
-layout.addComponent(new MyForm(item));
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#datamodel.itembinding.formclass.customcomponent[on-line example, window="_blank"].
-
-
-
-[[datamodel.itembinding.buffering]]
-== Buffering Forms
-
-Just like for individual fields, as described in
-<<dummy/../../../framework/components/components-fields#components.fields.buffering,"Field
-Buffering">>, a [classname]#FieldGroup# can handle buffering the form content so
-that it is written to the item data source only when [methodname]#commit()# is
-called for the group. It runs validation for all fields in the group and writes
-their values to the item data source only if all fields pass the validation.
-Edits can be discarded, so that the field values are reloaded from the data
-source, by calling [methodname]#discard()#. Buffering is enabled by default, but
-can be disabled by calling [methodname]#setBuffered(false)# for the
-[classname]#FieldGroup#.
-
-
-----
-// Have an item of some sort
-final PropertysetItem item = new PropertysetItem();
-item.addItemProperty("name", new ObjectProperty<String>("Q"));
-item.addItemProperty("age",  new ObjectProperty<Integer>(42));
-
-// Have some layout and create the fields
-Panel form = new Panel("Buffered Form");
-form.setContent(new FormLayout());
-
-// Build and bind the fields using the default field factory
-final FieldGroup binder = new FieldGroup(item);
-form.addComponent(binder.buildAndBind("Name", "name"));
-form.addComponent(binder.buildAndBind("Age",  "age"));
-
-// Enable buffering (actually enabled by default)
-binder.setBuffered(true);
-        
-// A button to commit the buffer
-form.addComponent(new Button("OK", new ClickListener() {
-    @Override
-    public void buttonClick(ClickEvent event) {
-        try {
-            binder.commit();
-            Notification.show("Thanks!");
-        } catch (CommitException e) {
-            Notification.show("You fail!");
-        }
-    }
-}));
-
-// A button to discard the buffer
-form.addComponent(new Button("Discard", new ClickListener() {
-    @Override
-    public void buttonClick(ClickEvent event) {
-        binder.discard();
-        Notification.show("Discarded!");
-    }
-}));
-----
-See the http://demo.vaadin.com/book-examples-vaadin7/book#datamodel.itembinding.formclass.customcomponent[on-line example, window="_blank"].
-
-
-[[datamodel.itembinding.beans]]
-== Binding Fields to a Bean
-
-The [classname]#BeanFieldGroup# makes it easier to bind fields to a bean. It
-also handles binding to nested beans properties. The build a field bound to a
-nested bean property, identify the property with dot notation. For example, if a
-[classname]#Person# bean has a [literal]#++address++# property with an
-[classname]#Address# type, which in turn has a [literal]#++street++# property,
-you could build a field bound to the property with
-[methodname]#buildAndBind("Street", "address.street")#.
-
-The input to fields bound to a bean can be validated using the Java Bean
-Validation API, as described in <<datamodel.itembinding.beanvalidation>>. The
-[classname]#BeanFieldGroup# automatically adds a [classname]#BeanValidator# to
-every field if a bean validation implementation is included in the classpath.
-
-
-[[datamodel.itembinding.beanvalidation]]
-== Bean Validation
-
-Vaadin allows using the Java Bean Validation API 1.0 (JSR-303) for validating
-input from fields bound to bean properties before the values are committed to
-the bean. The validation is done based on annotations on the bean properties,
-which are used for creating the actual validators automatically. See
-<<dummy/../../../framework/components/components-fields#components.fields.validation,"Field
-Validation">> for general information about validation.
-
-Using bean validation requires an implementation of the Bean Validation API,
-such as Hibernate Validator ( [filename]#hibernate-validator-4.2.0.Final.jar# or
-later) or Apache Bean Validation. The implementation JAR must be included in the
-project classpath when using the bean validation, or otherwise an internal error
-is thrown.
-
-Bean validation is especially useful when persisting entity beans with the
-Vaadin JPAContainer, described in
-<<dummy/../../../framework/jpacontainer/jpacontainer-overview.asciidoc#jpacontainer.overview,"Vaadin
-JPAContainer">>.
-
-[[datamodel.itembinding.beanvalidation.annotations]]
-=== Annotations
-
-The validation constraints are defined as annotations. For example, consider the
-following bean:
-
-
-----
-// Here is a bean
-public class Person implements Serializable {
-    @NotNull
-    @javax.validation.constraints.Size(min=2, max=10)
-    String name;
-    
-    @Min(1)
-    @Max(130)
-    int age;
-    
-    // ... setters and getters ...
-}
-----
-
-For a complete list of allowed constraints for different data types, please see
-the link:http://docs.oracle.com/javaee/6/tutorial/doc/gircz.html[Bean Validation
-API documentation].
-
-
-[[datamodel.itembinding.beanvalidation.validating]]
-=== Validating the Beans
-
-Validating a bean is done with a [classname]#BeanValidator#, which you
-initialize with the name of the bean property it should validate and add it the
-the editor field.
-
-In the following example, we validate a single unbuffered field:
-
-
-----
-Person bean = new Person("Mung bean", 100);
-BeanItem<Person> item = new BeanItem<Person> (bean);
-    
-// Create an editor bound to a bean field
-TextField firstName = new TextField("First Name",
-        item.getItemProperty("name"));
-    
-// Add the bean validator
-firstName.addValidator(new BeanValidator(Person.class, "name"));
-    
-firstName.setImmediate(true);
-layout.addComponent(firstName);
-----
-
-In this case, the validation is done immediately after focus leaves the field.
-You could do the same for the other field as well.
-
-Bean validators are automatically created when using a
-[classname]#BeanFieldGroup#.
-
-
-----
-// Have a bean
-Person bean = new Person("Mung bean", 100);
-        
-// Form for editing the bean
-final BeanFieldGroup<Person> binder =
-        new BeanFieldGroup<Person>(Person.class);
-binder.setItemDataSource(bean);
-layout.addComponent(binder.buildAndBind("Name", "name"));
-layout.addComponent(binder.buildAndBind("Age", "age"));
-
-// Buffer the form content
-binder.setBuffered(true);
-layout.addComponent(new Button("OK", new ClickListener() {
-    @Override
-    public void buttonClick(ClickEvent event) {
-        try {
-            binder.commit();
-        } catch (CommitException e) {
-        }
-    }
-}));
-----
-
-
-[[datamodel.itembinding.beanvalidation.locale]]
-=== Locale Setting for Bean Validation
-
-The validation error messages are defined in the bean validation implementation,
-in a [filename]#ValidationMessages.properties# file. The message is shown in the
-language specified with the locale setting for the form. The default language is
-English, but for example Hibernate Validator contains translations of the
-messages for a number of languages. If other languages are needed, you need to
-provide a translation of the properties file.
-
-
-
-
-
-- 
cgit v1.2.3

