Showcase App alterations

There is a requirement to add information about the fields etc. that are available in the showcase app:

1. The information should be succinct, descriptive but not contain code or any detail beyond a brief usage description for each item. (Why? If we can fit it in, is that ok?)
2. For further information the user needs to look to official documentation. For this reason there needs to be a link to official documentation from within Magnolia CMS 5. (Note that this solution assumes that extra information is required. It may not be.)

Currently there are three tabs in the showcase app:

1. Form fields - Magnolia specific fields. 
2. Vaadin fields - Vaadin fields that can be used with Magnolia. - Rename.
3. Unsupported fields - Not clear why we specify what Vaadin fields NOT to use. The list of controls is not extensive, implying either that there are many more controls that can be added (in which case the form field tab and Vaadin fields tab are incomplete) or that the list of banned controls is incomplete.

All three tabs require changes. To summarize:

• Make each tab tabular. Classic table with header, columns and rows (albeit these are invisible). Keep things nicely spaced.
• General suggestion valid for all three tabs is to add a link to official documentation, where users can find detailed information on using fields. The link could be by the line "Showcase apps......." above the tabs. Or, link to a more specific page from each tab. See Mockup proposal

What do Vaadin do?

Problem

Need to include information on using each control. How? What kind of information?

For example Text, Button etc. The question then is whether to list by control type (e.g. 'Text fields')  or functional type (e.g. Text inputs) which would include specific control types ('Text fields'). Vaadin mix these in their documentation, probably a sensible approach. Here you can see the Text input category:Vaadin approach

See: http://demo.vaadin.com/sampler Note that when the information is viewed this way, you get essentially what I would argue for in the Showcase app - a three column approach with headings that correspond to Control, Image, Description. The difference is that in Mag 5 we don't want to have click, jab to see the info.

...

1. Increase real estate for the fields (i.e make the light grey area bigger - stretch it to the left and right).
2. Only show Magnolia controls.
3. Add three columns (headings optional)
   
   1. Control name tree
   2. Control
   3. Description box with links.   - Add a short usage description per field. Say, max 140 - 200 characters. (Use this for... Can also be used for... etc.) Where, why, how. (Use on x pages to describe....Try not to use more than x times per page.)
4. Left align everything in each column.

Re c - Question remains over what information to provide. 

1. 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.)
2. 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: 
3. Link to documentation example of config by codeLeft align everything in each column.

Current look

Proposal mockup - version 1

Vaadin fields tab changes

Suggest making a few alterations to the Showcase App: Vaadin fields tab:

...

...

1. Use sentence case for headings (First word capitalized only.) At present there we have 'Magnolia icons' but 'Progress Indicator'. 'Progress indicator' is better.
2. Perhaps BOLD the highest level of heading (the category - for example Magnolia icons) not secondary headings. 
3. Label each item, field, 'thing' individually, either as an independent thing or as a member of a category.
4. Name each field separately. Currently there is 'Magnolia table and tree table'. This should be:

• Magnolia table
• Tree table

...