Integrating JavaScript Components and Extensions

    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.

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

    2.         src="mylibrary.js"></script>

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

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

    A JavaScript Component Example

    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.

    1. final MyComponent mycomponent = new MyComponent();
    3. // Set the value from server-side
    4. mycomponent.setValue("Server-side value");
    6. // Process a value input by the user from the client-side
    7. mycomponent.addValueChangeListener(
    8.         new MyComponent.ValueChangeListener() {
    9.     @Override
    10.         Notification.show("Value: " + mycomponent.getValue());
    11.     }
    12. });

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

    1. package com.vaadin.book.examples.client.js;
    3. @JavaScript({"mylibrary.js", "mycomponent-connector.js"})
    4. public class MyComponent extends AbstractJavaScriptComponent {
    5.     public interface ValueChangeListener extends Serializable {
    6.         void valueChange();
    7.     }
    8.     ArrayList<ValueChangeListener> listeners =
    9.             new ArrayList<ValueChangeListener>();
    10.     public void addValueChangeListener(
    11.                    ValueChangeListener listener) {
    12.         listeners.add(listener);
    13.     }
    15.     public void setValue(String value) {
    16.         getState().value = value;
    17.     }
    19.     public String getValue() {
    20.         return getState().value;
    21.     }
    23.     @Override
    24.     protected MyComponentState getState() {
    25.     }

    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:

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

    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?

    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.

    1. window.com_vaadin_book_examples_client_js_MyComponent =
    2. function() {
    3.     // Create the component
    4.     var mycomponent =
    5.         new mylibrary.MyComponent(this.getElement());
    7.     // Handle changes from the server-side
    8.     this.onStateChange = function() {
    9.         mycomponent.setValue(this.getState().value);
    10.     };
    12.     // Pass user interaction to the server-side
    13.     var self = this;
    14.     mycomponent.click = function() {
    15.         self.onClick(mycomponent.getValue());
    16.     };
    17. };

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

    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”.

    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.

    1. public MyComponent() {
    2.     addFunction("onClick", new JavaScriptFunction() {
    3.         @Override
    4.         public void call(JsonArray arguments) {
    5.             getState().setValue(arguments.getString(0));
    6.             for (ValueChangeListener listener: listeners)
    7.                 listener.valueChange();
    8.         }
    9.     });

    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):

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