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.
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.

Question for going forward - Is the showcase app likely to expand? As in, how likely is it that over time more and more controls will be added?  If this is the case, then it might be worth considering adding Categories for the Form Field tab control list.

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:

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 colum approach with headings that correspond to: 

Control, Image, Description.

Form fields tab changes

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

1. Increase real estate for the fields (i.e make the light grey area bigger - stretch it to the left and right).
2. Add three columns with headings:
   
   1. Field name
   2. Appearance - Show the actual field, item, 'thing'.
   3. Function (or Description) - 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.) 
3. Left align everything in each column.
4. To accommodate the About text (Function? Description?) increase space between each row so that 140 characters can fit comfortably in the third column, spread over 2/3 lines at standard browsing settings.
5. Consider adding visible lines as column or row indicators (i.e grey vertical lines). Am not 100% convinced of this. There appear to be semi row indicators in the Vaadin fields tab. Not to great effect though.
6. Remove references to 'in a form' in field name. So, 'Commit button in a form' is just called 'Commit button'.
   
   

Current look

Proposal mockup

Vaadin fields tab changes

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

1. Increase real estate for the fields (i.e make the light grey area bigger - stretch it to the left and right).
2. Add three columns:
   
   1. Field name
   2. Appearance - show the field
   3. Function (or Description) - description
3. Left align everything in each column. 
4. For the Field names:
   
   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