path: root/documentation/application/application-architecture.asciidoc

---
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[width=70%, scaledwidth=90%]

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[]