Introduction to the Vaadin Web Framework

Tremurici Cornel contributed to this tutorial

Vaadin is an open source web application framework for rich Internet applications. In contrast to JavaScript libraries and browser-plugin based solutions, it features a server-side architecture, which means that the majority of the logic runs on the servers. AJAX technology is used at the browser-side to ensure a rich and interactive user experience. On the client-side Vaadin is built on top of and can be extended with GWT.

The core piece of Vaadin is the Java library, which is designed to make creation and maintenance of high quality web-based user interface easy. The key idea in the server-driven programming model of Vaadin is that it allows you to forget the web and lets you program user interfaces much like you would program any Java desktop application with conventional toolkits such as AWT, Swing or SWT — but easier. With the server-driven programming model, Vaadin takes care of managing the user interface in the browser and AJAX communications between the browser and the server. With the Vaadin approach, you do not need to learn and debug browser technologies such as HTML or JavaScript.

The Vaadin library defines a clear separation between user interface presentation and logic and allows you to develop them separately. Vaadin's approach is to use themes that dictate the visual appearance of the applications. Themes control the appearance of the user interfaces using CSS and (optional) HTML page templates. Vaadin provides default themes, but you can create your own if you need to. On the backend, Vaadin uses GWT, the Google Web Toolkit, for rendering the user interface in the browser. GWT programs are written in Java, but compiled into JavaScript. GWT is ideal for implementing advanced user interface components (or widgets in GWT terminology) and interaction logic in the browser while Vaadin handles the actual application logic in the server. Vaadin is designed to be extensible, and you can indeed use any 3rd-party GWT components easily, in addition to the component repertoire offered in Vaadin. The use of GWT also means that all the code you need to write is pure Java.

To learn more about what Vaadin can do, see the Vaadin features page.

In this tutorial you learn about the Vaadin plugin for NetBeans IDE and you create a simple web application with NetBeans IDE and the Vaadin plugin.

Contents

• Installing the Vaadin Plugin
• Creating a Java Web Application With Vaadin
• Creating a Custom Vaadin Theme
• Debugging Your Application
• More Exercises
• See Also

To follow this tutorial, you need the following software and resources.

Software or Resource	Version Required
NetBeans IDE	Web and Java EE installation version 6.8
Java Development Kit (JDK)	version 6 or version 5
Vaadin plugin for NetBeans IDE	current version
GlassFish Server Open Source Edition or Tomcat servlet container	2.1.1 or 3.0.1   version 6.x

Installing the Vaadin Plugin

You need to download the Vaadin plugin before you can install it. The Vaadin plugin is available at http://plugins.netbeans.org/PluginPortal/faces/PluginDetailPage.jsp?pluginid=21965. The Vaadin plugin for NetBeans IDE is open-sourced and the plugin project is accessible on Kenai.

To install the Vaadin plugin:

1. Download the Vaadin plugin.
2. Start NetBeans IDE. Go to Tools > Plugins and open the Downloaded tab.
   
3. Click Add Plugins... and browse for the downloaded plugin.
   
4. Select the Vaadin plugin and click Open. You return to the Downloads tab of the Plugins manager, and now the Vaadin Framework plugin is visible. Make certain it is selected and click Install.
   
5. The installer opens. Click through the installer, accepting the licenses and approving the installation of the unsigned Vaadin plugin. When you finish, the Vaadin plugin is installed.

Creating a Java Web Application With Vaadin

In this section, you create a simple Java web application with the Vaadin framework. You explore the structure of the application and test it with a simple Hello, World function.

To create a Java web application with Vaadin:

1. In the IDE, open the New Project wizard (Ctrl-Shift-N). Select the Java Web category and then the Web Application project type. Click Next.
2. Name the project FirstVaadin and assign it to a convenient location in your file system. Click Next.
3. Select EE version 5 and an application server. While it is possible to use Vaadin with EE 6 (see, for example, this Vaadin forum discussion), this tutorial uses EE 5 applications for simplicity.
4. Click Next. The Framework page opens. Select the Vaadin framework. A number of configuration options appear. Accept all the defaults and click Finish.
   

You now have a simple Vaadin web application. Look at the project's structure in the Project window. Note the minimal number of differences between this project and a Java web application project with no framework.

• The Vaadin project does not have a default JSP file.
• Instead, the Vaadin project has a default Java file.
• The Vaadin project includes the Vaadin library.
• No JavaScript or extra XML files have been added.

Open the MyApplication.java file. Note that it imports Vaadin packages that create the UI instead of using a JSP page or something similar.

Run the application. Watch the Output windows of the IDE. Note that the IDE builds the project, starts the GlassFish Server Open Source Edition (if it is not running) and deploys the application to the server. After deployment, a browser window opens, displaying the text "Hello Vaadin User."

Congratulations! You have created and run a simple Vaadin project. In the next section, you'll create a new Vaadin theme.

Creating a Custom Vaadin Theme

According to the Book of Vaadin, "Vaadin separates the appearance of the user interface from its logic using themes. Themes can include CSS style sheets, custom HTML layouts, and any necessary graphics. Theme resources can also be accessed from an application as ThemeResource objects." For more information about themes in Vaadin, see the Themes chapter of the Book of Vaadin.

Vaadin framework 6.1.3 comes with two built-in themes, reindeer and runo. The NetBeans IDE Vaadin Plugin loads these themes dynamically from the vaadin JAR file.

You can add custom themes. First you must create the folder structure VAADIN/themes in the project's Web Pages folder. All custom Vaadin themes must be in the web/VAADIN/themes path. Every theme must contain a stylesheet named styles.css. Except for the path and the stylesheet, you are free to name and structure any other contents as you wish. However, the Vaadin people suggest naming theme subfolders img for images, layouts for custom layouts, and css for additional stylesheets.

In the rest of this section, you create a new theme and set it as the theme for your FirstVaadin project.

To create a custom theme:

1. In the Projects window, right-click the Web Projects folder in the FirstVaadin project. Select New > Folder and create a folder named VAADIN. In the VAADIN folder, create a folder named themes. All custom themes for the project will be in this folder.
   
2. In the themes folder, create a new folder named mytheme. This will contain the files for your new theme.
3. Right-click the mytheme folder and select New > Other > Cascading Style Sheet.
   
4. Click Next. The Name and Location window opens. Name the file styles and click Finish. The New File wizard closes and the new styles.css page opens in the editor.
5. Replace the default contents of the file with the following code and save the file:

   @import "../runo/styles.css";
   /* Import the runo theme for components not described in your CSS files*/
   .v-button {
        display: inline-block;
        zoom: 1;
        text-align: center;
        text-decoration: none;
        border: 2px outset #fff;
        background: #f00;
        cursor: pointer;
        white-space: nowrap;
        margin: 0;
        padding: .2em 1em;
        color: inherit;
        font: inherit;
        line-height: normal;
        -khtml-user-select: none;
        -moz-user-select: none;
        -ie-user-select: none;
        user-select: none;
        -webkit-box-sizing: border-box;
        -moz-box-sizing: border-box;
        -ms-box-sizing: border-box;
        box-sizing: border-box;
   }
   /* this is the Vaadin CSS class for a button client */
   

6. In MyApplication.java, add a button. Add the following code to the init method, after the code that adds the label:

   Button button = new Button("My Button");
   mainWindow.addComponent(button);

7. Run the project. You see the default button format.
   
8. Add a line at the beginning of the init method body that calls the setTheme method. Pass your theme name as the parameter.

   setTheme("mytheme");

9. Run the project again. You see a red button, as set in the CSS for mytheme.
   
10. Run the project with the default runo or reindeer themes to compare the appearance of the button.

Creating a Complex Application

In the following section, you build up your FirstVaadin project into a complex application with a listener event and more Vaadin GUI components.

To create a complex application:

1. Add the class MyFirstWindow to the project. In the Projects window, right-click the com.example.vaadin package and select New > Java class. Name the class MyFirstWindow.
2. Replace the default code in MyFirstWindow with the following code:

   package com.example.vaadin;
   
   
   public class MyFirstWindow extends Window{
       public MyFirstWindow(String windowName){
           this.setCaption("My First Window");
           this.setPositionX(100);
           this.setPositionY(100);
           this.setWidth(500, Window.UNITS_PIXELS);
           this.setHeight(500, Window.UNITS_PIXELS);
           this.addComponent(new Button("Button 1"));
           this.addComponent(new Button("Button 2"));
       }
   }

3. You see a number of warning icons that indicate missing classes. Fix missing imports by pressing Ctrl-Shift-I or by selecting Fix Imports from the context menu. You can open the context menu by right-clicking anywhere in the editor. Note that a dialog opens asking you whether to use Vaadin or Java AWT Button and Window classes. Accept the default Vaadin classes. After you fix the imports, press Alt-Shift-F to format your code.
4. Go back to MyApplication.java in the editor. Replace the MyApplication class with the following code:

   public class MyApplication extends com.vaadin.Application implements Button.ClickListener{
        private Button b;
        public void init() {
            setTheme("mytheme");
            Window main = new Window("Hello NetBeans ");
            setMainWindow(main);
            main.addComponent(new Label("Hello World!"));
            b=new Button("My Button");
            main.addComponent(b);
            b.addListener(this);
        }
   
   	 
   	 //When the client clicks button b, the browser shows a window in the client zone
        public void buttonClick(ClickEvent event) {
            if(event.getButton()==this.b){
            this.getMainWindow().addWindow(new MyFirstWindow("This is my first window!")); 
            }
        }
   }

5. Fix imports, or manually add an import statement for com.vaadin.ui.Button.ClickEvent.
6. Run the project. Click the button in the browser, and the window appears that you defined in MyFirstWindow.
   

That's it! You have a (not very) complex application with a button listener and an event that instantiates another class.

Debugging Your Application

NetBeans IDE includes debugging functionality. In this section you set breakpoints in your application and run it in debug mode.

To debug your application:

1. In the MyApplication class, go to the line Window main = new Window("Hello NetBeans "); and press Ctrl-F8. This adds a breakpoint to the line.
2. Add a breakpoint to the line if(event.getButton()==this.b){. The class in the editor now looks like this:
   
3. If FirstVaadin is your main project, run Ctrl-F5 to run it in debug mode. Otherwise, right-click the FirstVaadin node in the Projects window and select Debug.
4. A dialog opens asking you if you want to debug server-side Java or server-side Java and client-side JavaScript. Select server-side Java and click Debug.
5. The Debugging window opens in the IDE. The IDE output also shows breakpoints and variables, and the hit breakpoint is now green instead of red in the editor.
   
6. Press F5 to continue. When you continue past the first breakpoint, the first button and label appear in the browser. Press the button, and the IDE continues to the next breakpoint, in the buttonClick method.
7. The toolbar above the editor window gives you icons for stepping over, into, out, etc. Explore the application and NetBeans IDE debugger using these functions. You can end the debugging session with Shift-F5.

More Exercises

Here are a few more ideas for you to explore:

• Find an icon to use for your button. Create an img folder in mytheme and save the icon in that folder. Use the icon by adding the line b.setIcon(new ThemeResource("img/<ICON FILE NAME>")); to the init method in MyApplication.
• Use an application like Firefox's Firebug plugin to explore the Vaadin JSON messages.
• Run the Vaadin tutorial using NetBeans IDE.

See Also

For related tutorials, see the following resources:

• Introduction to Developing Web Applications
• The Vaadin Wiki Getting Started on NetBeans IDE tutorial. Note this was written for NetBeans IDE 6.7, which did not have the Vaadin plugin.
• Introduction to the Struts Web Framework
• Introduction to the Spring Web Framework
• Introduction to the Wicket Web Framework
• Introduction to the Google Web Toolkit Framework

And for information on Vaadin, please see the Book of Vaadin and the Vaadin user forum.