1 files changed, 208 insertions, 0 deletions

diff --git a/documentation/advanced/advanced-debug.asciidoc b/documentation/advanced/advanced-debug.asciidoc
new file mode 100644
index 0000000000..9a0d8d7ba8
--- /dev/null
+++ b/documentation/advanced/advanced-debug.asciidoc
@@ -0,0 +1,208 @@
+---
+title: Debug Mode and Window
+order: 3
+layout: page
+---
+
+[[advanced.debug]]
+= Debug Mode and Window
+
+Vaadin applications can be run in two modes: __debug mode__ and __production
+mode__. The debug mode, which is on by default, enables a number of built-in
+debug features for Vaadin developers:
+
+* Debug Window
+* Display debug information in the Debug Window and server console
+* On-the-fly compilation of Sass themes
+
+[[advanced.debug.mode]]
+== Enabling the Debug Mode
+
+The debug mode is enabled and production mode disabled by default in the UI
+templates created with the Eclipse plugin or the Maven archetypes. The debug
+mode can be enabled by giving a [parameter]#productionMode=false# parameter to
+the Vaadin servlet configuration:
+
+[subs="normal"]
+----
+@VaadinServletConfiguration(
+            productionMode = **false**,
+            ui = **MyprojectUI.class**)
+----
+Or with a context parameter in the [filename]#web.xml# deployment descriptor:
+
+[subs="normal"]
+----
+<context-param>
+  <description>Vaadin production mode</description>
+  <param-name>productionMode</param-name>
+  <param-value>**false**</param-value>
+</context-param>
+----
+Enabling the production mode disables the debug features, thereby preventing
+users from easily inspecting the inner workings of the application from the
+browser.
+
+
+[[advanced.debug.open]]
+== Opening the Debug Window
+
+Running an application in the debug mode enables the client-side Debug Window in
+the browser. You can open the Debug Window by adding " ?debug" parameter to the
+URL of the UI, for example, http://localhost:8080/myapp/?debug. The Debug Window
+has buttons for controlling the debugging features and a scrollable log of debug
+messages.
+
+[[]]
+.Debug Window
+image::img/debug-window-annotated-hi.png[]
+
+The functionalities are described in detail in the subsequent sections. You can
+move the window by dragging it from the title bar and resize it from the
+corners. The [guibutton]#Minimize# button minimizes the debug window in the
+corner of the browser window, and the [guibutton]#Close# button closes it.
+
+If you use the Firebug plugin for Firefox or the Developer Tools console in
+Chrome, the log messages will also be printed to the Firebug console. In such a
+case, you may want to enable client-side debugging without showing the Debug
+Window with " ?debug=quiet" in the URL. In the quiet debug mode, log messages
+will only be printed to the console of the browser debugger.
+
+
+[[advanced.debug.log]]
+== Debug Message Log
+
+The debug message log displays client-side debug messages, with time counter in
+milliseconds. The control buttons allow you to clear the log, reset the timer,
+and lock scrolling.
+
+[[]]
+.Debug Message Log
+image::img/debug-log-hi.png[]
+
+[[advanced.debug.log.custom]]
+=== Logging to Debug Window
+
+You can take advantage of the debug mode when developing client-side components,
+by using the standard Java [classname]#Logger# to write messages to the log. The
+messages will be written to the debug window and Firebug console. No messages
+are written if the debug window is not open or if the application is running in
+production mode.
+
+
+
+[[advanced.debug.info]]
+== General Information
+
+The [guilabel]#General information about the application(s)# tab displays
+various information about the UI, such as version numbers of the client and
+servlet engine, and the theme. If they do not match, you may need to compile the
+widget set or theme.
+
+[[]]
+.General Information
+image::img/debug-info.png[]
+
+
+[[advanced.debug.hierarchy]]
+== Inspecting Component Hierarchy
+
+The [guilabel]#Component Hierarchy# tab has several sub-modes that allow
+debugging the component tree in various ways.
+
+[[advanced.debug.hierarchy.tree]]
+=== Connector Hierarchy Tree
+
+The [guibutton]#Show the connector hierarchy tree# button displays the
+client-side connector hierarchy. As explained in
+<<dummy/../../../framework/gwt/gwt-overview.asciidoc#gwt.overview,"Integrating
+with the Server-Side">>, client-side widgets are managed by connectors that
+handle communication with the server-side component counterparts. The connector
+hierarchy therefore corresponds with the server-side component tree, but the
+client-side widget tree and HTML DOM tree have more complexity.
+
+[[]]
+.Connector Hierarchy Tree
+image::img/debug-hierarchy-tree.png[]
+
+Clicking on a connector highlights the widget in the UI.
+
+
+[[advanced.debug.hierarchy.inspect]]
+=== Inspecting a Component
+
+The [guibutton]#Select a component in the page to inspect it# button lets you
+select a component in the UI by clicking it and display its client-side
+properties.
+
+To view the HTML structure and CSS styles in more detail, you can use Firebug in
+Firefox, or the Developer Tools in Chrome, as described in
+<<dummy/../../../framework/getting-started/getting-started-environment#getting-started.environment.firefox,"Firefox
+and Firebug">>. Firefox also has a built-in feature for inspecting HTML and CSS.
+
+
+[[advanced.debug.hierarchy.analyze]]
+=== Analyzing Layout Problems
+
+The [guilabel]#Check layouts for potential problems# button analyzes the
+currently visible UI and makes a report of possible layout related problems. All
+detected layout problems are displayed in the log and also printed to the
+console.
+
+[[]]
+.Debug Window Showing the Result of Layout Analysis.
+image::img/debug-window-analyze-layouts.png[]
+
+Clicking on a reported problem highlights the component with the problem in the
+UI.
+
+The most common layout problem is caused by placing a component that has a
+relative size inside a container (layout) that has undefined size in the
+particular direction (height or width). For example, adding a
+[classname]#Button# with 100% width inside a [classname]#VerticalLayout# with
+undefined width. In such a case, the error would look as shown in
+<<dummy/../../../framework//-overview.asciidoc#figure.advanced.debug.hierarchy.analyze,"">>.
+
+[classname]#CustomLayout# components can not be analyzed in the same way as
+other layouts. For custom layouts, the button analyzes all contained
+relative-sized components and checks if any relative dimension is calculated to
+zero so that the component will be invisible. The error log will display a
+warning for each of these invisible components. It would not be meaningful to
+emphasize the component itself as it is not visible, so when you select such an
+error, the parent layout of the component is emphasized if possible.
+
+
+[[advanced.debug.hierarchy.used]]
+=== Displaying Used Connectors
+
+The last button, [guibutton]#Show used connectors and how to optimize widget
+set#, displays a list of all currently visible connectors. It also generates a
+connector bundle loader factory, which you can use to optimize the widget set so
+that it only contains the widgets actually used in the UI. Note, however, that
+it only lists the connectors visible in the current UI state, and you usually
+have more connectors than that.
+
+
+
+[[advanced.debug.communication]]
+== Communication Log
+
+The [guilabel]#Communication# tab displays all server requests. You can unfold
+the requests to view details, such as the connectors involved. Clicking on a
+connector highlights the corresponding element in the UI.
+
+You can use Firebug or Developer Tools in Firefox or Chrome, respectively, to
+get more detailed information about the requests and responses.
+
+
+[[advanced.debug.devmodes]]
+== Debug Modes
+
+The [guilabel]#Menu# tab in the window opens a sub-menu to select various
+settings. Here you can also launch the GWT SuperDevMode, as described in
+<<dummy/../../../framework/clientside/clientside-debugging#clientside.debugging,"Debugging
+Client-Side Code">>.
+
+
+
+