Add documentation to master branch

Change-Id: I2504bb10f1ae73ec0cbc08b7ba5a88925caa1674

1 files changed, 76 insertions, 0 deletions

diff --git a/documentation/clientside/clientside-widget.asciidoc b/documentation/clientside/clientside-widget.asciidoc
new file mode 100644
index 0000000000..ed911a46b4
--- /dev/null
+++ b/documentation/clientside/clientside-widget.asciidoc
@@ -0,0 +1,76 @@
+---
+title: Creating a Custom Widget
+order: 5
+layout: page
+---
+
+[[clientside.widget]]
+= Creating a Custom Widget
+
+Creating a new Vaadin component usually begins from making a client-side widget,
+which is later integrated with a server-side counterpart to enable server-side
+development. In addition, you can also choose to make pure client-side widgets,
+a possibility which we also describe later in this section.
+
+[[clientside.widget.simple]]
+== A Basic Widget
+
+All widgets extend the [classname]#Widget# class or some of its subclasses. You
+can extend any core GWT or supplementary Vaadin widgets. Perhaps typically, an
+abstraction such as [classname]#Composite#. The basic GWT widget component
+hierarchy is illustrated in <<figure.clientside.widgets>>. Please see the GWT
+API documentation for a complete description of the widget classes.
+
+[[figure.clientside.widgets]]
+.GWT Widget Base Class Hierarchy
+image::img/gwt-widgets-hi.png[]
+
+For example, we could extend the [classname]#Label# widget to display some
+custom text.
+
+
+----
+package com.example.myapp.client;
+
+import com.google.gwt.user.client.ui.Label;
+
+public class MyWidget extends Label {
+    public static final String CLASSNAME = "mywidget";
+
+    public MyWidget() {
+        setStyleName(CLASSNAME);
+        setText("This is MyWidget");
+    }
+}
+----
+
+The above example is largely what the Eclipse plugin generates as a widget stub.
+It is a good practice to set a distinctive style class for the widget, to allow
+styling it with CSS.
+
+The client-side source code __must__ be contained in a [filename]#client#
+package under the package of the descriptor file, which is covered later.
+
+
+[[clientside.widget.using]]
+== Using the Widget
+
+You can use a custom widget just like you would use any widget, possibly
+integrating it with a server-side component, or in pure client-side modules such
+as the following:
+
+
+----
+public class MyEntryPoint implements EntryPoint {
+    @Override
+    public void onModuleLoad() {
+        // Use the custom widget
+        final MyWidget mywidget = new MyWidget();
+        RootPanel.get().add(mywidget);
+    }
+}
+----
+
+
+
+