...

Docu's understanding is that the Showcase app Forms subapp lists controls specifically for use in Magnolia 5 forms (dialogs) during app development, modification.  All other Vaadin controls (currently listed in the Vaadin controls subapp) are for use within an app, subapps.

Proposal for Showcase app redesign

Create a custom app:

1. Increase real estate for the fields (i.e make the light grey area bigger - stretch it to the left and right).
2. Only have two subapps -  Form Controls & Other Controls etc.
   
3. Add three columns - left to right:
   
   1. Control name tree similar to vaadin approach: http://demo.vaadin.com/sampler#
   2. Control. Shows a fully functional control.
   3. Appears when selected on left menu. Dynamic description box with links (changes to reflect control clicked on left menu.)
   Left align everything in each column.

Ref 3c. - Question remains over what information to provide. The options are. See next section. 

Documentation options

We propose some or all of the following solutions:

• Link to internal configuration within Magnolia for each control. This provide real life access to how a control is configured in Magnolia (i.e. in the repository/workspace.)
• Link to API / widget documentation. Note that at present Git also supplies information on controls that we do not want developers to change or reuse - such as the App launcher:  https://git.magnolia-cms.com/gitweb/?p=magnolia_ui.git;a=tree;f=magnolia-ui-vaadin-common-widgets/src/main/java/info/magnolia/ui/vaadin;hb=HEAD
• Link to documentation example of config by code.

All three are possible if proposed redesign is implemented.

Documentation requirement

...