8.6. Using a Custom Component

A custom component is used like any other IT Mill Toolkit component. You will, however, need to compile the client-side widget set with the GWT Compiler.

8.6.1. Example: Color Picker Application

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.itmill.toolkit.demo.colorpicker;

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

/**
 * Demonstration application that shows how to use a simple
 * custom client-side GWT component, the ColorPicker.
 */
public class ColorPickerApplication extends com.itmill.toolkit.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);
    }
}

8.6.2. Web Application Deployment

Deployment of web applications that include custom components is almost identical to the normal case where you use only the default widget set of IT Mill Toolkit. The default case is documented in Section 3.7.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.

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.itmill.toolkit.terminal.gwt.server.ApplicationServlet</servlet-class>
        <init-param>
            <param-name>application</param-name>
            <param-value>com.itmill.toolkit.demo.colorpicker.ColorPickerApplication</param-value>
        </init-param>
        <init-param>
            <param-name>widgetset</param-name>
            <param-value>com.itmill.toolkit.demo.colorpicker.gwt.ColorPickerWidgetSet</param-value>
        </init-param>
    </servlet>

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

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

As the project context root in the above example is myproject and the <url-pattern> is /*, the URL for the application will be /myproject/.