Current Showcase App

...

Situation

...

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

...

provide information necessary for using the controls.

Currently there are three tabs in the showcase app:

1. Form fields - Magnolia specific fields . for dialog config. These controls come with Magnolia specific information. i.e - preconfigured for insertion into dialogs in Mag 5.
2. Vaadin fields - Vaadin fields that can be used with Magnolia . - Rename.(for apps - but which can also be used in forms.)
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?

Image Added

As we are using Vaadin controls, we analyzed the Vaadin approach to documentation them:

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.

...

Purpose of the controls

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 (headings optional)- left to right:
   
   1. Control name tree similar to vaadin approach: http://demo.vaadin.com/sampler#
   2. ControlDescription 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.. 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.

Current look

Image Removed

Proposal mockup

Image Removed

Vaadin fields tab changes

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

...

1. Field name
2. Appearance - show the field
3. Function (or Description) - description

...

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

Ref 3c. - Question remains over what information to provide. 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 Should go to
• Link to documentation example of config by code.

All three are possible if proposed redesign is implemented.

Follow up. Documentation requirement.

If we are to add a link to Magnolia 5 that leads to our wiki or docu, the documentation requirements will need to be communicated clearly.

Meeting of 31 /1/ 2013 - Showcase app to be removed. Need to document STK form fields for dialog definitions. These are also used in Apps.  When Dev say that these new form fields, controls are not for use in web development, that does not mean that they are not used in the STK. They are.

Documentation firs:  fields, control:  properties - Javadoc. Liaise with

Fields, controls are due to be implemented by end of February.