Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 158 insertions, 0 deletions

diff --git a/documentation/application/application-overview.asciidoc b/documentation/application/application-overview.asciidoc
new file mode 100644
index 0000000000..b70df520f9
--- /dev/null
+++ b/documentation/application/application-overview.asciidoc
@@ -0,0 +1,158 @@
+---
+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[]
+
+<<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:: Field components are essentially views to data, represented in the __Vaadin Data
+Model__. Using the data model, the components can get their values from and
+update user input to the data model directly, without the need for any control
+code. A field component is always bound to a __property__ and a group of fields
+to an __item__ that holds the properties. Items can be collected in a
+__container__, which can act as a data source for some components such as tables
+or lists. While all the components have a default data model, they can be bound
+to a user-defined data source. For example, you can bind a [classname]#Table#
+component to an SQL query response. For a complete overview of data binding in
+Vaadin, please refer to
+<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
+Components to Data">>.
+
+
+
+
+