Integrating JavaScript Components and Extensions

Vaadin allows simplified integration of pure JavaScript components, as well as component and UI extensions. The JavaScript connector code is published from the server-side. As the JavaScript integration does not involve GWT programming, no widget set compilation is needed.

Example JavaScript Library

There are many kinds of component libraries for JavaScript. In the following, we present a simple library that provides one object-oriented JavaScript component. We use this example later to show how to integrate it with a server-side Vaadin component.

The example library includes a single MyComponent component, defined in mylibrary.js.

// Define the namespace
var mylibrary = mylibrary || {};
mylibrary.MyComponent = function (element) {
    element.innerHTML =
        "<div class='caption'>Hello, world!</div>" +
        "<div class='textinput'>Enter a value: " +
        "<input type='text' name='value'/>" +
        "<input type='button' value='Click'/>" +
        "</div>";
    // Style it
    element.style.border = "thin solid red";
    element.style.display = "inline-block";
    // Getter and setter for the value property
    this.getValue = function () {
        return element.
            getElementsByTagName("input")[0].value;
    };
    this.setValue = function (value) {
        element.getElementsByTagName("input")[0].value =
            value;
    };
    // Default implementation of the click handler
    this.click = function () {
        alert("Error: Must implement click() method");
    };
    // Set up button click
    var button = element.getElementsByTagName("input")[1];
    var self = this; // Can't use this inside the function
    button.onclick = function () {
        self.click();
    };
};

When used in an HTML page, the library would be included with the following definition:

<script type="text/javascript"
        src="mylibrary.js"></script>

You could then use it anywhere in the HTML document as follows:

<!-- Placeholder for the component -->
<div id="foo"></div>
<!-- Create the component and bind it to the placeholder -->
<script type="text/javascript">
    window.foo = new mylibrary.MyComponent(
            document.getElementById("foo"));
    window.foo.click = function () {
        alert("Value is " + this.getValue());
    }
</script>

A JavaScript Component Example

You could interact with the component with JavaScript for example as follows:

<a href="javascript:foo.setValue('New value')">Click here</a>

A Server-Side API for a JavaScript Component

To begin integrating such a JavaScript component, you would need to sketch a bit how it would be used from a server-side Vaadin application. The component should support writing the value as well as listening for changes to it.

final MyComponent mycomponent = new MyComponent();
// Set the value from server-side
mycomponent.setValue("Server-side value");
// Process a value input by the user from the client-side
mycomponent.addValueChangeListener(
        new MyComponent.ValueChangeListener() {
    @Override
    public void valueChange() {
        Notification.show("Value: " + mycomponent.getValue());
    }
});
layout.addComponent(mycomponent);

Basic Server-Side Component

A JavaScript component extends the AbstractJavaScriptComponent, which handles the shared state and RPC for the component.

package com.vaadin.book.examples.client.js;
@JavaScript({"mylibrary.js", "mycomponent-connector.js"})
public class MyComponent extends AbstractJavaScriptComponent {
    public interface ValueChangeListener extends Serializable {
        void valueChange();
    }
    ArrayList<ValueChangeListener> listeners =
            new ArrayList<ValueChangeListener>();
    public void addValueChangeListener(
                   ValueChangeListener listener) {
        listeners.add(listener);
    }
    public void setValue(String value) {
        getState().value = value;
    }
    public String getValue() {
        return getState().value;
    }
    @Override
    protected MyComponentState getState() {
        return (MyComponentState) super.getState();
    }
}

Notice later when creating the JavaScript connector that its name must match the package name of this server-side class.

The shared state of the component is as follows:

public class MyComponentState extends JavaScriptComponentState {
    public String value;
}

If the member variables are private, you need to have public setters and getters for them, which you can use in the component.

Defining a JavaScript Connector

A JavaScript connector is a function that initializes the JavaScript component and handles communication between the server-side and the JavaScript code.//TOD Clarify - code?

A connector is defined as a connector initializer function that is added to the window object. The name of the function must match the server-side class name, with the full package path. Instead of the Java dot notation for the package name, underscores need to be used as separators.

The Vaadin client-side framework adds a number of methods to the connector function. The this.getElement() method returns the HTML DOM element of the component. The this.getState() returns a shared state object with the current state as synchronized from the server-side.

window.com_vaadin_book_examples_client_js_MyComponent =
function() {
    // Create the component
    var mycomponent =
        new mylibrary.MyComponent(this.getElement());
    // Handle changes from the server-side
    this.onStateChange = function() {
        mycomponent.setValue(this.getState().value);
    };
    // Pass user interaction to the server-side
    var self = this;
    mycomponent.click = function() {
        self.onClick(mycomponent.getValue());
    };
};

In the above example, we pass user interaction using the JavaScript RPC mechanism, as described in the next section.

RPC from JavaScript to Server-Side

User interaction with the JavaScript component has to be passed to the server-side using an RPC (Remote Procedure Call) mechanism. The JavaScript RPC mechanism is almost equal to regular client-side widgets, as described in “RPC Calls Between Client- and Server-Side”.

Handling RPC Calls on the Server-Side

Let us begin with the RPC function registration on the server-side. RPC calls are handled on the server-side in function handlers that implement the JavaScriptFunction interface. A server-side function handler is registered with the addFunction() method in AbstractJavaScriptComponent. The server-side registration actually defines a JavaScript method that is available in the client-side connector object.

Continuing from the server-side MyComponent example we defined earlier, we add a constructor to it that registers the function.

public MyComponent() {
    addFunction("onClick", new JavaScriptFunction() {
        @Override
        public void call(JsonArray arguments) {
            getState().setValue(arguments.getString(0));
            for (ValueChangeListener listener: listeners)
                listener.valueChange();
        }
    });
}

Making an RPC Call from JavaScript

An RPC call is made simply by calling the RPC method in the connector. In the constructor function of the JavaScript connector, you could write as follows (the complete connector code was given earlier):

window.com_vaadin_book_examples_gwt_js_MyComponent =
    function() {
        ...
        var connector = this;
        mycomponent.click = function() {
            connector.onClick(mycomponent.getValue());
        };
    };

Here, the mycomponent.click is a function in the example JavaScript library, as described in Example JavaScript Library. The onClick() is the method we defined on the server-side. We pass a simple string parameter in the call.

You can pass anything that is valid in JSON notation in the parameters.