Migrate IntegratingAJavaScriptLibraryAsAnExtension

2 files changed, 81 insertions, 0 deletions

diff --git a/documentation/articles/IntegratingAJavaScriptLibraryAsAnExtension.asciidoc b/documentation/articles/IntegratingAJavaScriptLibraryAsAnExtension.asciidoc
new file mode 100644
index 0000000000..e359bf4a99
--- /dev/null
+++ b/documentation/articles/IntegratingAJavaScriptLibraryAsAnExtension.asciidoc
@@ -0,0 +1,80 @@
+[[integrating-a-javascript-library-as-an-extension]]
+Integrating a JavaScript library as an extension
+------------------------------------------------
+
+JavaScript can also be used for creating Extensions e.g. for integrating
+existing JavaScript libraries. See link:CreatingAUIExtension.asciidoc[Creating a UI extension] for general information about Extensions. The main
+difference when using JavaScript is that you extend
+`AbstractJavaScriptExtension`, that your shared state class should
+extend `JavaScriptExtensionState` and then of course that your
+client-side implementation is written in JavaScript. See [Integrating a
+JavaScript component] for basic information about how to use JavaScript
+for your client-side logic.
+
+This tutorial will create a simple Extension for integrating
+https://developers.google.com/analytics/devguides/collection/gajs/[Google
+Analytics]. Because the Analytics API just uses the same `_gaq.push`
+function with different arguments, the JavaScript connector logic can be
+equally simple. Aside from asynchronously loading ga.js, the client-side
+code just adds a callback (see link:SimplifiedRPCusingJavaScript.asciidoc[Simplified RPC using JavaScript] for
+more information) that the server-side code can use to push new
+commands.
+
+[source,javascript]
+....
+window._gaq = window._gaq || [];
+
+(function() {
+  var ga = document.createElement('script');
+  ga.type = 'text/javascript';
+  ga.async = true;
+  ga.src = ('https:' == document.location.protocol ?
+    'https://ssl' : 'http://www') +
+    '.google-analytics.com/ga.js';
+  var s = document.getElementsByTagName('script')[0];
+  s.parentNode.insertBefore(ga, s);
+})();
+
+window.com_example_Analytics = function() {
+  this.pushCommand = function(command) {
+    _gaq.push(command);
+  }
+}
+....
+
+The server-side Extension class provides the common Extension API for
+extending a UI instance as well as API for some Analytics features. All
+the Analytics features are based on the `pushCommand` method that
+invokes the corresponding client-side callback.
+
+The Analytics API used in this example has nothing that warrants using
+shared state, but you can of course use shared state in your own
+JavaScript Extension if you want to as long as your state class extends
+`JavaScriptExtensionState`.
+
+[source,java]
+....
+@JavaScript("analytics_connector.js")
+public class Analytics extends AbstractJavaScriptExtension {
+  public Analytics(UI ui, String account) {
+    extend(ui);
+    pushCommand("_setAccount", account);
+  }
+
+  public void trackPageview(String name) {
+    pushCommand("_trackPageview", name);
+  }
+
+  private void pushCommand(Object... commandAndArguments) {
+    // Cast to Object to use Object[] commandAndArguments as the first
+    // varargs argument instead of as the full varargs argument array.
+    callFunction("pushCommand", (Object) commandAndArguments);
+  }
+}
+....
+
+Extensions are suitable for integrating many existing JavaScript
+libraries that do not provide a component that is added to a layout. By
+using a client-side JavaScript connector for integrating the JavaScript
+library, you can eliminate GWT from the equation to give you slightly
+less code to maintain.
diff --git a/documentation/articles/contents.asciidoc b/documentation/articles/contents.asciidoc
index 3b02b3d4d5..486416cf5b 100644
--- a/documentation/articles/contents.asciidoc
+++ b/documentation/articles/contents.asciidoc
@@ -45,3 +45,4 @@ are great, too.
 - link:VaadinOnGrailsDatabaseAccess.asciidoc[Vaadin on grails - Database access]
 - link:VaadinOnGrailsMultipleUIs.asciidoc[Vaadin on grails - Multiple UIs]
 - link:IntegratingAJavaScriptComponent.asciidoc[Integrating a JavaScript component]
+- link:IntegratingAJavaScriptLibraryAsAnExtension.asciidoc[Integrating a JavaScript library as an extension]