Add 3 wiki articles (#9903)

Add articles:

- Configure ComboBoxes wisely
- Letting the user download a file
- Using Vaadin in IBM Domino

1 files changed, 310 insertions, 0 deletions

diff --git a/documentation/articles/UsingVaadinInIBMDomino.asciidoc b/documentation/articles/UsingVaadinInIBMDomino.asciidoc
new file mode 100644
index 0000000000..d182ef5c40
--- /dev/null
+++ b/documentation/articles/UsingVaadinInIBMDomino.asciidoc
@@ -0,0 +1,310 @@
+[[using-vaadin-in-ibm-domino]]
+Using Vaadin In IBM Domino
+--------------------------
+
+Vaadin can be used as a UI technology in Domino. This page will contain
+the instruction how to setup the development environment and to get
+started with your first Vaadin app in Domino.
+
+The steps for setting up XPages SDK are:
+
+1.  Download the
+http://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20SDK%20for%20Eclipse%20RCP/releases/0C60A1BFF5F40FD586257D8D005AA593[XPages
+SDK for Luna and above from OpenNTF]
+2.  In Eclipse, from the Help menu select *Install New Software….*
+3.  Select *Add…*, then choose *Archive…* and navigate to the zip file
+downloaded. +
+image:https://lh3.googleusercontent.com/PznhvZ1_SL6oJAm_J7BDsd0uBRHK7HDgCm6XJThdSRrPxDymwjYWOxbDpJ5Kt_5VIOIR-SP4Zl9KDAwCG0wzWni1iTwK8FUcmT8P_mYo4GxdtGjPZS4D8Y9pQus3dHM-kNeaRmfChg[Add XPages repository]
+4.  You will need to deselect *Group items by category*. Two features
+will show. The first includes sources, so select the second and click
+*Next*. +
+image:https://lh6.googleusercontent.com/PcTpwSQ-XpG-6c51FQ0W2upuK7XTNmawdi8vVgMb31pCBUg8Lt1oInKXT7r7o21Qjj_KJtie3yLxtPvGtCnltuNwGtj42ChuMEJBkqys8nt3KCmilFydpm6iFrme6Ro-FL4uZtUjkA[Select features]
+5.  Accept the terms and finish the dialog. You will be prompted to
+restart Eclipse to complete the install.
+6.  Select *Window* > *Preferences* (on Mac the location is *Eclipse* >
+*Preferences*). In the XPages SDK category tick *Automatically create
+JRE* and point to your local Notes and Domino installs. Then click
+*Apply*. +
+image:https://lh4.googleusercontent.com/22p8lT8-LrVTSKMDM0rpK2rFJT2EVfAuT62DyTYu6-x_eeddy6pEm1Io1haYlbGMwIE6PY8YRAUIEw0HQkXcHs6sNdnxkguXO4vv5VRKnoWUulDC6t46oDYI8Y9EjraTEV-dDHT6Wg[Select XPages SDK]
+7.  In the *Java* > *Installed JREs* category you should now have two
+additional options, “XPages Domino JRE” and “XPages Notes JRE”. Under
+*Plug-in Development* > *Target Platform* click *Add…*. Select the
+*Domino Install Target* template and complete. +
+image:https://lh5.googleusercontent.com/q0i66CSxHHvtQHXX4d-sq6AzElKUH_Lj-D9bg2awQL0Gn3WkcW_eTC7p_WBL94GUpB7ohEGw_i33Mk9K-q8wJ-2F5cguXimdrcCJxkELNLYC1FBzmDsx6FJo3-7wotvPdPGYVq_EeA[Configure target definition]
+8.  Apply this as the target platform. +
+image:https://lh6.googleusercontent.com/bguj0lMgODnG96vnU-RyBXCpz-FsodyAuvR6E-X3AsOoi4jC5iEilOtfssxk_Mwl3Ks1RPIbm6Pu6VzjmhOAnaL5c219wStTvw8cGKlG3pKSCVuSCcqHmHHpAxDHqK9c8TYT18siGA[Apply target definition]
+
+If you do not have a Domino server installed, there is an alternative
+approach. However, to test your OSGi plugin, you will need to create a
+Feature project, add the Plugin to that feature, then create an Update
+Site Project, add the feature to the update site, build and export. Then
+you will need to import that into an Update Site database on your
+server. This is the same process for creating and testing any other OSGi
+plugin on the server, such as XPages Extension Library.
+
+1.  Download the
+http://www.openntf.org/main.nsf/project.xsp?r=project/XPages%20SDK%20for%20Eclipse%20RCP/releases/0C60A1BFF5F40FD586257D8D005AA593[IBM
+Domino Update Site for Build Management from OpenNTF]. This is basically
+a zip file that contains features and plugins required for Maven and
+Tycho development in Eclipse, but also has all the dependencies required
+for Eclipse.
+2.  In Eclipse, go to *Window* > *Preferences* (on Mac the location is
+*Eclipse* > *Preferences*). Then go to *Plug-in Development* > *Target
+Platform*.
+3.  Edit the existing target platform configuration and in the dialog,
+click *Add…*, then *Directory*, then Next. Browse to and select the
+folder where you extracted the Update Site.> +
+image:https://lh5.googleusercontent.com/H2SiM2GdW9GYFzX_Az1Y7S_KAPnxYaGxwludqlqQoT3P1oVRDNxlC53uTt6SIrtQkPn42hr7yYqaJPK3hY9yF7BVeH8dPdwknzwLdeTIGgOXToWkKhy4smxg0hucyt3aWbmtjFpsgg[Add content]
+4.  The current release of Domino, 9.0.1, only supports Java 1.6. The
+next release, probably called Domino 9.0.2 and expected to ship first
+half 2016, is expected to include Java 1.8. But in the meantime, it’s
+best to set the JRE accordingly. In the preferences, go to *Java* >
+*Installed JREs* category.
+5.  *Add…*, *Standard VM*, then *Next* +
+image:https://lh6.googleusercontent.com/CGTOZTDGlIzgLNWn-1gTnrmhl7knp3SM2up9CX1cknk4Fyu5NfzQXjBDu2_yBz6gfq2HBppWH4gessWitIqUMOW793v_E7VekqUPJSAw0lVXj0inSusqi7gzjw6NjRsIDwJqvirjDA[Add JRE]
+6.  Click *Directory* and browse to your IBM Notes install’s “jvm”
+library. Give it an appropriate name and click *Finish*. Alternatively,
+if you don’t have IBM Notes installed on the development environment,
+download Java SE 6 SDK from Oracle. +
+image:https://lh5.googleusercontent.com/ipTTRFnUl_Ew0UE0X7XOaqqGcjEwUMAosAY6LDJ0_XZg8d7TyjsnRmDXDjGY3yrCOZ_54q9a23eqKZU0G__HwLKlglRxw5XeW2eDHvKPsgBpRu7YKcP46nKL_2KcCN4ljt1F3NAlFw[Configure JRE]
+
+[[setting-up-vaadin]]
+Setting up Vaadin
+^^^^^^^^^^^^^^^^^
+
+Eclipse has a set of Vaadin plugins that can easily be installed to set
+up your environment.
+
+1.  *Select *Help* > *Eclipse Marketplace…*.*
+2.  Search for "Vaadin" amd install the**Vaadin Plugin for Eclipse** +
+image:https://lh4.googleusercontent.com/SpgGN3m6aFksfRJG47RVBg4qi5D7r9dhfaIUwHkm3A8TLfkF6M2farq2ZZf-zvjZakrNl1wALHHqGtiP6GNoVyIFHJs9Dpr9Tt3yqtWS6TwFMN1qsJ47o3T4UqU-G1SW0KCIbQGBnA[Select Vaadin plugin]
+3.  The options to install will include the *Vaadin Designer*, so leave
+all selected, confirm and accept the license. You will be prompted to
+restart Eclipse to complete the install.
+
+[[hello-world-example]]
+Hello World Example
+^^^^^^^^^^^^^^^^^^^
+
+Now the development environment is set up, it’s time to create a Hello
+World application. But this one will not just print “Hello World” to the
+browser, instead it will add in the other key aspect, integrating with
+Domino. Maven is a useful tool for loading dependencies automatically,
+but will require the
+http://www.openntf.org/main.nsf/project.xsp?r=project/IBM%20Domino%20Update%20Site%20for%20Build%20Management[IBM
+Domino Update Site for Build Management] mentioned earlier. So at this
+point the approach will just create a simple non-Mavenized plugin.
+
+1.  In Eclipse, select *File* > *New* > *Plug-in Project* and give it a
+name. As an OSGi plugin, tell it to run with the OSGi framework
+“Equinox”.
+image:img/domino1.png[1]
+
+2.  Until the next release of Domino is out, the execution environment
+needs to be changed to Java 1.6. Then finish – the Eclipse perspective
+used for development is not significant at this stage.
+image:img/domino2.png[2]
+
+3.  The MANIFEST.MF will be opened and some additional configuration is
+required. The plugin should be set as a singleton on the Overview tab.
+image:img/domino3.png[3]
+
+4.  On the Dependencies tab some plugins and packages need loading for
+OSGi and Domino, as below.
+image:img/domino4.png[4]
+
+5.  Back on the Overview tab, click the Extension Points link and
+confirm you want to display the Extension and Extension Point pages.
+image:img/domino4.png[5]
+
+6.  On the Extensions tab, click *Add…* and choose
+`com.ibm.pvc.webcontainer.application`.
+image:img/domino6.png[6]
+
+7.  Set the contextRoot to “/helloVaadin”.
+image:img/domino7.png[7]
+
+8.  Right-click on *com.ibm.pvc.webcontainer.application* and select
+*New* > *contentLocation*. Set it to “WebContent”. These two steps can
+be done by manually typing the relevant XML onto the plugin.xml tab and
+I would recommend you loop at what the resulting XML is.
+image:img/domino8.png[8]
+
+9.  Next download the Vaadin jar files that will be needed from the
+https://vaadin.com/download#direct-download[Vaadin website]. The
+README.txt file outlines the steps required to add it to the project,
+but are repeated below.
+
+10. Right-click the project and select *New* > *Folder* and call it
+WebContent/WEB-INF/lib.
+image:img/domino9.png[9]
+
+11. Copy all jars to WebContent/WEB-INF/lib. Copy all jars in the lib
+folder to WebContent/WEB-INF/lib.
+
+12. In the MANIFEST.MF, on the *Runtime* tab in the *Classpath* section,
+click *Add…* and add all the jar files added to WebContent/WEB-INF/lib.
+You must select the jars, not the folder. Then remember to move the “.”
+entry to the top of the list.
+image:img/domino10.png[10]
+
+13. Right-click the WebContent/WEB-INF folder and select *New* > *File*.
+Call it web.xml.
+
+14. Paste in the code below:
++
+[source,xml]
+....
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
+xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
+http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
+<display-name>HelloVaadin</display-name>
+   <welcome-file-list>
+     <welcome-file>index.html</welcome-file>
+     <welcome-file>index.htm</welcome-file>
+     <welcome-file>index.jsp</welcome-file>
+     <welcome-file>default.html</welcome-file>
+     <welcome-file>default.htm</welcome-file>
+     <welcome-file>default.jsp</welcome-file>
+   </welcome-file-list>
+   <context-param>
+       <description>Vaadin production mode</description>
+       <param-name>productionMode</param-name>
+       <param-value>false</param-value>
+   </context-param>
+   
+   <servlet>
+       <servlet-name>HelloVaadinServlet</servlet-name>
+       <servlet-class>com.vaadin.server.VaadinServlet</servlet-class>
+       <init-param>
+           <param-name>UI</param-name>
+           <param-value>com.paulwithers.hellovaadin.HelloVaadinUI</param-value>
+       </init-param>
+   </servlet>
+
+   <servlet-mapping>
+       <servlet-name>HelloVaadinServlet</servlet-name>
+       <url-pattern>/*</url-pattern>
+   </servlet-mapping>
+</web-app>
+....
++
+This first block gives a list of default URL extensions accepted for
+mapping and tells the application to run in development mode. The
+<servlet> block gives the servlet name and points to a class we will
+create later which will initialise the NotesThread required for talking
+to Domino. The initParam points to a class we will create later that
+will be the entry point into the application.
+
+15.  Right-click com.paulwithers.hellovaadin and select *New* > *Vaadin
+Design*. You will need an evaluation or full license for Vaadin
+Designer. To get the trial license, log into the vaadin.com website and
+go to https://vaadin.com/designer#license-modal[https://vaadin.com/designer#license-modal.]
+
+16.  Call the design page “WelcomeDesign” and use the *Vertical Layout*
+template. Finish and confirm to switch to the Vaadin perspective.
+
+17.  Drag and drop a new Label onto the page (components are displayed
+alphabetically). In the Properties view set the name to “label1”. Click
+the ellipsis button next to *StyleName*. Select “LABEL_H2” and click
+*Add ->*, then OK. Change *ComponentAlignment* to “TOP_CENTER”. Save and
+close.
+
+18. Switch back to the Plug-in Development perspective. This is better
+suited to plugin development. Note the “WelcomeDesign.html” and
+“WelcomeDesign.java” files. Review WelcomeDesign.java.
+
+19. Right-click on com.paulwithers.hellovaadin and select *New* >
+*Class*. Call it WelcomeView and set the superclass as WelcomeDesign.
+image:img/domino12.png[12]
+
+20. Add the following code to the class to extend the auto-generated class and to compute the value of label1.
++
+[source,java]
+....
+import com.ibm.domino.osgi.core.context.ContextInfo;
+
+public class WelcomeView extends WelcomeDesign {
+    private static final long serialVersionUID = 1L;
+
+    public WelcomeView() {
+        super();
+        try {
+            label1.setValue("Welcome " +
+ContextInfo.getUserSession().getEffectiveUserName());
+        } catch (final Exception e) {
+            // TODO: handle exception
+        }
+    }
+}
+....
+
+21. You may get an error that the method Session.getEffectiveUserName()
+is not API. That can be fixed by amending the Java compiler settings, by
+changing the setting for forbidden reference to “Warning”.
+image:img/domino13.png[13]
+
+22. Right-click on *src/com.paulwithers.hellovaadin* and select *New* >
+*Class*. Class it “HelloVaadinUI” and set the superclass as
+“com.vaadin.ui.UI”.
+image:img/domino14.png[14]
+
+23. Add the following code to the class:
++
+[source,java]
+....
+import com.vaadin.server.VaadinRequest;
+import com.vaadin.ui.UI;
+
+public class HelloVaadinUI extends UI {
+    @Override
+    protected void init(VaadinRequest request) {
+        final WelcomeView welcome = new WelcomeView();
+        setContent(welcome);
+    }
+}
+....
+This creates an instance of the WelcomeView class just created and loads
+it to the page.
+
+24. On the *Build* tab ensure META-INF, WebContent, plugin.xml, src are
+all ticked for Binary Build.
+
+25. On the Overview tab, launch the *Organize Manifests Wizard* and
+complete.
+image:img/domino15.png[15]
+
+26. Select *File* > *New* > *Feature Project*. Call it
+com.paulwithers.helloVaadinFeature.
+image:img/domino16.png[16]
+
+27. Click Next and initialise from the com.paulwithers.helloVaadin
+plugin.
+
+28. Select *File* > *New* > *Update Site Project*. Call it
+com.paulwithers.helloVaadinUpdate and click Finish. Click *Add Feature…*
+and select com.paulwithers.helloVaadinFeature. Click *Build All*.
+
+29. Right-click com.paulwithers.helloVaadinUpdate and click *Export…*.
+Choose *General > File System*. You only need to select the site.xml.
+Export to an appropriate location.
+image:img/domino17.png[17]
+
+30. In an Update Site database on the relevant server, import the update
+site by pointing to the site.xml.
+image:img/domino18.png[18]
++
+As with any OSGi plugin, you will need to issue “restart task http”
+command to the server for the plugin to be available.
+
+31. If you browse to the “helloVaadin” URL on the server (corresponding
+to the contextRoot in the plugin.xml), you should now see “Hello
+Anonymous” message.
+image:img/domino19.png[19]
+
+If you log in or prefix the contextRoot with the filepath of a database
+that does not allow anonymous access, you will see a welcome message for
+the current logged in user.
+image:img/domino20.png[20]