1 files changed, 78 insertions, 0 deletions
diff --git a/documentation/portal/portal-ui.asciidoc b/documentation/portal/portal-ui.asciidoc
new file mode 100644
index 0000000000..69c6cc3b58
--- /dev/null
+++ b/documentation/portal/portal-ui.asciidoc
@@ -0,0 +1,78 @@
+---
+title: Portlet UI
+order: 4
+layout: page
+---
+
+[[portal.ui]]
+= Portlet UI
+
+A portlet UI is just like in a regular Vaadin application, a class that extends
+[classname]#com.vaadin.ui.UI#.
+
+
+----
+@Theme("myportlet")
+public class MyportletUI extends UI {
+    @Override
+    protected void init(VaadinRequest request) {
+        final VerticalLayout layout = new VerticalLayout();
+        layout.setMargin(true);
+        setContent(layout);
+
+        Button button = new Button("Click Me");
+        button.addClickListener(new Button.ClickListener() {
+            public void buttonClick(ClickEvent event) {
+                layout.addComponent(
+                        new Label("Thank you for clicking"));
+            }
+        });
+        layout.addComponent(button);
+    }
+}
+----
+
+If you created the project as a Servlet 3.0 project, the generated UI stub
+includes a static servlet class annotated with [classname]#@WebServlet#, as
+described in
+<<dummy/../../../framework/getting-started/getting-started-first-project#getting-started.first-project.exploring,"Exploring
+the Project">>.
+
+
+----
+    @WebServlet(value = "/*", asyncSupported = true)
+    @VaadinServletConfiguration(productionMode = false,
+                                ui = MyportletUI.class)
+    public static class Servlet extends VaadinServlet {
+    }
+----
+
+This enables running the portlet UI in a servlet container while developing it,
+which may be easier than deploying to a portal. For Servlet 2.4 projects, a
+[filename]#web.xml# is created.
+
+The portlet theme is defined with the [classname]#@Theme# annotation as usual.
+The theme for the UI must match a theme installed in the portal. You can use any
+of the built-in themes in Vaadin. For Liferay theme compatibility, there is a
+special [literal]#++liferay++# theme. If you use a custom theme, you need to
+compile it to CSS with the theme compiler and install it in the portal under the
+[filename]#VAADIN/themes# context to be served statically.
+
+In addition to the UI class, you need the portlet descriptor files, Vaadin
+libraries, and other files as described later.
+<<figure.portal.helloworld.project>> shows the complete project structure under
+Eclipse.
+
+[[figure.portal.helloworld.project]]
+.Portlet Project Structure in Eclipse
+image::img/liferay-project.png[]
+
+Installed as a portlet in Liferay from the [guilabel]#Add Application# menu, the
+application will show as illustrated in <<figure.portal.helloworld>>.
+
+[[figure.portal.helloworld]]
+.Hello World Portlet
+image::img/liferay-helloworld.png[]
+
+
+