Added tutorial to documentation

Change-Id: I805c001ab86d4be0c0842d07ef15e02e7cf939cb

1 files changed, 884 insertions, 0 deletions

diff --git a/documentation/tutorial.adoc b/documentation/tutorial.adoc
new file mode 100644
index 0000000000..db65033065
--- /dev/null
+++ b/documentation/tutorial.adoc
@@ -0,0 +1,884 @@
+:experimental:
+:sectnums:
+:imagesdir: img
+
+= Vaadin tutorial
+
+This tutorial gives you an overview of how you can use
+https://vaadin.com/framework[Vaadin Framework] to build single-page web UI's for your Java
+application. All you need to start with it is JDK 8 and an https://en.wikipedia.org/wiki/Integrated_development_environment[IDE] like Eclipse.
+No extensive knowledge of Java is even needed to get started, only the basic programming skills are required. Although the tutorial is built for
+Eclipse users, you can use your IDE of choice.
+
+We'll build a simple customer management system. It is not a real app, but we'll
+use an in-memory "backend" so that you can understand how to hook it to an
+existing Java based backend. We'll cover the basic Vaadin development and you
+can use the result as a basis for more experiments with Vaadin, like using
+add-ons, your own custom look and feel (aka. theme), adding new views or optimizing the result for
+mobile support.
+
+You'll need about 20 - 60 minutes to complete the tutorial, depending on your
+existing experience, but naturally you can just do the beginning of
+the exercise or pick any of the steps you want. To start from a specific step,
+we have prepared the example code after each step to be 
+downloaded as a zip file. If don't want to do the exercise at all, you can also
+just https://github.com/vaadin/tutorial/[downlood the final application] and
+play around with it.
+
+The tutorial uses Java 8, so ensure you have an up-to-date JDK 8 installed. Most
+linux distributions can use package managers to install JDK8, Windows and Mac users should
+download it from
+http://www.oracle.com/technetwork/java/javase/downloads/index.html[Oracle's Java
+SE site].
+
+Also make sure you have the latest version of your IDE. Eclipse is available in
+various packages, be sure to download the *Eclipse IDE for Java EE Developers*
+from http://www.eclipse.org/downloads/[eclipse.org].
+
+== Creating a project using an archetype
+
+As a starting point for the application, we'll use a Maven archetype called
+vaadin-archetype-application. Maven archetypes are project stubs with basic
+build script and some example code.
+
+Start by choosing menu:File[New > Maven Project] from the menu.
+
+image::createMavenProject.jpg[Create a new Maven built Vaadin project.]
+
+TIP: If the "Maven Project" is not visible in the menu, you should switch to the
+_Java EE_ perspective. Use the shortcut button in the toolbar or
+menu:Window[Perspective] to do this.
+
+The first page in the wizard is ok with its defaults, but on the second page
+you'll need to choose _vaadin-archetype-application_ archetype. You can first
+try to find it using the filtering function, but in some cases Eclipse hasn't
+yet indexed the archetype catalog, so you might need to manually add the
+archetype details with the _Add Archetype_ button. The Group Id is _com.vaadin_,
+the Artifact Id is _vaadin-archetype-application_ and as a version you can use
+the latest Vaadin version, at the time of writing _7.6.2_. The _Repository URL_
+can be left blank.
+
+CAUTION: Eclipse has a bug in its project wizard. If
+_vaadin-archetype-application_ doesn't appear in the listing, even though you
+added it using the _Add Archetype_ button, close the whole new project wizard
+and re-open it by selecting menu:File[New > Maven Project] again. The archetype
+then typically appears in the listing and can be found by the filtering
+functionality.
+
+On the next wizard page, type in _my.vaadin_ as the Group Id, _app_ as the
+Artifact Id and click _Finish_. If this is your first Vaadin app, creating
+a project might take a while, depending on the speed of your network, as Vaadin
+libraries and other dependencies are being downloaded. Maven caches these on
+your local file system and creating your next Maven based Vaadin project will be much
+faster.
+
+Right click on the newly created project and choose menu:Run as[Maven Install].
+This will initiate a full build of your application and will finally create a
+https://en.wikipedia.org/wiki/WAR_(file_format)[war] file to the "target" directory that you can deploy to your application
+server. As Maven might again need to download some new modules and the project
+has a setup for add-on usage and contains a project specific theme, the first
+build will take a while.
+
+TIP: For the Maven compilation to work you need a JDK to be configured in your
+Eclipse in menu:Window[Preferences > Java > Installed JREs > Add...]. This step
+is necessary at least on Windows, if you are using a fresh installation of
+Eclipse or for some other reason haven't configured a JDK to your Eclipse. The
+JDK by default installs to _\Program Files\Java_ on Windows. You
+can make JDK the default JRE for your Eclipse.
+
+While the build is running, let's have a look at what the archetype created for
+you. You can browse your project resources from the tree structure in the
+_Project Explorer_. Maven's _pom.xml_ on top level contains settings for your
+projects build and declares the used dependencies. Open _Java Resources_ and
+below it _src/main/java_, the main source directory, and _my.vaadin.app_, the
+main Java package that will contain your Vaadin UI code.
+
+TIP: Eclipse shows all project files in the Project Explorer. In this case you
+can also find your _.java_ files via top level _src_ node, but the suggested
+method is to access them via the _Java Resources_ node, which is optimized for
+editing Java source code.
+
+The UI code (and the Servlet declaration) used by the application stub can be
+found in the _MyUI.java_ file. Let's read it through to see how it works. The
+_init_ method of a UI class is triggered when a user enters your web
+application. The VerticalLayout is one of the most used layout objects, which
+are used to position and display other Vaadin components in your UI classes. The
+example code creates one TextField to allow the user to input her name and a
+Button whose click listener dynamically adds a new Label component to the main
+layout. In the end of the init method we just configure the main layout and
+place components into it and set it to be the content of MyUI.
+
+To test your first Vaadin application, right click on the project and choose
+menu:Debug as[Maven build...]. The debug mode is slightly slower than the basic run
+mode, but it often helps you to figure out what is happening in your
+application.
+
+image::debugAsMavenBuild.jpg[Starting the server using a Maven target]
+
+In the dialog, type _Run in jetty_ to the _Name_ input and _jetty:run_ to the
+_Goals_ input.
+
+image::debugAsMavenBuild2.jpg[Generating a Maven launch for jetty:run target]
+
+Before clicking debug, to make sure debugging works properly, add your Java
+project to the source lookup path from the _Source_ tab, like it is being done
+in the image below.
+
+image::debugAsMavenBuildAddSources.jpg[Adding sources for debugging]
+
+Now click _Debug_ to continue. This will download a small Java web server
+(if not cached to your local Maven repository), and use it to host
+your application. Once the server has started, point your browser to the URL
+http://localhost:8080/[http://localhost:8080/] to see the running application.
+
+If you make changes to the code, the jetty server will notice the changes and in
+a couple of seconds most changes are automatically deployed. Reloading the page
+in your browser will show the changes.
+
+TIP: In some cases your JVM might not allow injecting changes on the fly. In
+these cases, Eclipse will complain about "Hot code replacement error". Just
+choose to restart the server to get the latest changes. Many Java developers use
+a commercial tool called http://zeroturnaround.com/software/jrebel/[JRebel] to make code
+replacement work better.
+
+Mastering the usage of the java debugger is also handy to better understand how your
+application actually works and fixing bugs that all developers write at some
+point. As Vaadin is "only" Java code, you can use all of Java's debugging tools, which cannot be done with other UI frameworks where the UI is written (partly) in HTML and/or JavaScript. Double click on the line number in the Java editor, for example of the
+following line in the click listener:
+
+[source,java]
+----
+    layout.addComponent(new Label("Thanks " + name.getValue()
+----
+
+This will add a breakpoint to the selected line. If you then click the button in
+your browser, the execution of the application will stop on that line. Eclipse
+will ask you to enter to _Debugging perspective_ and you can inspect its
+variables and step through the execution. Clicking on the _play_ icon in the
+toolbar will continue the execution. Double click the same line again to remove
+the breakpoint.
+
+image::debugInBreakPointVariable.jpg[Execution in a break point in the button click listener]
+
+Clicking the red square in the Console view will terminate the server process.
+You can restart it easily form the run/debug history. You can find that from the
+small down arrow next to the green play button or bug button (for the debug
+mode) in the toolbar. Alternatively you can use the main menu menu:Run[Run
+history/Debug history > Run in Jetty].
+
+To get back to the _Java EE Perspective_, an Eclipse mode designed for editing
+Java web app code, click the _Java EE_ button in the toolbar.
+
+== Adding a demo "backend"
+
+Before getting more into real Vaadin development, let's introduce some domain
+objects and a "fake backend". In a real world application, you'll most likely
+have something similar, implemented with, for example, JPA and EJB or a Spring based
+service.
+
+Copy the following three classes from github to your project. Class names
+point to the classes hosted in Github. Copying classes can be done in many ways.
+
+TIP: The fastest way to copy classes using Eclipse is to use your good old
+clipboard. Select the text content of the whole class from your browser, choose
+menu:Edit[Copy], focus the node representing the _my.vaadin.app_ Java package in
+Eclipse's Java Resources view and choose menu:Edit[Paste]. Eclipse is smart
+enough to automatically create a properly named Java file for the class.
+
+ * https://raw.githubusercontent.com/vaadin/tutorial/master/src/main/java/my/vaadin/app/CustomerStatus.java[CustomerStatus] - this is a simple enum class
+ * https://raw.githubusercontent.com/vaadin/tutorial/master/src/main/java/my/vaadin/app/Customer.java[Customer] - this is the main domain object, a basic Java bean that we'll be
+   using in our example
+ * https://raw.githubusercontent.com/vaadin/tutorial/master/src/main/java/my/vaadin/app/CustomerService.java[CustomerService] - this is a simple facade via which you can request and modify Customer instances. You can think of this as your entry point to your fake database.
+
+In the next steps, we'll be using these classes and build a UI around them. The
+actual implementation of these classes is not relevant for this tutorial, but
+feel free to have a look around.
+
+== Listing entities in a Grid
+
+TIP: Starting from this step directly? https://github.com/vaadin/tutorial/archive/step2.zip[Download the project] for this step, extract the zip file and choose menu:Import...[Maven>Existing Maven project].
+
+Often when you start building a UI for a data centric application, the first
+thing you want to do is to list your data from your backend. There are several
+components and methods in Vaadin to do this. In this example, we'll use the Grid
+component for tabular presentation of our customers.
+
+We'll start by introducing a Grid field to the MyUI class. We could of course
+just introduce the Grid as a variable in the init method, but we'll most likely
+want to refer to it later. Also, let's get a reference to the CustomerService.
+
+[source,java]
+----
+public class MyUI extends UI {
+
+    // Add next two lines:
+    private CustomerService service = CustomerService.getInstance();
+    private Grid grid = new Grid();
+
+    // the rest is already there...
+    @Override
+    protected void init(VaadinRequest vaadinRequest) {
+----
+
+TIP: If you are new to Java development, you probably don't feel comfortable
+with the red compilation error for the line where the Grid got introduced, due
+to a missing import. This is easily fixed in Eclipse by using the
+menu:Source[Organize Imports] command. Learn its shortcut (kbd:[Ctrl-Shift-O] or
+kbd:[CMD-Shift-O] on Macs), you'll be using it a lot in Java development. In
+possible class name collisions, always choose the appropriate class from the
+_com.vaadin.ui_ package if you want to import core Vaadin UI classes like the
+Grid.
+
+To simply list all properties of all Customer objects from the backend service,
+replace the init method with the following snippet:
+
+[source,java]
+----
+@Override
+protected void init(VaadinRequest vaadinRequest) {
+    final VerticalLayout layout = new VerticalLayout();
+
+    // add Grid to the layout
+    layout.addComponents(grid);
+
+    // fetch list of Customers from service and assign it to Grid
+    List<Customer> customers = service.findAll();
+    grid.setContainerDataSource(new BeanItemContainer<>(Customer.class, customers));
+
+    layout.setMargin(true);
+    setContent(layout);
+}
+----
+
+TIP: Again, use the organize imports feature. The List object we use here is
+_java.util.List_.
+
+As we'll want to refresh the listing from various places in our application,
+extract the customer listing part into its own "updateList" method with the
+*public* modifier. The public modifier is handy later when we want to update the
+listing from other classes. You can let Eclipse help here by selecting the
+relevant lines and using the "quick fix" feature (kbd:[Ctrl+1] or kbd:[Cmd+1] on
+Macs). The extracted method call looks like this:
+
+[source,java]
+----
+    public void updateList() {
+        List<Customer> customers = service.findAll();
+        grid.setContainerDataSource(new BeanItemContainer<>(Customer.class, customers));
+    }
+----
+
+If you try the application now, you'll see that quite many properties of the
+customers are shown in the grid. To limit the visible properties, configure
+the Grid using the _setColumns_ method to only show "firstName", "lastName" and
+"email" properties.
+
+[source,java]
+----
+    grid.setColumns("firstName", "lastName", "email");
+----
+
+At this point the body of the MyUI class should look like this (servlet declaration
+omitted):
+
+[source,java]
+----
+private CustomerService service = CustomerService.getInstance();
+private Grid grid = new Grid();
+
+@Override
+protected void init(VaadinRequest vaadinRequest) {
+    final VerticalLayout layout = new VerticalLayout();
+
+    grid.setColumns("firstName", "lastName", "email");
+    // add Grid to the layout
+    layout.addComponent(grid);
+
+    updateList();
+
+    layout.setMargin(true);
+    setContent(layout);
+}
+
+public void updateList() {
+    // fetch list of Customers from service and assign it to Grid
+    List<Customer> customers = service.findAll();
+    grid.setContainerDataSource(new BeanItemContainer<>(Customer.class, customers));
+}
+----
+
+You can now save your changes to the file and verify the changes from your browser.
+You can do this at any point during the rest of the tutorial as well.
+
+== Creating live filtering for entities
+
+TIP: Starting from this step directly? https://github.com/vaadin/tutorial/archive/step3.zip[Download the project] for this step, extract the zip file and choose menu:Import...[Maven>Existing Maven project].
+
+A search functionality is expected in every modern application and it is
+also a nice Vaadin development exercise. Let's add a filtering functionality to
+the Customer listing we created in the previous step.
+
+We'll start by introducing a TextField component as a field to our UI class:
+
+[source,java]
+----
+    private TextField filterText = new TextField();
+----
+
+In the _init_ method, configure the text field to contain a helpful input prompt
+and add a text change listener to the field. The exact place of these lines is
+not important, but add them, for example, after you have introduced the _layout_
+object.
+
+[source,java]
+----
+filterText.setInputPrompt("filter by name...");
+filterText.addTextChangeListener(e -> {
+    grid.setContainerDataSource(new BeanItemContainer<>(Customer.class,
+            service.findAll(e.getText())));
+});
+----
+
+TIP: To keep your code more readable, you can use autoformat after you write or
+copy paste code snippets. The default keyboard shortcut in Eclipse is
+kbd:[Ctrl+Shift+F] or kbd:[Cmd+Shift+F]
+
+The text change listener is another listener (in addition to the more commonly
+used ValueChangeListener) you can use with text fields in Vaadin. It is fired
+lazily while the user is typing, but only when there is a small pause in the
+typing. This makes it perfect for this kind of automatic filtering. When the
+user has changed the text, we'll just update the listing like in the updateList
+method, but use the current text as a filter for entries.
+
+To keep the _updateList_ method functional, it should also take into
+consideration the possible value in the filterText field. Change the line for
+fetching the customers into this:
+
+[source,java]
+----
+  List<Customer> customers = service.findAll(filterText.getValue());
+----
+
+Before adding the text field to the UI, let's improve the usability a bit
+and make a short exercise to compose better components from lower level UI
+components. The search field can naturally be cleared with the keyboard, but let's
+add a clear button next to the text field. Start by adding the following lines
+to the init method, for example right after your filterText configuration:
+
+[source,java]
+----
+Button clearFilterTextBtn = new Button(FontAwesome.TIMES);
+clearFilterTextBtn.setDescription("Clear the current filter");
+clearFilterTextBtn.addClickListener(e -> {
+  filterText.clear();
+  updateList();
+});
+----
+
+Vaadin contains a set of built in icons, from which we use the "X" icon,
+_FontAwesome.TIMES_, here, which most users will recognise as a functionality to clear
+the value. If we set the description to a component, it will be shown as a
+tooltip for those users who hover the cursor over the button and wonder what to
+do with it. In the click listener, we simply clear the text from the field and
+refresh the content of the listing.
+
+Vaadin contains lots of different kinds of layouts. The simplest way to align
+the text field and the button next to each other would be to use a
+HorizontalLayout. An alternative way we use here is using a CssLayout, which is
+a lightweight layout that is easy to customize with css. Even if you wouldn't
+want to play with CSS yourself, you can often use one of the existing style
+rules in the default _Valo_ theme. The following snippet will create a nice
+compact "composition" of both the TextField and the clear button. Add these
+lines to the init method right after you configured the _clearFilterTextBtn_:
+
+[source,java]
+----
+CssLayout filtering = new CssLayout();
+filtering.addComponents(filterText, clearFilterTextBtn);
+filtering.setStyleName(ValoTheme.LAYOUT_COMPONENT_GROUP);
+----
+
+Finally, *change* the row in the init method that currently adds only the grid,
+to add both _filtering_ composition and the _grid_ to the main _layout_ of the
+application.
+
+[source,java]
+----
+    layout.addComponents(filtering, grid);
+----
+
+Now it is a good place to save your changes and try them in your browser.
+
+== Creating a form to edit Customer objects
+
+To edit and add Customer objects we need to create a form, that edits the
+values in our domain objects. This tutorial has two alternative methods to do
+that. Pick either of them.
+
+=== Creating a form using Vaadin Designer
+
+TIP: Starting from this step directly? https://github.com/vaadin/tutorial/archive/step4.zip[Download the project] for this step, extract the zip file and choose menu:Import...[Maven>Existing Maven project].
+
+The form to edit Customer objects can be built using several methods of which
+the visual composition by drag 'n' drop is the most intuitive. Vaadin
+Designer is an Eclipse plugin that you can install and do WYSIWYG editing of
+your view code. We'll use it to create the form and then hook the editing logic
+to it with Java.
+
+TIP: If you are using another IDE or just prefer to compose your user interface
+with code, take the alternative step, <<Creating a form using plain Java>>,
+where the CustomerForm is composed using plain Java code.
+
+==== Installing Vaadin Designer
+
+Vaadin Designer comes as an integrated part of Vaadin Plugin for Eclipse. It can
+be installed easily via Eclipse Marketplace. Choose menu:Help[Eclipse Marketplace]
+
+In the dialog, just search for Vaadin and click _install_ to mark it for
+installation. Clicking _Install Now_ will take you to choose the modules you want
+and accept the license agreement.
+
+image::pluginEclipseMarketPlace2.jpg[Selecting Vaadin Plugin for Eclipse for installation in Eclipse Marketplace]
+
+If you get a security warning about the software containing unsigned content,
+just accept the warning by clicking OK. After installation, Eclipse asks if you
+want to restart. Click Yes.
+
+TIP: When you use Vaadin Designer for the first time in the next
+step, it will ask for a license key. Get a key from
+https://vaadin.com/designer. If you are not willing to buy a license now, just
+acquire a trial license.
+
+==== Creating the form design
+
+The following screencast will show you how to produce the
+_CustomerFormDesign.html_, a design file we need in this tutorial. Use pause and
+slow motion to follow better what is being done in the video. Feel free to get creative!
+
+video::B5dN69NSS78[youtube, width="640", height="400"]
+
+TIP: At any point of the process, you can also switch to the markup mode where
+you can edit the raw content of the .html file. If you wish to take a shortcut
+or think you did something wrong when using the designer, you can just
+copy-paste the content of https://github.com/vaadin/tutorial/blob/master/src/main/resources/my/vaadin/app/CustomerFormDesign.html[the final state] to your own .html file.
+
+At this point we only have a static mockup of the actual UI. To implement a
+functional form component, we need some Java code as well. Vaadin Designer
+automatically creates a similarly named Java class, but a good habit is to never touch the auto-generated file, in this case the
+CustomerFormDesign.java file. If you'd introduce a new field to your form,
+your changes to CustomerFormDesign would be overridden by the tooling. Instead,
+we'll create a class called CustomerForm which inherits from the auto-generated
+CustomerFormDesign class.
+
+Start by creating a new Java class with the name CustomerForm. In Eclipse, right
+click on the "my.vaadin.app" package and choose menu:New[Class]. Type in the
+name _CustomerForm_, define the superclass as
+_my.vaadin.app.CustomerFormDesign_ and click _finish_.
+
+From the superclass, we inherit all the UI elements that we named when using
+the designer. E.g. by simply referencing to "save" field in the CustomerForm,
+we'll have access to the save button we previously created.
+
+We will later need a reference to the currently edited Customer object,
+CustomerService and the MyUI that uses this class. Add these fields and a
+basic constructor that accepts MyUI as a parameter to the CustomerForm class:
+
+[source,java]
+----
+CustomerService service = CustomerService.getInstance();
+private Customer customer;
+private MyUI myUI;
+
+public CustomerForm(MyUI myUI) {
+    this.myUI = myUI;
+}
+----
+
+Although the form is not yet fully functional, you might want to see what it
+looks like at this point. Add it as a field to the _MyUI_ class:
+
+[source,java]
+----
+    CustomerForm form = new CustomerForm(this);
+----
+
+Now let's modify the init method in MyUI to show the form. Let's wrap both the
+Grid and the CustomerForm in a horizontal layout and configure the Grid to use
+all of the available space more efficiently. Replace the line
+*layout.addComponents(filtering, grid);* with the following:
+
+[source,java]
+----
+HorizontalLayout main = new HorizontalLayout(grid, form);
+main.setSpacing(true);
+main.setSizeFull();
+grid.setSizeFull();
+main.setExpandRatio(grid, 1);
+
+layout.addComponents(filtering, main);
+----
+
+If you now save your changes and reload your application page in a browser,
+you should see your CustomerForm next to the grid that lists your
+existing entities.
+
+Let's get back to the CustomerForm. The first thing we'll need is to populate
+the options for the select. To add all enum values as valid selections, add the
+following line to the constructor:
+
+[source,java]
+----
+    status.addItems(CustomerStatus.values());
+----
+
+Let's also improve the UX a bit. When building the design, we already
+emphasized the save button with a ValoTheme.BUTTON_PRIMARY style name. Thus, it
+would be natural if the enter-key would do the same action as clicking the
+save button. Assign a keyboard shortcut to the save button with this line in the
+constructor:
+
+[source,java]
+----
+save.setClickShortcut(KeyCode.ENTER);
+----
+
+To finish our form, we need to create a public API that we will use in the next
+part from MyUI, to pass in a Customer object that the form should edit. We
+will also add some logic to actually save the changes. We'll start by creating a
+setter method to the Customer field. Just type _setCus_ in the body of the
+class and hit autocomplete (kbd:[Ctrl+Space]) and Eclipse will create a method
+stub for you. Complete it with the following implementation:
+
+[source,java]
+----
+public void setCustomer(Customer customer) {
+    this.customer = customer;
+    BeanFieldGroup.bindFieldsUnbuffered(customer, this);
+
+    // Show delete button for only customers already in the database
+    delete.setVisible(customer.isPersisted());
+    setVisible(true);
+    firstName.selectAll();
+}
+----
+
+In addition to saving the reference of the currently edited Customer object, we are
+calling the _BeanFieldGroup.bindFieldsUnbuffered_ method. It will initialize all
+similarly named editor fields in this form with the values from their
+counterpart in the given Customer object. Also, it will automatically update the
+values in the domain objects as the corresponding field value changes in the
+user interface.
+
+TIP: If the naming convention based databinding doesn't fit your needs, you
+can use
+https://www.vaadin.com/api/com/vaadin/data/fieldgroup/PropertyId.html[PropertyId]
+annotation on fields to explicitly declare the edited property.
+
+We'll also want to ensure the form is visible and that focus goes to the
+firstName field to improve user experience. As we will be using the form to
+edit both new non-persisted objects and existing customers, we will also show
+the delete button only for customers that are already persisted in the backend.
+
+The last thing we need to do is to handle save and delete button clicks. Add
+the following methods to the CustomerForm class:
+
+[source,java]
+----
+private void delete() {
+    service.delete(customer);
+    myUI.updateList();
+    setVisible(false);
+}
+
+private void save() {
+    service.save(customer);
+    myUI.updateList();
+    setVisible(false);
+}
+----
+
+Finally, we'll add listeners to the buttons to call these methods. Adding these
+simple lambda expressions to the constructor will take care of that:
+
+[source,java]
+----
+save.addClickListener(e->this.save());
+delete.addClickListener(e->this.delete());
+----
+
+TIP: For a truly re-usable form component in a real life project, you'd want to
+introduce an interface to replace the myUI field or, even better, use an event
+system like https://vaadin.com/wiki/-/wiki/main/Events+and+contexts[CDI events]
+to completely decouple the components. We'll leave that out of this tutorial for
+simplicity.
+
+=== Creating a form using plain Java
+
+This is an alternative step to the <<Creating a form using Vaadin Designer>>,
+where you'll build the form UI programmatically in plain Java. If you already
+completed the step using Vaadin Designer, you can proceed to
+<<Connecting the form to the application>>.
+
+Start by creating a new Java class with the name CustomerForm. In Eclipse right
+click on the "my.vaadin.app" package and choose menu:New[Class]. Type in the
+name _CustomerForm_, define the superclass as _com.vaadin.ui.FormLayout_ and
+click _finish_.
+
+In the form, we'll need editor fields for each property in our Customer domain
+class. There are different kinds of fields in Vaadin for editing different kinds
+of properties. In this example, we'll use a TextField, a PopupDateField and a
+NativeSelect. Add the following field declarations and action buttons as Java
+fields to the CustomerForm:
+
+[source,java]
+----
+private TextField firstName = new TextField("First name");
+private TextField lastName = new TextField("Last name");
+private TextField email = new TextField("Email");
+private NativeSelect status = new NativeSelect("Status");
+private PopupDateField birthdate = new PopupDateField("Birthday");
+private Button save = new Button("Save");
+private Button delete = new Button("Delete");
+----
+
+Also, we will laterneed a reference to the currently edited Customer object,
+CustomerService and the MyUI that uses this class. Add these fields and a
+basic constructor that accepts MyUI as a parameter to the CustomerForm class:
+
+[source,java]
+----
+private CustomerService service = CustomerService.getInstance();
+private Customer customer;
+private MyUI myUI;
+
+public CustomerForm(MyUI myUI) {
+    this.myUI = myUI;
+
+    setSizeUndefined();
+    HorizontalLayout buttons = new HorizontalLayout(save, delete);
+    buttons.setSpacing(true);
+    addComponents(firstName, lastName, email, status, birthdate, buttons);
+}
+----
+
+In the constructor we make the form size undefined, which practically means it
+will consume the minimum space defined by its content. Then we'll just add all
+the fields to the CustomerForm and add action buttons to the bottom - side-by-side
+using a HorizontalLayout. Although the form is not yet fully functional, you
+might want to see what it looks like at this point. Add it as a field to the MyUI
+class:
+
+[source,java]
+----
+    CustomerForm form = new CustomerForm(this);
+----
+
+Now let's modify the init method in MyUI to show the form. Let's wrap both the
+Grid and the CustomerForm in a horizontal layout and configure the Grid to use
+all of the available space more efficiently. Replace the line
+*layout.addComponents(filtering, grid);* with the following:
+
+[source,java]
+----
+HorizontalLayout main = new HorizontalLayout(grid, form);
+main.setSpacing(true);
+main.setSizeFull();
+grid.setSizeFull();
+main.setExpandRatio(grid, 1);
+
+layout.addComponents(filtering, main);
+----
+
+When you now save your changes and reload your application page in your browser,
+you should see your CustomerForm next to the grid that lists your
+existing entities.
+
+Let's get back to the CustomerForm. The first thing we'll need is to populate
+the options for the select. To add all enum values as valid selections, add the
+following line to the constructor:
+
+[source,java]
+----
+   status.addItems(CustomerStatus.values());
+----
+
+Let's also improve the UX a bit. The most common thing your users will want to
+do with this kind of form is to save it. Let's decorate the button with a style
+name that makes it more prominent in the UI and give it a keyboard shortcut -
+simply an enter hit in this case:
+
+[source,java]
+----
+save.setStyleName(ValoTheme.BUTTON_PRIMARY);
+save.setClickShortcut(KeyCode.ENTER);
+----
+
+To finish our form, we need to create a public API that we will use in the next
+part from the MyUI, to pass in a Customer object that the form should edit. We
+will also add some logic to actually save the changes. We'll start by creating a
+setter method for the Customer field. Just type _setCus_ in the body of the
+class and hit autocomplete (kbd:[Ctrl+Space]) and Eclipse will create a method
+stub for you. Complete it with the following implementation:
+
+[source,java]
+----
+public void setCustomer(Customer customer) {
+    this.customer = customer;
+    BeanFieldGroup.bindFieldsUnbuffered(customer, this);
+
+    // Show delete button for only customers already in the database
+    delete.setVisible(customer.isPersisted());
+    setVisible(true);
+    firstName.selectAll();
+}
+----
+
+In addition to saving the reference of the currently edited Customer object, we are
+calling _BeanFieldGroup.bindFieldsUnbuffered_ method. It will initialise all
+similarly named editor fields in this form with the values from their
+counterpart in the given Customer object. Also, it will automatically update the
+values in the domain objects as the corresponding field value changes in the
+user interface.
+
+TIP: If the naming convention based databinding doesn't fit your needs, you
+can use
+https://www.vaadin.com/api/com/vaadin/data/fieldgroup/PropertyId.html[PropertyId]
+annotation on fields to explicitly declare the edited property.
+
+We'll also want to ensure the form is visible and that the focus goes to the
+firstName field to improve the user experience. As we will be using the form to
+edit both new non-persisted objects and existing customers, we will also show
+the delete button only for customers that are already persisted in the backend.
+
+The last thing we need to do is to handle save and delete button clicks. Add
+the following methods to the CustomerForm class:
+
+[source,java]
+----
+private void delete() {
+    service.delete(customer);
+    myUI.updateList();
+    setVisible(false);
+}
+
+private void save() {
+    service.save(customer);
+    myUI.updateList();
+    setVisible(false);
+}
+----
+
+Finally, we'll add listeners to the buttons to call these methods. Adding these
+simple lambda expressions to the constructor will take care of that:
+
+[source,java]
+----
+save.addClickListener(e->this.save());
+delete.addClickListener(e->this.delete());
+----
+
+TIP: For a truly re-usable form component in a real life project, you'd want to
+introduce an interface to replace the myUI field or, event better, use an event
+system like https://vaadin.com/wiki/-/wiki/main/Events+and+contexts[CDI events]
+to completely decouple the components. We'll leave that out of this tutorial for
+simplicity.
+
+== Connecting the form to the application
+
+TIP: Starting from this step directly? https://github.com/vaadin/tutorial/archive/step5.zip[Download the project] for this step, extract the zip file and choose menu:Import...[Maven>Existing Maven project].
+
+In this part, we'll use the CustomerForm class, which we created in the
+previous step, from the MyUI class. We will use it for both editing the existing
+customers and creating new ones.
+
+In the previous part, we already added the form to the _MyUI_ to see what it looks
+like. By default, we want it to be invisible, so let's first hide it
+by adding this line to the _init_ method of MyUI class:
+
+[source,java]
+----
+form.setVisible(false);
+----
+
+To edit the customer chosen from the Grid, add the following selection listener to
+the end of the _init_ method:
+
+[source,java]
+----
+grid.addSelectionListener(event -> {
+    if (event.getSelected().isEmpty()) {
+        form.setVisible(false);
+    } else {
+        Customer customer = (Customer) event.getSelected().iterator().next();
+        form.setCustomer(customer);
+    }
+});
+----
+
+In the listener, we simply take the Customer object of the selected row and pass it to
+the CustomerForm for editing. In the previous step, we added a side effect to the
+_setCustomer_ method that will bind the domain object to the corresponding fields
+and make it visible. If the selection is empty, we'll hide the form.
+
+To allow users to also create new customer records, we'll create a simple "Add
+customer button" to the top of the UI, right next to the _filtering_ composition
+we have already built from a CssLayout, a TextField and a Button. Introduce the new
+Button with a click listener, by adding the following lines to the _init_ method,
+right after where you introduced the _filtering_ composition:
+
+[source,java]
+----
+Button addCustomerBtn = new Button("Add new customer");
+addCustomerBtn.addClickListener(e -> {
+    grid.select(null);
+    form.setCustomer(new Customer());
+});
+----
+
+In the click listener, we first clear a possible selection from the grid and then
+instantiate a new Customer object and pass that to the form for editing.
+
+To add it beside our _filtering_ composition, we can use a HorizontalLayout to
+create a toolbar where we place both components. First, introduce a toolbar like
+this after the previously created _addCustomerBtn_:
+
+[source,java]
+----
+HorizontalLayout toolbar = new HorizontalLayout(filtering, addCustomerBtn);
+toolbar.setSpacing(true);
+----
+
+And, again, *replace* the line that populates your main layout to add the
+toolbar instead of just the filtering composition, which we just moved to the
+_toolbar_ layout.
+
+[source,java]
+----
+layout.addComponents(toolbar, main);
+----
+
+All planned features are now done. You can save the changes and play around with
+the application. If something went wrong, you can also download an example of
+https://github.com/vaadin/tutorial[the final application] and see what went wrong.
+
+== It works! What next?
+
+Congratulations! Users can now create, read, update and delete customer records
+stored in the demo backend and you have completed creating your first CRUD UI
+with Vaadin.
+
+If you are an experienced Java developer, you are probably already full of ideas of
+how you can use your existing skills and create new shiny web UIs for your
+existing Java apps. If you want more ideas of how to create full stack
+applications, you might, for example, go through the
+http://spring.io/guides/gs/crud-with-vaadin/[Creating CRUD UI with Vaadin] guide
+and create a bit similar UI with a real database backend implemented with Spring
+Data JPA. We have also collected a couple of other resources for an easy
+start in your Vaadin developer career.
+
+ * https://vaadin.com/docs/-/part/framework/introduction/intro-overview.html[Vaadin online documentation]
+ * http://spring.io/guides/gs/crud-with-vaadin/[Creating CRUD UI with Vaadin] - the tutorial for your first Vaadin application using a Spring based backend.
+ * https://github.com/mstahv/jpa-invoicer[Jave EE example app] - a Vaadin app example for creating invoices that uses Java EE backend, Apache DeltaSpike Data for simple JPA layer, OAuth2 based login, PDF generation etc.
+ * http://vaadin.com/directory[Directory] - a vast source of awesome Vaadin add-ons
+
+