com.vaadin.ui.renderers.AbstractJavaScriptRenderer Maven / Gradle / Ivy
/*
* Copyright (C) 2000-2024 Vaadin Ltd
*
* This program is available under Vaadin Commercial License and Service Terms.
*
* See for the full
* license.
*/
package com.vaadin.ui.renderers;
import com.vaadin.server.AbstractJavaScriptExtension;
import com.vaadin.server.JavaScriptCallbackHelper;
import com.vaadin.server.JsonCodec;
import com.vaadin.shared.JavaScriptExtensionState;
import com.vaadin.shared.communication.ServerRpc;
import com.vaadin.ui.JavaScriptFunction;
import elemental.json.Json;
import elemental.json.JsonValue;
/**
* Base class for Renderers with all client-side logic implemented using
* JavaScript.
*
* When a new JavaScript renderer is initialized in the browser, the framework
* will look for a globally defined JavaScript function that will initialize the
* renderer. 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_MyRenderer for the
* server-side
* com.example.MyRenderer extends AbstractJavaScriptRenderer class.
* If MyRenderer instead extends com.example.SuperRenderer , then
* com_example_SuperRenderer will also be attempted if
* com_example_MyRenderer has not been defined.
*
*
* In addition to the general JavaScript extension functionality explained in
* {@link AbstractJavaScriptExtension}, this class also provides some
* functionality specific for renderers.
*
* 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;. In addition to the
* extension functions described for {@link AbstractJavaScriptExtension}, the
* connector wrapper object also provides this function:
*
* getRowKey(rowIndex) - Gets a unique identifier for the row
* at the given index. This identifier can be used on the server to retrieve the
* corresponding ItemId using {@code getItem(String)}.
* The connector wrapper also supports these special functions that can be
* implemented by the connector:
*
* render(cell, data) - Callback for rendering the given data
* into the given cell. The structure of cell and data are described in separate
* sections below. The renderer is required to implement this function.
* Corresponds to
* {@code com.vaadin.client.renderers.Renderer#render(com.vaadin.client.widget.grid.RendererCellReference, Object)}.init(cell) - Prepares a cell for rendering. Corresponds to
* {@code com.vaadin.client.renderers.ComplexRenderer#init(com.vaadin.client.widget.grid.RendererCellReference)}.destroy(cell) - Allows the renderer to release resources
* allocate for a cell that will no longer be used. Corresponds to
* {@code com.vaadin.client.renderers.ComplexRenderer#destroy(com.vaadin.client.widget.grid.RendererCellReference)}.onActivate(cell) - Called when the cell is activated by the
* user e.g. by double clicking on the cell or pressing enter with the cell
* focused. Corresponds to
* {@code com.vaadin.client.renderers.ComplexRenderer#onActivate(com.vaadin.client.widget.grid.CellReference)}.getConsumedEvents() - Returns a JavaScript array of event
* names that should cause onBrowserEvent to be invoked whenever an event is
* fired for a cell managed by this renderer. Corresponds to
* {@code com.vaadin.client.renderers.ComplexRenderer#getConsumedEvents()}.onBrowserEvent(cell, event) - Called by Grid when an event
* of a type returned by getConsumedEvents is fired for a cell managed by this
* renderer. Corresponds to
* {@code com.vaadin.client.renderers.ComplexRenderer#onBrowserEvent(com.vaadin.client.widget.grid.CellReference, com.google.gwt.dom.client.NativeEvent)}.
*
*
* The cell object passed to functions defined by the renderer has these
* properties:
*
* element - The DOM element corresponding to this cell.
* Readonly.rowIndex - The current index of the row of this cell.
* Readonly.columnIndex - The current index of the column of this cell.
* Readonly.colSpan - The number of columns spanned by this cell. Only
* supported in the object passed to the render function - other
* functions should not use the property. Readable and writable.
*
*
* @param
* the grid type this renderer can be attached to
* @param
* the type this renderer knows how to present
*
* @author Vaadin Ltd
* @since 8.0
*/
public abstract class AbstractJavaScriptRenderer
extends AbstractRenderer {
private JavaScriptCallbackHelper callbackHelper = new JavaScriptCallbackHelper(
this);
protected AbstractJavaScriptRenderer(Class presentationType,
String nullRepresentation) {
super(presentationType, nullRepresentation);
}
protected AbstractJavaScriptRenderer(Class presentationType) {
super(presentationType, null);
}
@Override
protected void registerRpc(R implementation,
Class rpcInterfaceType) {
super.registerRpc(implementation, rpcInterfaceType);
callbackHelper.registerRpc(rpcInterfaceType);
}
/**
* Register a {@link 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 {@link JavaScriptFunction} to be
* invoked with the same arguments.
*
* @param functionName
* the name that should be used for client-side callback
* @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 can be any boxed
* primitive type, String, {@link 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 {@link JsonValue}
* before sending. This can be done either with
* {@link JsonCodec#encode(Object, JsonValue, java.lang.reflect.Type, com.vaadin.ui.ConnectorTracker)}
* or using the factory methods in {@link Json}.
*
* @param name
* the name of the function
* @param arguments
* function arguments
*/
protected void callFunction(String name, Object... arguments) {
callbackHelper.invokeCallback(name, arguments);
}
@Override
protected JavaScriptExtensionState getState() {
return (JavaScriptExtensionState) super.getState();
}
@Override
protected JavaScriptExtensionState getState(boolean markAsDirty) {
return (JavaScriptExtensionState) super.getState(markAsDirty);
}
}