Page History

Most work is expected to be carried out through the following ticket/epic. This ticket, as well as linked support tickets hold several concrete scenarios.

•  

  Mikaël Geljić prepares skeleton for Vaadin sandbox application on a branch

•  

  Mikaël Geljić publishes the AccessControlFieldUI sandbox

•  

  Mikaël Geljić files JIRA tickets for each standalone PoC

1. Use cases

We need to support such dynamic forms in a much easier way. Collecting some commons requirements:

• populating select options based on the value of another field
• validating a field depending on the value of another field (including within a composite field itself)
• enabling/disabling fields conditionally
• potentially custom handling of any field, via plain Vaadin code
• updating form buttons (enabling/disabling/relabeling)

2. General directions & goals

• Exposing hooks on form-level
  • currently only possible on field-level via FieldFactories
  • fields & factories are only aware about themselves, in isolation. They're not aware about other fields and this is harder to do than it should.
• Use more of Vaadin out of the box
  • less customizations
  • get rid of legacy Vaadin 6.x or client-side code
• Open up APIs to offer more possibilities (data-binding, or dynamic/ cross-field behaviors)
• Reduce technical debt

...

3.

...

Key Concepts

• Goals

  • Validate several assumptions from Mika

  • If all goes well, put it all together at the end, through an Integration phase

• Process

  • To be carried out by the VN Core Team
  • Try to work in pairs (can still switch afterwards), or alternate between group phases and individual work/thinking
  • Keep each PoC standalone until the end of the PoC phase
• Target date:
  • 25 Sep 2016 

PoC #1: New FormPresenter

Reading definitions and building tabs and fields

• 1 Vaadin FieldGroup + FormLayout for each tab (merge bits from FormBuilder)
• Result: a simple Vaadin application (w/ ui-framework on the classpath)
  • Mika might prepare the skeleton on a branch
• FormPresenter invoking FieldFactories
  • for the PoC, you can instantiate factories manually
  • either refactor existing ones, or reimplement a simple TextFieldFactory with less Magnolia dependencies
    
    • maybe API like public Field<T> createField(D definition)

    • so we can reuse a single FieldFactory to produce multiple instances of a field
  • FieldFactories no longer doing property data-binding (#setPropertyDataSource)
    • FormPresenter doing the databinding instead => fieldGroup#setItemDataSource
    • -
• Not needed for the PoC:
  • locale and i18n handling
  • complex fields (only text fields, selects)
  • visual appearance, no MagnoliaTabSheet needed, just a plain VerticalLayout with one-to-many FormLayouts
  • -

PoC #2: Validation bubbles below field

Validation as a Vaadin JS Extension, see the few links below:

• Integrating JavaScript Components and Extensions (Vaadin docs)
• class com.vaadin.server.AbstractJavaScriptExtension
• Component Extensions & Component and UI Extensions (the GWT way, Vaadin docs)
• see also TextAreaStretcher, Bidi (GWT way) or JCrop, RowScroller (JS way) for more extension examples

Default Vaadin validation is as follows:

• warning icon
• tooltip when hovering the field

Image Removed

Extension should primarily add the bubble below

• Same styles as now
  • see Image Removed
  • bubble width is the same as field width with border
  • arrow tip should be around 30–40px from the left
• Result: small Vaadin application
  • Apply to a TextField (e.g. using standard Vaadin email validator)
  • If using the Magnolia theme, then field border should become red too
• Currently tooltip is hidden via CSS in Magnolia
  • we can still do this the same way, maybe as well for the warning icon

PoC #3: Complex Fields refactoring

Goals:

• Get rid of Magnolia-specific components within field implementations
• Get rid of AbstractCustomMultiField abstraction

The following three may be done independently:

—without Magnolia component/definition inside field implementations

Pure Vaadin CompositeField

• close to AccessControlField
• Except fields are not hard-coded
  • pass sub-fields into constructor?
    
    • maybe as map with field-names as keys?
  • would help us keeping FieldFactories outside of field implementations
    • i.e. get rid of infamous AbstractCustomMultiField#createLocalField
• also bind fields internally via FieldGroup?
• reuse #setValidationVisible and handling of valueChange on sub-fields
• Result: simple Vaadin application
  • operating over a PropertysetItem or BeanItem
  • part 1. using a CompositeField for First name and Last name
    • laid out horizontally
    • has an API to set direction (minimum requirement)
  • part2. also API to set an arbitrary layout
    • if feasible, but not a must-have
    • or maybe using a Vaadin declarative layout?
      • check out Sasha's talk from mconf16
      • Designing UIs declaratively (Vaadin docs)
      • icing on top of the cake really 

Pure Vaadin MultiValueField

• close to AccessControlListField
• reuse some form of EntryFieldFactory (maybe also NewEntryHandler if applicable)
• Result: simple Vaadin application
  • operating over a PropertysetItem or BeanItem
    • i.e. extends CustomField<I extends Item>
    • or extends CustomField<C extends Collection> (maybe more in line with Vaadin 8?)
  • with a property of type Collection or List, then one entry per entry in the collection
  • field needs to create Vaadin properties for each entry in the list, and bind it internally to sub-fields
  • also bind fields internally via FieldGroup?
  • reuse validation and valueChange logic from AccessControlListField
  • steps:
    1. a MultiField of TextFields (can be hard-coded)
    2. a MultiField of a CustomField type (First name + Last name)
    3. a MultiField with the pluggable NewEntryHandler (closer to use cases in Magnolia where subfields are configured)

Pure Vaadin LinkField

• Inspired from AccessControlField$PathChooserHandler
• Result: small Vaadin application
  • see info.magnolia.dev.acls.AccessControlFieldUI in Mika's sandbox
  • opens a Vaadin Window
    • field inside the window shares property data-source with text field

4. Integration phase

- To be determined

...

• e.g. still as a small Vaadin application, but combining configured forms, complex fields, sub-field validation and a dynamic behavior

A new Form “component”

• Focus on The Big Role
• Create a Vaadin form that can be bound to Magnolia content
• Most often produce fields from config / definitions
• Most often bound to JCR items, and saving the session

Separation of concerns

1. Field creation
   • Responsible for producing raw fields with UI presets, unbound
   • New FieldFactory: Creating Field from FieldDefinition => clear and simple
2. Data-binding
   • New binding ways, using FieldGroup (later V8 Binder) instead of set/get datasource in Factory
   • Responsible for binding, default-values, transforming, converter, validation setup
   • Item variation (i18n, p13n) through re-binding? 
3. Layout
   • Responsible for laying out fields in order
   • Plain Vaadin form with tabsheets, no need to customize, code is more clear and easy to maintain

Flexibility

• Primarily through delegation to functional interfaces
• Ideally also through decoration (TBD)
• Alternatively through extension (config typically mandates implClass)
• Less through custom field-factories
• Less through complex fields

Configuration

• Support current common cases ootb, without config changes
• Gained flexibility is not necessarily exposed through config at first
• Rather whoever opens the form/dialog is responsible for its setup
  • e.g. OpenEditDialogAction
  • entails providing sugar / builders with good defaults
• Introduce simplified + more advanced config gradually
  • e.g. fields on root level / less nesting, layout config
• No intent to expose config on technical terms
  • e.g. no defs for bindings, delegates, generics, all sorts of highly technical classes
• No intent for declarative config of interaction logic between fields

4. PoC phase

The PoC phase was conducted in September–October 2016. Refer to child-page Dynamic forms - PoC phase for details and outcome.

5. Productization phase

Based on the PoC results, we first collected the following tasks, in order to bring new forms on par with the current Magnolia forms.

...