summaryrefslogtreecommitdiffstats
path: root/documentation/application/application-overview.asciidoc
blob: 7649bc2d934b6485239db7a7ed3e22fb9e1bf9c9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
title: Overview
order: 1
layout: page
---

[[application.overview]]
= Overview

A server-side Vaadin application runs as a Java Servlet in a servlet container.
The Java Servlet API is, however, hidden behind the framework. The user
interface of the application is implemented as a __UI__ class, which needs to
create and manage the user interface components that make up the user interface.
User input is handled with event listeners, although it is also possible to bind
the user interface components directly to data. The visual style of the
application is defined in themes as CSS or Sass. Icons, other images, and
downloadable files are handled as __resources__, which can be external or served
by the application server or the application itself.

[[figure.application.architecture]]
.Server-Side Application Architecture
image::img/application-architecture-hi.png[width=75%, scaledwidth=90%]

<<figure.application.architecture>> illustrates the basic architecture of an
application made with the Vaadin Framework, with all the major elements, which
are introduced below and discussed in detail in this chapter.

First of all, a Vaadin application must have one or more UI classes that extend
the abstract [classname]#com.vaadin.ui.UI# class and implement the
[methodname]#init()# method. A custom theme can be defined as an annotation for
the UI.


[source, java]
----
@Theme("hellotheme")
public class HelloWorld extends UI {
    protected void init(VaadinRequest request) {
        ... initialization code goes here ...
    }
}
----

A UI is a viewport to a Vaadin application running in a web page. A web page can
actually have multiple such UIs within it. Such situation is typical especially
with portlets in a portal. An application can run in multiple browser windows,
each having a distinct [classname]#UI# instance. The UIs of an application can
be the same UI class or different.

Vaadin framework handles servlet requests internally and associates the requests
with user sessions and a UI state. Because of this, you can develop Vaadin
applications much like you would develop desktop applications.

The most important task in the initialization is the creation of the initial
user interface. This, and the deployment of a UI as a Java Servlet in the
Servlet container, as described in
<<dummy/../../../framework/application/application-environment#application.environment,"Deploying
an Application">>, are the minimal requirements for an application.

Below is a short overview of the other basic elements of an application besides
UI:

UI:: A __UI__ represents an HTML fragment in which a Vaadin application runs in a web
page. It typically fills the entire page, but can also be just a part of a page.
You normally develop a Vaadin application by extending the [classname]#UI# class
and adding content to it. A UI is essentially a viewport connected to a user
session of an application, and you can have many such views, especially in a
multi-window application. Normally, when the user opens a new page with the URL
of the Vaadin UI, a new [classname]#UI# (and the associated [classname]#Page#
object) is automatically created for it. All of them share the same user
session.

+
The current UI object can be accessed globally with
[methodname]#UI.getCurrent()#. The static method returns the thread-local UI
instance for the currently processed request
ifdef::web[]
 (see
<<dummy/../../../framework/advanced/advanced-global#advanced.global.threadlocal,"ThreadLocal
Pattern">>)
endif::web[]
.

Page:: A [classname]#UI# is associated with a [classname]#Page# object that represents
the web page as well as the browser window in which the UI runs.

+
The [classname]#Page# object for the currently processed request can be accessed
globally from a Vaadin application with [methodname]#Page.getCurrent()#. This is
equivalent to calling [methodname]#UI.getCurrent().getPage()#.

Vaadin Session:: A [classname]#VaadinSession# object represents a user session with one or more
UIs open in the application. A session starts when a user first opens a UI of a
Vaadin application, and closes when the session expires in the server or when it
is closed explicitly.

User Interface Components:: The user interface consists of components that are created by the application.
They are laid out hierarchically using special __layout components__, with a
content root layout at the top of the hierarchy. User interaction with the
components causes __events__ related to the component, which the application can
handle. __Field components__ are intended for inputting values and can be
directly bound to data using the Vaadin Data Model. You can make your own user
interface components through either inheritance or composition. For a thorough
reference of user interface components, see
<<dummy/../../../framework/components/components-overview.asciidoc#components.overview,"User
Interface Components">>, for layout components, see
<<dummy/../../../framework/layout/layout-overview.asciidoc#layout.overview,"Managing
Layout">>, and for compositing components, see
<<dummy/../../../framework/components/components-customcomponent#components.customcomponent,"Composition
with CustomComponent">>.

Events and Listeners:: Vaadin follows an event-driven programming paradigm, in which events, and
listeners that handle the events, are the basis of handling user interaction in
an application (although also server push is possible as described in
<<dummy/../../../framework/advanced/advanced-push#advanced.push,"Server
Push">>).
<<dummy/../../../framework/architecture/architecture-events#architecture.events,"Events
and Listeners">> gave an introduction to events and listeners from an
architectural point-of-view, while
<<dummy/../../../framework/application/application-events#application.events,"Handling
Events with Listeners">> later in this chapter takes a more practical view.

Resources:: A user interface can display images or have links to web pages or downloadable
documents. These are handled as __resources__, which can be external or provided
by the web server or the application itself.
<<dummy/../../../framework/application/application-resources#application.resources,"Images
and Other Resources">> gives a practical overview of the different types of
resources.

Themes:: The presentation and logic of the user interface are separated. While the UI
logic is handled as Java code, the presentation is defined in __themes__ as CSS
or SCSS. Vaadin includes some built-in themes. User-defined themes can, in
addition to style sheets, include HTML templates that define custom layouts and
other theme resources, such as images. Themes are discussed in detail in
<<dummy/../../../framework/themes/themes-overview.asciidoc#themes.overview,"Themes">>,
custom layouts in
<<dummy/../../../framework/layout/layout-customlayout#layout.customlayout,"Custom
Layouts">>, and theme resources in
<<dummy/../../../framework/application/application-resources#application.resources.theme,"Theme
Resources">>.

Data Binding:: With data binding, any Vaadin field component can be bound to the properties
of business objects such as JavaBeans and grouped together as forms. The components
can get their values from and update user input to the data model directly, without
the need for any control code. Similarly, any select component can be bound to a
__data source__, fetching its items from a Java Collection or a backend such as an SQL database.
For a complete overview of data binding in Vaadin, please refer to
<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
Components to Data">>.