com.vaadin.ui

Class AbstractJavaScriptComponent

java.lang.Object

com.vaadin.server.AbstractClientConnector

com.vaadin.ui.AbstractComponent

com.vaadin.ui.AbstractJavaScriptComponent

All Implemented Interfaces:

ContextClickEvent.ContextClickNotifier, MethodEventSource, ClientConnector, Sizeable, Connector, Component, Serializable

public abstract class AbstractJavaScriptComponent
extends AbstractComponent

Base class for Components with all client-side logic implemented using JavaScript.

When a new JavaScript component is initialized in the browser, the framework will look for a globally defined JavaScript function that will initialize the component. The name of the initialization function is formed by replacing . with _ in the name of the server-side class. If no such function is defined, each super class is used in turn until a match is found. The framework will thus first attempt with com_example_MyComponent for the server-side com.example.MyComponent extends AbstractJavaScriptComponent class. If MyComponent instead extends com.example.SuperComponent , then com_example_SuperComponent will also be attempted if com_example_MyComponent has not been defined.

JavaScript components have a very simple GWT widget ( JavaScriptWidget ) just consisting of a single element (a div by default) to which the JavaScript code should initialize its own user interface. The tag can be overridden by defining a string named com_example_MyComponent.tag. If no tag has been defined, a tag defined in a super class will be located in the same manner as with the init function.

For example, to create a component (my.package.Span) with the DOM <span>some text</span>, taking the span text from the state, the JavaScript would be:

 
my_package_Span = function() {
  this.onStateChange = function() {
    this.getElement().innerText = this.getState().text;
  }
}
my_package_Span.tag = "span";

 

The initialization function will be called with this pointing to a connector wrapper object providing integration to Vaadin. Please note that in JavaScript, this is not necessarily defined inside callback functions and it might therefore be necessary to assign the reference to a separate variable, e.g. var self = this;. The following functions are provided by the connector wrapper object:

• getConnectorId() - returns a string with the id of the connector.
• getParentId([connectorId]) - returns a string with the id of the connector's parent. If connectorId is provided, the id of the parent of the corresponding connector with the passed id is returned instead.
• getElement([connectorId]) - returns the DOM Element that is the root of a connector's widget. null is returned if the connector can not be found or if the connector doesn't have a widget. If connectorId is not provided, the connector id of the current connector will be used.
• getState() - returns an object corresponding to the shared state defined on the server. The scheme for conversion between Java and JavaScript types is described bellow.
• registerRpc([name, ] rpcObject) - registers the rpcObject as a RPC handler. rpcObject should be an object with field containing functions for all eligible RPC functions. If name is provided, the RPC handler will only used for RPC calls for the RPC interface with the same fully qualified Java name. If no name is provided, the RPC handler will be used for all incoming RPC invocations where the RPC method name is defined as a function field in the handler. The scheme for conversion between Java types in the RPC interface definition and the JavaScript values passed as arguments to the handler functions is described bellow.
• getRpcProxy([name]) - returns an RPC proxy object. If name is provided, the proxy object will contain functions for all methods in the RPC interface with the same fully qualified name, provided a RPC handler has been registered by the server-side code. If no name is provided, the returned RPC proxy object will contain functions for all methods in all RPC interfaces registered for the connector on the server. If the same method name is present in multiple registered RPC interfaces, the corresponding function in the RPC proxy object will throw an exception when called. The scheme for conversion between Java types in the RPC interface and the JavaScript values that should be passed to the functions is described bellow.
• translateVaadinUri(uri) - Translates a Vaadin URI to a URL that can be used in the browser. This is just way of accessing ApplicationConnection.translateVaadinUri(String)
• addResizeListener(element, callbackFunction) - Registers a listener that gets notified whenever the size of the provided element changes. The listener is called with one parameter: an event object with the element property pointing to the element that has been resized.
• removeResizeListener(element, callbackFunction) - Unregisters a combination of an element and a listener that has previously been registered using addResizeListener. All registered listeners are automatically unregistered when this connector is unregistered, but this method can be use to to unregister a listener at an earlier point in time.

The connector wrapper also supports these special functions:

• onStateChange - If the JavaScript code assigns a function to the field, that function is called whenever the contents of the shared state is changed.
• onUnregister - If the JavaScript code assigns a function to the field, that function is called when the connector has been unregistered.
• Any field name corresponding to a call to addFunction(String, JavaScriptFunction) on the server will automatically be present as a function that triggers the registered function on the server.
• Any field name referred to using callFunction(String, Object...) on the server will be called if a function has been assigned to the field.

Values in the Shared State and in RPC calls are converted between Java and JavaScript using the following conventions:

• Primitive Java numbers (byte, char, int, long, float, double) and their boxed types (Byte, Character, Integer, Long, Float, Double) are represented by JavaScript numbers.
• The primitive Java boolean and the boxed Boolean are represented by JavaScript booleans.
• Java Strings are represented by JavaScript strings.
• Java Dates are represented by JavaScript numbers containing the timestamp
• List, Set and all arrays in Java are represented by JavaScript arrays.
• Map<String, ?> in Java is represented by JavaScript object with fields corresponding to the map keys.
• Any other Java Map is represented by a JavaScript array containing two arrays, the first contains the keys and the second contains the values in the same order.
• A Java Bean is represented by a JavaScript object with fields corresponding to the bean's properties.
• A Java Connector is represented by a JavaScript string containing the connector's id.
• A pluggable serialization mechanism is provided for types not described here. Please refer to the documentation for specific types for serialization information.

Since:

7.0.0

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.vaadin.ui.Component

Component.ErrorEvent, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener

Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable

Sizeable.Unit

Field Summary

Fields inherited from class com.vaadin.ui.AbstractComponent

DESIGN_ATTR_PLAIN_TEXT

Fields inherited from interface com.vaadin.server.Sizeable

SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS

Constructor Summary

Constructors

Constructor and Description
AbstractJavaScriptComponent()

Method Summary

Modifier and Type	Method and Description
protected void	addFunction(String functionName, JavaScriptFunction function) Register a JavaScriptFunction that can be called from the JavaScript using the provided name.
protected void	callFunction(String name, Object... arguments) Invoke a named function that the connector JavaScript has added to the JavaScript connector wrapper object.
protected JavaScriptComponentState	getState() Returns the shared state bean with information to be sent from the server to the client.
protected JavaScriptComponentState	getState(boolean markAsDirty) Returns the shared state for this connector.
protected <T extends ServerRpc> void	registerRpc(T implementation, Class<T> rpcInterfaceType) Registers an RPC interface implementation for this component.

Methods inherited from class com.vaadin.ui.AbstractComponent

addContextClickListener, addListener, addShortcutListener, addStyleName, attach, beforeClientResponse, detach, findAncestor, fireComponentErrorEvent, fireComponentEvent, focus, getActionManager, getCaption, getComponentError, getCustomAttributes, getData, getDebugId, getDescription, getErrorMessage, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isOrHasAncestor, isReadOnly, isRequiredIndicatorVisible, isResponsive, isVisible, readDesign, removeContextClickListener, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setDescription, setEnabled, setHeight, setHeight, setHeightUndefined, setIcon, setId, setLocale, setParent, setPrimaryStyleName, setReadOnly, setRequiredIndicatorVisible, setResponsive, setSizeFull, setSizeUndefined, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined, writeDesign

Methods inherited from class com.vaadin.server.AbstractClientConnector

addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirty, markAsDirtyRecursive, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource, updateDiffstate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.ui.Component

addStyleNames, getUI, removeStyleNames, setStyleName

Methods inherited from interface com.vaadin.server.ClientConnector

addAttachListener, addDetachListener, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Constructor Detail

AbstractJavaScriptComponent

public AbstractJavaScriptComponent()

Method Detail

registerRpc

protected <T extends ServerRpc> void registerRpc(T implementation,
                                                 Class<T> rpcInterfaceType)

Description copied from class: AbstractClientConnector

Registers an RPC interface implementation for this component. A component can listen to multiple RPC interfaces, and subclasses can register additional implementations.

Overrides:

registerRpc in class AbstractClientConnector

Parameters:

implementation - RPC interface implementation

rpcInterfaceType - RPC interface class for which the implementation should be registered

addFunction

protected void addFunction(String functionName,
                           JavaScriptFunction function)

Register a JavaScriptFunction that can be called from the JavaScript using the provided name. A JavaScript function with the provided name will be added to the connector wrapper object (initially available as this). Calling that JavaScript function will cause the call method in the registered JavaScriptFunction to be invoked with the same arguments.

Parameters:

functionName - the name that should be used for client-side function

function - the JavaScriptFunction object that will be invoked when the JavaScript function is called

callFunction

protected void callFunction(String name,
                            Object... arguments)

Invoke a named function that the connector JavaScript has added to the JavaScript connector wrapper object. The arguments can be any boxed primitive type, String, JsonValue or arrays of any other supported type. Complex types (e.g. List, Set, Map, Connector or any JavaBean type) must be explicitly serialized to a JsonValue before sending. This can be done either with JsonCodec.encode(Object, JsonValue, java.lang.reflect.Type, com.vaadin.ui.ConnectorTracker) or using the factory methods in Json.

Parameters:

name - the name of the function

arguments - function arguments

getState

protected JavaScriptComponentState getState()

Description copied from class: AbstractComponent

Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().

Overrides:

getState in class AbstractComponent

Returns:

updated component shared state

getState

protected JavaScriptComponentState getState(boolean markAsDirty)

Description copied from class: AbstractClientConnector

Returns the shared state for this connector.

Overrides:

getState in class AbstractComponent

Parameters:

markAsDirty - true if the connector should automatically be marked dirty, false otherwise

Returns:

The shared state for this connector. Never null.

See Also:

AbstractClientConnector.getState()