Form layouting

Related issue DEV-883 - Getting issue details... STATUS

Goal

We want to provide users with a simple, modern API to build arbitrarily complex fields.

Problem

All is good, as long as a simple value is bound to a simple field, e.g. TextField → String.

But what if I need a field manage a complex nested value, i.e. if I have to manage hierarchical data?

Currently Magnolia does provide such ability through custom multi fields (see AbstractCustomMultiField) but they have several shortcomings, both in terms of internal implementation and from a client developer's perspective (see for instance MGNLUI-2542 - Getting issue details... STATUS ).

Proposal

Assume the field is simple and atomic
When you need to manage many related values - it is another form within a form
Complex fields are like forms but with stripped layout

Layouting

Form (or editor) layout should be separated from the binding mechanism and should be flexible

first we produce the field/sub-form components and bind them to the binder
then we pass the mapping of e.g. the property names and the resulting components (fields/sub-forms) to a layout producer

the layout producer could yield a tabbed layout that we have currently or any other type of layout based on the configured definition

PoC https://git.magnolia-cms.com/users/jsimak/repos/ui/pull-requests/1/commits/91980c4dbd0803b429e50f037f4b70a638cce0dd

A class diagram from the current PoC and a description of their main responsibilities

FormDefinition

is a ComponentDefinition
is registered and mapped to a factory class like any other form field
has FieldDefinition(s)
has a LayoutDefinition

Form configuration example (YAML)

# this is the 'main' form configuration
form:
  fields:
    title:
      class: info.magnolia.ui.form.poc.definition.TextFieldDefinition
    firstName:
      class: info.magnolia.ui.form.poc.definition.TextFieldDefinition
	lastName:
      class: info.magnolia.ui.form.poc.definition.TextFieldDefinition
    # address is a form component (a subform of the main form) and specifies its own layout.
    # It is declared under fields and we can refer to it as a field
    # see below form/layout/tabs/more/fields/address
    address:
      class: info.magnolia.ui.form.poc.definition.FormDefinition
      fields:
        city:
          class: info.magnolia.ui.form.poc.definition.TextFieldDefinition
        country:
          class: info.magnolia.ui.form.poc.definition.TextFieldDefinition
        nested: # a form component can have sub-form components with their own layout
          class: info.magnolia.ui.form.poc.definition.FormDefinition
          fields:
            qux:
              class: info.magnolia.ui.form.poc.definition.TextFieldDefinition
          layout:
            class: info.magnolia.ui.form.poc.layout.MyLayout
            fields:
              qux:
      layout: # this is the layout for address
        class: info.magnolia.ui.form.poc.layout.DefaultLayoutDefinition
        fields:
          city:
          country:
          nested:
  # this is the main form's layout configuration
  # layout configurations could probably be omitted altogether and rely on a reasonable default 
  layout:
    class: info.magnolia.ui.form.poc.layout.TabbedLayoutDefinition
    tabs:
      personal:
        fields:
          title:
          firstName:
		  lastName:	
      more:
        fields:
          # address is a form component (a subform of the main form)
          # here it is referred to as if it were a plain Field
          address:

LayoutDefinition

has a list of field names composing the layout. Their names match those of the FieldDefinition(s)
specifies LayoutProducer implementation class

LayoutProducer

is instantiated from a LayoutDefinition
createLayout(LayoutDefinition, Map<String, Component>) creates the actual layout (a Vaadin Component) from
- LayoutDefinition
- a mapping of field names and actual field components

Form

is a plain Java class
it stores
- its Binder
- its own Layout (including sub-form layouts)
- its sub-forms
can save and validate self and its sub-forms recursively (should this functionality move away from Form?)

FormPresenter

is currently the orchestrator of the form building process
creates the final form view (a Vaadin Layout)

instantiates a Form from a FormDefinition
returns the form view to the caller
TODO

set labels, help messages and descriptions: use something like info.magnolia.ui.dialog.formdialog.FormView?
update forms/fields based on Locale? See info.magnolia.ui.dialog.formdialog.FormPresenterImpl.updateForm()

- - pass it to DetailPresenter(..) which takes care of initializing actions and other stuff before calling and setting the form view produced by FormPresenter?

Snippet from FormPresenter

...
 /***
 * @return a {@link View} as described by this {@link FormDefinition} including nested forms, if any.
 */
public View createFormView(D formDefinition) {
    FormView view = new FormView();
    Form<T> form = formFactory.createForm(formDefinition);
    view.addComponent(form.getLayout());

    return view;
}

Page tree