/* * Copyright 2000-2013 Vaadin Ltd. * * Licensed under the Apache License, Version 2.0 (the "License"); you may not * use this file except in compliance with the License. You may obtain a copy of * the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and limitations under * the License. */ package com.vaadin.ui; import com.vaadin.server.JavaScriptCallbackHelper; import com.vaadin.shared.communication.ServerRpc; import com.vaadin.shared.ui.JavaScriptComponentState; /** * 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 (
* {@link com.vaadin.client.ui.JavaScriptWidget} ) just consisting of a
* div
element to which the JavaScript code should initialize its
* own user interface.
*
* The initialization function will be called with this
pointing to
* a connector wrapper object providing integration to Vaadin with the following
* functions:
*
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
* {@link com.vaadin.client.ApplicationConnection#translateVaadinUri(String)}onStateChange
- If the JavaScript code assigns a function to
* the field, that function is called whenever the contents of the shared state
* is changed.* * Values in the Shared State and in RPC calls are converted between Java and * JavaScript using the following conventions: *
this
). Calling that JavaScript function will
* cause the call method in the registered {@link JavaScriptFunction} to be
* invoked with the same arguments.
*
* @param functionName
* the name that should be used for client-side function
* @param function
* the {@link JavaScriptFunction} object that will be invoked
* when the JavaScript function is called
*/
protected void addFunction(String functionName, JavaScriptFunction function) {
callbackHelper.registerCallback(functionName, function);
}
/**
* Invoke a named function that the connector JavaScript has added to the
* JavaScript connector wrapper object. The arguments should only contain
* data types that can be represented in JavaScript including primitives,
* their boxed types, arrays, String, List, Set, Map, Connector and
* JavaBeans.
*
* @param name
* the name of the function
* @param arguments
* function arguments
*/
protected void callFunction(String name, Object... arguments) {
callbackHelper.invokeCallback(name, arguments);
}
@Override
protected JavaScriptComponentState getState() {
return (JavaScriptComponentState) super.getState();
}
}