1 files changed, 96 insertions, 0 deletions
diff --git a/documentation/articles/IntegratingAJavaScriptLibraryAsAnExtension.asciidoc b/documentation/articles/IntegratingAJavaScriptLibraryAsAnExtension.asciidoc
new file mode 100644
index 0000000000..090c91209e
--- /dev/null
+++ b/documentation/articles/IntegratingAJavaScriptLibraryAsAnExtension.asciidoc
@@ -0,0 +1,96 @@
+---
+title: Integrating A JavaScript Library As An Extension
+order: 39
+layout: page
+---
+
+[[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 <<CreatingAUIExtension#creating-a-ui-extension,
+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 
+<<IntegratingAJavaScriptComponent#integrating-a-javascript-component,
+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 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.
+
+[WARNING]
+.Security Warning
+====
+Do note that third-party JavaScript code can be dangerous 
+(https://www.owasp.org/index.php/3rd_Party_Javascript_Management_Cheat_Sheet), 
+and you should take into account the security risks of using such. 
+
+====
+\ No newline at end of file