A custom component is used like any other Vaadin component. You will, however, need to compile the client-side widget set with the GWT Compiler. See Section 11.8.4, “Compiling GWT Widget Sets” for instructions on how to compile widget sets.

The following server-side example application shows how to use the Color Picker custom widget. The example includes also server-side feedback of the user input and changing the color selection to show that the communication of the component state works in both directions.

package com.vaadin.demo.colorpicker;

import com.vaadin.data.Property.ValueChangeEvent;
import com.vaadin.data.Property.ValueChangeListener;
import com.vaadin.ui.*;
import com.vaadin.ui.Button.ClickEvent;

/**
 * Demonstration application that shows how to use a simple
 * custom client-side GWT component, the ColorPicker.
 */
public class ColorPickerApplication
       extends com.vaadin.Application {
    Window main = new Window("Color Picker Demo");
    
    /* The custom component. */
    ColorPicker colorselector = new ColorPicker();
    
    /* Another component. */
    Label colorname;
    
    public void init() {
        setMainWindow(main);
        setTheme("demo");
        
        // Listen for value change events in the custom
        // component, triggered when user clicks a button
        // to select another color.
        colorselector.addListener(new ValueChangeListener() {
            public void valueChange(ValueChangeEvent event) {
                // Provide some server-side feedback
                colorname.setValue("Selected color: " + 
                                   colorselector.getColor());
            }
        });
        main.addComponent(colorselector);
        
        // Add another component to give feedback from
        // server-side code
        colorname = new Label("Selected color: " +
                              colorselector.getColor());
        main.addComponent(colorname);
        
        // Server-side manipulation of the component state
        Button button = new Button("Set to white");
        button.addListener(new Button.ClickListener() {
            public void buttonClick(ClickEvent event) {
                colorselector.setColor("white");
            }
        });
        main.addComponent(button);
    }
}

Deployment of web applications that include custom components is almost identical to the normal case where you use only the default widget set of Vaadin. The default case is documented in Section 4.8.3, “Deployment Descriptor web.xml. You only need to specify the widget set for the application in the WebContent/WEB-INF/web.xml deployment descriptor.

If you use the Vaadin Plugin for Eclipse to create a new widget in your project, the plugin will modify the deployment descriptor to use the custom widget set.

The following deployment descriptor specifies the Color Picker Application detailed in the previous section.

<?xml version="1.0" encoding="UTF-8"?>
<web-app
  id="WebApp_ID"
  version="2.4"
  xmlns="http://java.sun.com/xml/ns/j2ee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
           http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <display-name>myproject</display-name>

    <servlet>
        <servlet-name>ColorPickerServlet</servlet-name>
        <servlet-class>
            com.vaadin.terminal.gwt.server.ApplicationServlet
        </servlet-class>
        <init-param>
            <param-name>application</param-name>
            <param-value>
                com.vaadin.demo.colorpicker.ColorPickerApplication
            </param-value>
        </init-param>
        <init-param>
            <param-name>widgetset</param-name>
            <param-value>
                com.vaadin.demo.colorpicker.widgetset.ColorPickerWidgetSet
            </param-value>
        </init-param>
    </servlet>

    <servlet-mapping>
        <servlet-name>ColorPickerServlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

The project specific parameters are emphasized. Notice that the widget set name is not a file name, but the base name for the ColorPickerWidgetSet.gwt.xml module descriptor.

The Eclipse Plugin will automatically generate the init-param parameter in the web.xml file of your project when you create a new widget.

As the project context root in the above example is myproject and the <url-pattern> is /*, the URL for the application will be /myproject/. If you are using an URL pattern such as /myapp/*, you need to make an additional mapping to map requests to /VAADIN/* context to the same servlet. Otherwise the default widget set and built-in themes in Vaadin will be missing.

  <servlet-mapping>
    <servlet-name>Book of Vaadin Examples</servlet-name>
    <url-pattern>/VAADIN/*</url-pattern>
  </servlet-mapping>