From bfe2385e9a0758bbb609d97380cea09cf15b02f0 Mon Sep 17 00:00:00 2001
From: Erik Lumme <erik@vaadin.com>
Date: Tue, 12 Sep 2017 12:04:00 +0300
Subject: [PATCH] Migrate UsingRPCFromJavaScript

---
 .../articles/UsingRPCFromJavaScript.asciidoc  | 108 ++++++++++++++++++
 documentation/articles/contents.asciidoc      |   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 documentation/articles/UsingRPCFromJavaScript.asciidoc

diff --git a/documentation/articles/UsingRPCFromJavaScript.asciidoc b/documentation/articles/UsingRPCFromJavaScript.asciidoc
new file mode 100644
index 0000000000..c4bfea9bb9
--- /dev/null
+++ b/documentation/articles/UsingRPCFromJavaScript.asciidoc
@@ -0,0 +1,108 @@
+[[using-rpc-from-javascript]]
+Using RPC from JavaScript
+-------------------------
+
+This tutorial continues where
+link:IntegratingAJavaScriptComponent.asciidoc[Integrating a JavaScript
+component] ended. We will now add RPC functionality to the JavaScript
+Flot component. RPC can be used in the same way as with ordinary GWT
+components.
+
+We will add RPC from the client to the server when the user clicks a
+data point in the graph and RPC from server to client for highlighting a
+data point in the graph. For each of these, we define an RPC interface.
+Each interface has one method that takes a data series index and the
+index of a point in that series. As with the shared state, the GWT code
+doesn't need to know about these interfaces and it's thus not required
+to put them in the widgetset's client package and to recompile the
+widgetset after making changes.
+
+[source,java]
+....
+public interface FlotClickRpc extends ServerRpc {
+  public void onPlotClick(int seriesIndex, int dataIndex);
+}
+
+public interface FlotHighlightRpc extends ClientRpc {
+  public void highlight(int seriesIndex, int dataIndex);
+}
+....
+
+The server side code for this looks the same as if the client-side
+connector was implemented using GWT. An RPC implementation is registered
+in the constructor.
+
+[source,java]
+....
+public Flot() {
+  registerRpc(new FlotClickRpc() {
+    public void onPlotClick(int seriesIndex, int dataIndex) {
+      Notification.show("Clicked on [" + seriesIndex + ", "
+            + dataIndex + "]");
+    }
+  });
+}
+....
+
+Highlighting is implemented by getting an RPC proxy object and invoking
+the method.
+
+[source,java]
+....
+public void highlight(int seriesIndex, int dataIndex) {
+  getRpcProxy(FlotHighlightRpc.class).highlight(seriesIndex, dataIndex);
+}
+....
+
+The JavaScript connector uses similar functions from the connector
+wrapper: `this.getRpcProxy()` for getting an object with functions that
+will call the server-side counterpart and `this.registerRpc()` for
+registering an object with functions that will be called from the
+server. Because of the dynamic nature of JavaScript, you don't need to
+use the interface names if you don't want to - all methods from all RPC
+interfaces registered for the connector on the server will be available
+in the RPC proxy object and any RPC method invoked from the server will
+be called if present in the RPC object you registered. If a connector
+uses multiple RPC interfaces that define methods with conflicting names,
+you can still use the interface names to distinguish between interfaces.
+
+We need to make some small adjustments to the connector JavaScript to
+make it work with the way Flot processes events. Because a new Flot
+object is created each time the `onStateChange` function is called, we
+need to store a reference to the current object that we can use for
+applying the highlight. We also need to pass a third parameter to
+`$.plot` to make the graph area clickable. Aside from those changes, we
+just call the function on the RPC proxy in a click listener and register
+an RPC implementation with a function that highlights a point.
+
+[source,javascript]
+....
+window.com_example_Flot = function() {
+  var element = $(this.getElement());
+  var rpcProxy = this.getRpcProxy();
+  var flot;
+
+  this.onStateChange = function() {
+    flot = $.plot(element, this.getState().series, {grid: {clickable: true}});
+  }
+
+  element.bind('plotclick', function(event, point, item) {
+    if (item) {
+      rpcProxy.onPlotClick(item.seriesIndex, item.dataIndex);
+    }
+  });
+
+  this.registerRpc({
+    highlight: function(seriesIndex, dataIndex) {
+      if (flot) {
+        flot.highlight(seriesIndex, dataIndex);
+      }
+    }
+  });
+}
+....
+
+When the normal Vaadin RPC is used with JavaScript connectors, you can
+use the same server-side code that you would use with a GWT connector
+and the client-side code uses the same concepts as for GWT connectors,
+just translated to fit into the world of JavaScript.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 504cdcd33a..2efd9491c7 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -48,4 +48,5 @@ are great, too.
 - link:IntegratingAJavaScriptLibraryAsAnExtension.asciidoc[Integrating a JavaScript library as an extension]
 - link:UsingAJavaScriptLibraryOrAStyleSheetInAnAddOn.asciidoc[Using a JavaScript library or a style sheet in an add-on]
 - link:ExposingServerSideAPIToJavaScript.asciidoc[Exposing server-side API to JavaScript]
+- link:UsingRPCFromJavaScript.asciidoc[Using RPC from JavaScript]
 - link:CreatingAUIExtension.asciidoc[Creating a UI extension]
-- 
2.39.5