From 99d6de546c74f0eed230ea8253dda6b85109d2e7 Mon Sep 17 00:00:00 2001 From: Markus Koivisto Date: Fri, 22 Jan 2016 14:55:18 +0200 Subject: Add documentation to master branch Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674 --- .../clientside/clientside-debugging.asciidoc | 125 +++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 documentation/clientside/clientside-debugging.asciidoc (limited to 'documentation/clientside/clientside-debugging.asciidoc') 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: + + ++ +---- + +---- ++ +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: + + ++ +---- + +---- +. 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. + + + + -- cgit v1.2.3