Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 125 insertions, 0 deletions

diff --git a/documentation/clientside/clientside-debugging.asciidoc b/documentation/clientside/clientside-debugging.asciidoc
new file mode 100644
index 0000000000..efbe24a8ec
--- /dev/null
+++ b/documentation/clientside/clientside-debugging.asciidoc
@@ -0,0 +1,125 @@
+---
+title: Debugging Client-Side Code
+order: 6
+layout: page
+---
+
+[[clientside.debugging]]
+= Debugging Client-Side Code
+
+Vaadin currently includes SuperDevMode for debugging client-side code right in
+the browser.
+
+The predecessor of SuperDevMode, the GWT Development Mode, no longer works in
+recent versions of Firefox and Chrome, because of certain API changes in the
+browsers. There exists workarounds on some platforms, but for the sake of
+simplicity, we recommend using the SuperDevMode.
+
+ifdef::web[]
+[[clientside.debugging.devmode]]
+== Launching Development Mode
+
+The Development Mode launches the application in the browser, compiles the
+client-side module (or widget set) when the page is loaded, and allows debugging
+the client-side code in Eclipse. You can launch the Development Mode by running
+the [classname]#com.google.gwt.dev.DevMode# class. It requires some parameters,
+as described later.
+
+The Vaadin Plugin for Eclipse can create a launch configuration for the
+Development Mode. In the Vaadin section of project properties, click the
+[guibutton]#Create development mode launch# button. This creates a new launch
+configuration in the project. You can edit the launch configuration in "Run >
+Run Configurations".
+
+
+----
+-noserver -war WebContent/VAADIN/widgetsets com.example.myproject.widgetset.MyWidgetSet -startupUrl http://localhost:8080/myproject -bindAddress 127.0.0.1
+----
+
+The parameters are as follows:
+
+[parameter]#-noserver#:: Normally, the Development Mode launches its own Jetty server for hosting the content. If you are developing the application under an IDE that deploys it to a server, such as Eclipse, you can disable the Development Mode server with this option.
+[parameter]#-war#:: Specifies path to the location where the JavaScript is to be compiled. When developing a pure client-side module, this could be the [filename]#WebContent# (in Eclipse) or some other folder under it. When compiling widget sets, it must be [filename]#WebContent/VAADIN/widgetsets#.
+[parameter]#-startupUrl#:: Specifies the address of the loader page for the application. For server-side Vaadin applications, this should be the path to the Vaadin application servlet, as defined in the deployment. For pure client-side widgets, it should be the page where the application is included.
+[parameter]#-bindAddress#:: This is the IP address of the host in which the Development Mode runs. For debugging on the development workstation, it can be just [literal]#++127.0.0.1++#. Setting it as the proper IP address of the host enables remote debugging.
+
+
+endif::web[]
+
+[[clientside.debugging.superdevmode]]
+== Launching SuperDevMode
+
+The SuperDevMode is much like the old Development Mode, except that it does not
+require a browser plugin. Compilation from Java to JavaScript is done
+incrementally, reducing the compilation time significantly. It also allows
+debugging JavaScript and even Java right in the browser (currently only
+supported in Chrome).
+
+You can enable SuperDevMode as follows:
+
+. You need to set a redirect property in the [filename]#.gwt.xml# module
+descriptor as follows:
+
+
++
+----
+<set-configuration-property name="devModeRedirectEnabled" value="true" />
+----
++
+In addition, you need the [literal]#++xsiframe++# linker. It is included in the
+[classname]#com.vaadin.DefaultWidgetSet# as well as in the
+[classname]#com.vaadin.Vaadin# module. Otherwise, you need to include it with:
+
+
++
+----
+<add-linker name="xsiframe" />
+----
+. Compile the module (that is, the widget set), for example by clicking the button in Eclipse.
+. If you are using Eclipse, create a launch configuration for the SuperDevMode by
+clicking the [guibutton]#Create SuperDevMode launch# in the [guilabel]#Vaadin#
+section of the project properties.
+
+.. The main class to execute should be [classname]#com.google.gwt.dev.codeserver.CodeServer#.
+.. The application takes the fully-qualified class name of the module (or widget set) as parameter, for example, [classname]#com.example.myproject.widgetset.MyprojectWidgetset#.
+.. Add project sources to the class path of the launch if they are not in the project class path.
+
+
+The above configuration only needs to be done once to enable the SuperDevMode.
+After that, you can launch the mode as follows:
+
+. Run the SuperDevMode Code Server with the launch configuration that you created above. This perfoms the initial compilation of your module or widget set.
+. Launch the servlet container for your application, for example, Tomcat.
+. Open your browser with the application URL and add [literal]#++?superdevmode++# parameter to the URL (see the notice below if you are not extending [classname]#DefaultWidgetSet#). This recompiles the code, after which the page is reloaded with the SuperDevMode. You can also use the [literal]#++?debug++# parameter and then click the [guibutton]#SDev# button in the debug console.
+
+If you make changes to the client-side code and refresh the page in the browser,
+the client-side is recompiled and you see the results immediately.
+
+The Step 3 above assumes that you extend [classname]#DefaultWidgetSet# in your
+module. If that is not the case, you need to add the following at the start of
+the [methodname]#onModuleLoad()# method of the module:
+
+
+----
+if (SuperDevMode.enableBasedOnParameter()) { return; }
+----
+
+Alternatively, you can use the bookmarklets provided by the code server. Go to
+http://localhost:9876/ and drag the bookmarklets " [guilabel]#Dev Mode On#" and
+" [guilabel]#Dev Mode Off#" to the bookmarks bar
+
+
+[[clientside.debugging.chrome]]
+== Debugging Java Code in Chrome
+
+Chrome supports source maps, which allow debugging Java source code from which
+the JavaScript was compiled.
+
+Open the Chrome Inspector by right-clicking and selecting [guilabel]#Inspect
+Element#. Click the settings icon in the lower corner of the window and check
+the "Scripts > Enable source maps" option. Refresh the page with the Inspector
+open, and you will see Java code instead of JavaScript in the scripts tab.
+
+
+
+