Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 258 insertions, 0 deletions

diff --git a/documentation/application/application-architecture.asciidoc b/documentation/application/application-architecture.asciidoc
new file mode 100644
index 0000000000..77c1756594
--- /dev/null
+++ b/documentation/application/application-architecture.asciidoc
@@ -0,0 +1,258 @@
+---
+title: Building the UI
+order: 2
+layout: page
+---
+
+[[application.architecture]]
+= Building the UI
+
+Vaadin user interfaces are built hierarchically from components, so that the
+leaf components are contained within layout components and other component
+containers. Building the hierarchy starts from the top (or bottom - whichever
+way you like to think about it), from the [classname]#UI# class of the
+application. You normally set a layout component as the content of the UI and
+fill it with other components.
+
+
+[source, java]
+----
+public class MyHierarchicalUI extends UI {
+    @Override
+    protected void init(VaadinRequest request) {
+        // The root of the component hierarchy
+        VerticalLayout content = new VerticalLayout();
+        content.setSizeFull(); // Use entire window
+        setContent(content);   // Attach to the UI
+        
+        // Add some component
+        content.addComponent(new Label("Hello!"));
+        
+        // Layout inside layout
+        HorizontalLayout hor = new HorizontalLayout();
+        hor.setSizeFull(); // Use all available space
+
+        // Couple of horizontally laid out components
+        Tree tree = new Tree("My Tree",
+                TreeExample.createTreeContent());
+        hor.addComponent(tree);
+
+        Table table = new Table("My Table",
+                TableExample.generateContent());
+        table.setSizeFull();
+        hor.addComponent(table);
+        hor.setExpandRatio(table, 1); // Expand to fill
+
+        content.addComponent(hor);
+        content.setExpandRatio(hor, 1); // Expand to fill
+    }
+}
+----
+
+The component hierarchy could be illustrated with a tree as follows:
+
+
+----
+UI
+ `-- VerticalLayout
+   |-- Label
+   `-- HorizontalLayout
+     |-- Tree
+     `-- Table
+----
+
+The result is shown in <<figure.application.architecture.example>>.
+
+[[figure.application.architecture.example]]
+.Simple Hierarchical UI
+image::img/ui-architecture-hierarchical.png[]
+
+Instead of building the layout in Java, you can also use a declarative design,
+as described later in
+<<dummy/../../../framework/application/application-declarative#application.declarative,"Designing
+UIs Declaratively">>. The examples given for the declarative layouts give
+exactly the same UI layout as built from the components above.
+
+The built-in components are described in
+<<dummy/../../../framework/components/components-overview.asciidoc#components.overview,"User
+Interface Components">> and the layout components in
+<<dummy/../../../framework/layout/layout-overview.asciidoc#layout.overview,"Managing
+Layout">>.
+
+The example application described above just is, it does not do anything. User
+interaction is handled with event listeners, as described a bit later in
+<<dummy/../../../framework/application/application-events#application.events,"Handling
+Events with Listeners">>.
+
+[[application.architecture.architecture]]
+== Application Architecture
+
+Once your application grows beyond a dozen or so lines, which is usually quite
+soon, you need to start considering the application architecture more closely.
+You are free to use any object-oriented techniques available in Java to organize
+your code in methods, classes, packages, and libraries. An architecture defines
+how these modules communicate together and what sort of dependencies they have
+between them. It also defines the scope of the application. The scope of this
+book, however, only gives a possibility to mention some of the most common
+architectural patterns in Vaadin applications.
+
+The subsequent sections describe some basic application patterns. For more
+information about common architectures, see
+<<dummy/../../../framework/advanced/advanced-architecture#advanced.architecture,"Advanced
+Application Architectures">>, which discusses layered architectures, the
+Model-View-Presenter (MVP) pattern, and so forth.
+
+ifdef::web[]
+The
+<<dummy/../../../framework/advanced/advanced-global#advanced.global,"Accessing
+Session-Global Data">> discusses the problem of passing essentially global
+references around, a common problem which is also visited in
+<<application.architecture.accessing>>.
+endif::web[]
+
+
+[[application.architecture.composition]]
+== Compositing Components
+
+User interfaces typically contain many user interface components in a layout
+hierarchy. Vaadin provides many layout components for laying contained
+components vertically, horizontally, in a grid, and in many other ways. You can
+extend layout components to create composite components.
+
+
+[source, java]
+----
+class MyView extends VerticalLayout {
+    TextField entry   = new TextField("Enter this");
+    Label     display = new Label("See this");
+    Button    click   = new Button("Click This");
+
+    public MyView() {
+        addComponent(entry);
+        addComponent(display);
+        addComponent(click);
+        
+        // Configure it a bit
+        setSizeFull();
+        addStyleName("myview");
+    }
+}
+
+// Use it
+Layout myview = new MyView();
+----
+
+This composition pattern is especially supported for creating forms, as
+described in
+<<dummy/../../../framework/datamodel/datamodel-itembinding#datamodel.itembinding.formclass,"Binding
+Member Fields">>.
+
+While extending layouts is an easy way to make component composition, it is a
+good practice to encapsulate implementation details, such as the exact layout
+component used. Otherwise, the users of such a composite could begin to rely on
+such implementation details, which would make changes harder. For this purpose,
+Vaadin has a special [classname]#CustomComponent# wrapper, which hides the
+content representation.
+
+
+[source, java]
+----
+class MyView extends CustomComponent {
+    TextField entry   = new TextField("Enter this");
+    Label     display = new Label("See this");
+    Button    click   = new Button("Click This");
+
+    public MyView() {
+        Layout layout = new VerticalLayout();
+        
+        layout.addComponent(entry);
+        layout.addComponent(display);
+        layout.addComponent(click);
+        
+        setCompositionRoot(layout);
+        
+        setSizeFull();
+    }
+}
+
+// Use it
+MyView myview = new MyView();
+----
+
+For a more detailed description of the [classname]#CustomComponent#, see
+<<dummy/../../../framework/components/components-customcomponent#components.customcomponent,"Composition
+with CustomComponent">>.
+
+
+[[application.architecture.navigation]]
+== View Navigation
+
+While the most simple applications have just a single __view__ (or __screen__),
+perhaps most have many. Even in a single view, you often want to have sub-views,
+for example to display different content.
+<<figure.application.architecture.navigation>> illustrates a typical navigation
+between different top-level views of an application, and a main view with
+sub-views.
+
+[[figure.application.architecture.navigation]]
+.Navigation Between Views
+image::img/view-navigation-hi.png[]
+
+The [classname]#Navigator# described in
+<<dummy/../../../framework/advanced/advanced-navigator#advanced.navigator,"Navigating
+in an Application">> is a view manager that provides a flexible way to navigate
+between views and sub-views, while managing the URI fragment in the page URL to
+allow bookmarking, linking, and going back in browser history.
+
+Often Vaadin application views are part of something bigger. In such cases, you
+may need to integrate the Vaadin applications with the other website. You can
+use the embedding techniques described in
+<<dummy/../../../framework/advanced/advanced-embedding#advanced.embedding,"Embedding
+UIs in Web Pages">>.
+
+
+[[application.architecture.accessing]]
+== Accessing UI, Page, Session, and Service
+
+You can get the UI and the page to which a component is attached to with
+[methodname]#getUI()# and [methodname]#getPage()#.
+
+However, the values are [literal]#++null++# until the component is attached to
+the UI, and typically, when you need it in constructors, it is not. It is
+therefore preferable to access the current UI, page, session, and service
+objects from anywhere in the application using the static
+[methodname]#getCurrent()# methods in the respective [classname]#UI#,
+[classname]#Page#, [classname]#VaadinSession#, and [classname]#VaadinService#
+classes.
+
+
+[source, java]
+----
+// Set the default locale of the UI
+UI.getCurrent().setLocale(new Locale("en"));
+
+// Set the page title (window or tab caption)
+Page.getCurrent().setTitle("My Page");
+        
+// Set a session attribute
+VaadinSession.getCurrent().setAttribute("myattrib", "hello");
+
+// Access the HTTP service parameters
+File baseDir = VaadinService.getCurrent().getBaseDirectory();
+----
+
+You can get the page and the session also from a [classname]#UI# with
+[methodname]#getPage()# and [methodname]#getSession()# and the service from
+[classname]#VaadinSession# with [methodname]#getService()#.
+
+The static methods use the built-in ThreadLocal support in the classes.
+
+ifdef::web[]
+ The pattern is described in
+<<dummy/../../../framework/advanced/advanced-global#advanced.global.threadlocal,"ThreadLocal
+Pattern">>.
+endif::web[]
+
+
+
+