JavaScript Controller

The JavaScript controller provides client-side implementations (running in ContentCreator's JavaScript-based environment) of the functionality specified by the web gadget class and the aspects that class provides.

The JavaScript controller object must be defined as a property of the window object (e.g. window.MyExampleController), and the controller object's name must match that provided by the web gadget factory class' method String getControllerName().

Constructing a JavaScript Controller Object

In order to register a JavaScript controller object, one of the JavaScript URLs referenced in List<String> WebPluginGadgetFactory#getScriptUrls() (see Web Gadget Factory) must provide code which constructs that controller object.

An example controller constructor may look as follows:

window.ExampleController = function(webHost, configuration) {

    var self = this;

    this.webHost = webHost;
    this.configuration = configuration;
    this.editable = false;

    // Functionality executed once the controller object has been constructed.
    this.onLoad = function() {

        // Listener function for form input element changes, notifies the web host object that data has changed.
        function onChange() {
            self.webHost.onModification();
        }

        // Register the listener for key-up and change events on the form input element.
        self.getField().onkeyup = onChange;
        self.getField().onchange = onChange;

        // Set the form input element to an initial editability state ('false', see above).
        self.getField().disabled = !self.editable;
    };

    // Obtain the field (a form input component) from the DOM.
    // NOTE: always use webHost.getElementById(...) to obtain fields, as element IDs are modified to avoid collisions.
    function getField() {
        return webHost.getElementById("text_form_field");
    }

    // Aspect functions
    // NOTE: These aspects are not documented in the FirstSpirit APIs as they are not implementable interfaces.

    // Aspect: ValueHolder

    // Obtain the gadget's current value.
    this.getValue = function() {
        return getField().value;
    };

    // Set the gadget's current value.
    this.setValue = function(value) {
        getField().value = value;
    };

    // Determine if the gadget is currently empty.
    this.isEmpty = function() {
        return getField().value;
    };

    // Aspect: Labelable

    // Obtain the input component's label.
    this.getLabel = function() {
        return this.configuration.label;
    }

    // Aspect: Editable

    // Set editability status of the input component's UI.
    this.setEditable = function(enable) {
        self.editable = enable;
        getField().disabled = !enable;
    };
};

The resulting controller object in this example (window.ExampleController) is thus configured to support the client-side gadget aspects ValueHolder, Labelable, and Editable (see Client-Side Gadget Aspects below) by providing JavaScript functions which are counterparts of the aspects' Java method implementations. The functions operate on a form input component with the ID text_form_field or its value, respectively.

In order to obtain elements from the DOM by ID, always use the webHost object's function getElementById(...)! The JavaScript function document.getElementById(...) will not be able to resolve IDs of HTML elements added through the web gadget factory. See HTML, CSS, and JavaScript for details.

Reacting to Form Input

In order to update the server-side gadget's value and perform tasks such as input validation, the JavaScript controller should specify a listener method which is registered to events which indicate that an input form element's value has changed or some other activity has occurred. That listener function should then call the web host object's function onModification(), which takes care of polling for the gadget's current value.

In the above example, the controller object features a function onLoad() which defines a listener function onChange() and registers that listener with the sole form input element's onkeyup and onchange events. These events now call the listener function whenever a keypress has ended while the form input element has focus and whenever the value of the form input element has been changed, respectively.

Client-Side Gadget Aspects

The JavaScript controller may support a number of aspects which provide additional functionality within the JavaScript-based client user interface. These aspects are separate from the aspects which may be provided by the server-side gadget class, however, some of them require both server-side and client-side implementations.

ContentCreator identifies if a JavaScript controller supports a certain aspect by checking if all of its functions are available within the controller object.

As these aspects are only used in JavaScript, they are not included in the FirstSpirit API documentation.