Page tree
Skip to end of metadata
Go to start of metadata

Current Showcase App

Situation

There is a need to 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 (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.

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

Vaadin approach

See: http://demo.vaadin.com/sampler

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 - 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. See next section. 

Documentation options

We propose some or all of the following solutions:

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.

  • No labels

2 Comments

  1. I would like to see an example of the Function (or Description) text. If the text can "not contain any coding information or any detail beyond a brief usage description" then what value does it provide to developers? Self-evident text such as "The date field is used for selecting dates" is of little value.

  2. Advice on where to use it perhaps? Will discuss with Philippe. Don't have enough info at present to comment properly. I say -

    "Add a short usage description per field. Say, max 140 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.)"

    - hoping to avoid something too literally descriptive. Some fields, objects may not be intuitive. If something is self evident, maybe we can just skip the usage description?  Will talk to devs about this. Agree 100%.