Start page
Start page

Start page / Plug-In Development / Universal Extensions / Input Components / ContentCreator / JavaScript Controller (Client)

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.

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

Important ContentCreator identifies if a JavaScript controller supports a certain aspect by checking if all of its functions are available within the controller object.
Important As these aspects are only used in JavaScript, they are not included in the FirstSpirit API documentation.

ContentCreator Gadget Aspects (Client-Side)

Appearance

Aspect

Description

Functions / Notes

Labelable

Provides a label to display next to the input component's form representation.

/**
* @return {string}
*/
function getLabel()

provides the input component's label.

Editing and storing component values

Aspect

Description

Functions / Notes

Editable

Controls whether the gadget's form components are editable or not.

/**
* @param {boolean} editable
*/
function setEditable(boolean editable)

enables (editable == true) or disables (editable == false) form components of the gadget.

ValueHolder

Enables storing the component's data using FirstSpirit's persistence functionality and retrieving such data for display in the component.

/**
* @return {object}
*/
function getValue()

returns the value currently set in the input component in serialized form. This method is used to persist the component's value (e.g. when saving an element).

/**
* @param {object} value
*/
function setValue(value)

configures the input component to show a stored value; should set the input component's fields to reflect the serialized value provided as a parameter.

/**
* @return {boolean}
*/
function isEmpty()

indicates if the currently held value is to be considered empty.

Parameterization:
object is a JSON-compatible object which is compatible with the type <S extends Serializable> with which the server-side gadget aspect SerializingValueHolder is parameterized (see Web Gadget Factory for details about compatible types).

Note:
This client-side aspect requires the server-side gadget to provide an aspect of type SerializingValueHolder<T, S extends Serializable>.

   

© 2005 - 2015 e-Spirit AG | All rights reserved. | Last change: 2014-12-08