diff options
Diffstat (limited to 'documentation/datamodel')
| -rw-r--r-- | documentation/datamodel/datamodel-fields.asciidoc | 26 | ||||
| -rw-r--r-- | documentation/datamodel/datamodel-overview.asciidoc | 37 |
2 files changed, 27 insertions, 36 deletions
diff --git a/documentation/datamodel/datamodel-fields.asciidoc b/documentation/datamodel/datamodel-fields.asciidoc index ac39c7fda0..655426d5f9 100644 --- a/documentation/datamodel/datamodel-fields.asciidoc +++ b/documentation/datamodel/datamodel-fields.asciidoc @@ -7,7 +7,7 @@ layout: page [[datamodel.fields]] = Editing Values in Fields -The [interfacename]#Field# interface is in a very central role for handling data in an application since different types of fields are the main user interface controls used for entering data into the application. +Input field components (implementing the `HasValue` interface) are in a very central role for handling data in an application since different types of fields are the main user interface controls used for displaying and editing data. While each field implementation has its own functionality, all fields also have some common core functionality. By using these common building blocks, the data binding part of the framework can help simplify the code we need to write for many common data entry cases. @@ -25,12 +25,12 @@ Button sayHelloButton = new Button("Say hello", clickEvent -> { }); ---- -Each field implementation has its own specific value type – the type of a [classname]#TextField# is [classname]#String#, the type of a [classname]#Slider# is [classname]#Double#, the type of a [classname]#DateField# is [classname]#LocalDate#, and so on. +Each field implementation has its own specific value type – for instance, the type of a `TextField` is `String`, the type of a `Slider` is `Double`, the type of a `DateField` is `LocalDate`, and so on. == Reacting to Value Changes When the value of a field changes, it fires a value change event. -By listening to the event, we can find out the new value of the field and whether the value was changed by the user through the user interface or by code through the [methodname]#setValue# method. +By listening to the event, we can find out the new value of the field and whether the value was changed by the user through the user interface or by code through the `setValue` method. [source,java] ---- @@ -44,25 +44,15 @@ nameField.addValueChangeListener(event -> { Notification.show(message); }); -Button button = new Button("Set name", event -> { +Button setButton = new Button("Set name", event -> { // Will show "Name is Zaphod as set from code" nameField.setValue("Zaphod"); }); ---- -If we only need to get the new value whenever it changes, we can use the [methodname]#onChange# method. -This kind of listener directly receives the new value, which makes it convenient if we want to directly pass on the value to some other part of the application. -It is often practical to use a method reference for defining where the new value should be delivered. +Fields can also be set in read-only mode, which means that the user is not able to directly edit the value through the user interface, but the value can still be changed through code. +This is useful for showing the user that the data is there, even though the user is currently not allowed to edit it. -[source,java] ----- -Person person = new Person("Douglas Adams", 49); +When editing multiple values from the same business object, you can use `Binder` to simplify how the values of all input fields in a form are handled. -TextField nameField = new TextField("Name"); -nameField.setValue(person.getName()); -nameField.onChange(person::setName); - -Button button = new Button("Show name", event -> { - Notification.show("Person name: " + person.getName()); -}) ----- +link:datamodel-forms.asciidoc[Binding Data to Forms] describes how this is done. diff --git a/documentation/datamodel/datamodel-overview.asciidoc b/documentation/datamodel/datamodel-overview.asciidoc index a98762fd23..7e9afeb3b6 100644 --- a/documentation/datamodel/datamodel-overview.asciidoc +++ b/documentation/datamodel/datamodel-overview.asciidoc @@ -7,25 +7,26 @@ layout: page [[datamodel.overview]] = Overview -//// -TODO - - * Item: typically a Java Bean, but can also be any other Java type - * Individual values in an item: callback or bean property name - * Collections of items: In-memory list or explicitly fetched on demand from a backend -//// - The Vaadin Data Model is one of the core concepts of the library. -To allow the view (user interface components) to access the data model of an application directly, we have introduced a standard data interface. +There is a standard data interface that all UI components use to access and modify the application's data. + +The most basic UI component for handling data is a field component that lets the user define a single value, for instance a text field for writing the name of a product or a dropdown menu for selecting which department an employee belongs to. +See link:datamodel-fields.asciidoc[Editing Values in Fields] to learn how these components can be used on their own. -The model allows binding user interface components directly to data that can be viewed and possibly also edited. +In most applications, there are business classes that represent real-world objects like a single employee or a product in an inventory. +The user interface is structured as a form that lets the user edit all the different properties of a single business object instance. +Vaadin Framework makes it easy to create forms for editing these sorts. +You have full control over how you configure and lay out the individual input fields making up a form, and then you can use `Binder` to hook up those fields to a business object instance. +link:datamodel-forms.asciidoc[Binding Data to Forms] shows how to bind data to fields. -Notice that the Data Model does not define data representation, but only how components access the data. -This leaves the representation fully to the implementation of the containers. -The representation can be almost anything, such as a plain old Java object (POJO) structure, a filesystem, or a database query. +There are UI components in the framework that lists multiple similar objects and lets the user view, select and in some cases even edit those objects. +A listing component can get its data from an in-memory collection or lazily fetch it from some backend. +In either case, there are options available for defining how the data is sorted and filtered before being displayed to the user. +Read more about how to provide lists of data to these components in link:datamodel-providers.asciidoc[Showing Many Items in a Listing]. +Using a listing component as an input field to select one or many of the listed items is described in link:datamodel-selection.asciidoc[Selecting items]. -Many data model implementations, such as data sources, are available as add-ons, either from the Vaadin Directory or from independent sources. -Installation of add-ons is described in -<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using -Vaadin Add-ons">>. -Notice that unlike with most regular add-on components, you do not need to compile a widget set for add-ons that include just data model implementations. +Vaadin Data Model topic references:: +* link:datamodel-fields.asciidoc[Editing Values in Fields] +* link:datamodel-forms.asciidoc[Binding Data to Forms] +* link:datamodel-providers.asciidoc[Showing Many Items in a Listing] +* link:datamodel-selection.asciidoc[Selecting items] |