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

Abstract

Using forms and dialogs should feel natural for a developer. The current implementation is flexible, but not very clear. Where to add actions, what classes are important.

Steps

Update SubAppDescriptor 

subApp

  • editor
    • form
    • actions
      • actionName (maps to subapp actions)
  • actions
  • ..

TODO: move description and label from form to editor

Drop FormPresenterFactory
  • Use IOC for the FOrmPresenter.
  • pass formDefinition into start method
Changed role of FormDialogPresenterFactory
  • openDialog methods

TODO: rename to DialogUtil or something

Renaming of ContentApp classes

ItemWorkbenchPresenter -> ItemPresenter

ItemPresenter -> EditorPresenter

 

ContentWorkenchPresenter -> Contentpresenter

ContentPresenter -> Workbenchpresenter

 

These changes reflect the hierarchy in the configuration

On the map
  1. remove usage of DialogActionRegistry
    1. ActionDefinition (FormActionDef can be dropped -> ConfigActionDef) has Default implementation set, can be overriden
  2. formDefinition -> form
  3. drop DialogBuilder 
  4. info.magnolia.ui.form.FormPresenterImpl remove all references to actions and callback

 

info.magnolia.ui.vaadin.form.Form

remove dataSource 

 

https://www.evernote.com/shard/s248/sh/fb0ec1cd-307f-4bdd-bef1-08a4a621e087/d97c8d46e5314eff588a88be9a2d4902

 

Analysis

Documentation

The documentation needs to be updated. Use the Employees App to showcase dialog usage. Form and ItemSubApp is already in place.

Form

  • Do we want to have action definitions for forms or should the container take care of actions?
    • container = dialog, itemView in AbstractItemSubApp
    • If itemView is container we can't use the defined actions like info.magnolia.ui.admincentral.form.action.SaveFormAction
  • Configuration
    • formDefinition currently in workbench and dialog definition.
    • itemType registry and configure form per item?

Dialog

  • info.magnolia.ui.admincentral.dialog.builder.DialogBuilder lost relevancy after introducing FormBuilder
    • only some setters beeing used.
    • action mapping done in info.magnolia.ui.admincentral.dialog.DialogPresenter.DialogPresenterUtil
  • Registry for dialogs

FormDialog

  • info.magnolia.ui.admincentral.dialog.FormDialogPresenterImpl vs info.magnolia.ui.admincentral.form.FormPresenterImpl
    • too similar

Actions

  • dialogActionRegistry
    • used for forms and dialogs
  • callback concept at least needs some documentation
    • info.magnolia.ui.admincentral.dialog.DialogPresenter.Callback.Adapter usecase?
    • for forms?
  • how to properly hook dialog actions and form actions?

Decisions

  • General
    • documentation needs to be updated to reflect latest changes
    • Review needed
      • simplify builders, drop dialogBuilder?
      • views and presenters
    • migration needs to reflect latest changes
      • currently only the bootstrap files are changed and have the new form node under the dialog node.
      • currently there won't be any changes to the current configuration of dialogs and form, except for the removal of actions from the form
    • make some developer tests, after first iteration
    • formDefinition -> form

  • Major sub tasks

    • Dialog and Form relationship
      • hide complexity with convenient methods or reduce it generally
    • Dialog Actions
    • Form Fields

UML Diagrams with annotated Problems and Proposals

Diagrams and Notes made in the meeting.

type key summary assignee reporter priority status resolution created updated due

Unable to locate Jira server for this macro. It may be due to Application Link configuration.

Future Improvements

  • FormDialog class has to be refactored/removed: this class used to be a significant component that was combining the Form and the Dialog. Now it doesn't do anything
    except for forwarding the method calls to the internal FormView. This class has to be removed or should actually implement functionality of the FormView.
  • FormView interface, ItemFormView which implements it. Should be renamed as the implementation contains a Form in the Dialog chrome and now Form and Dialog are separate concepts. 
    I propose it to become an EditorView (ItemEditorView). As mentioned above - these could be merged with FormDialog.
  • BaseDialog should now become a DialogLayout.
  • DialogActionListener has to get a better name as now it is used in both ItemPresenter and FormDialog concepts (EditorActionListener??).
  • Form/FormView should not manage validation and data-binding on their own. Instead the FormBuilder should assemble the FieldGroup and provide it to the Form, which in turn should 
    simply lay out the fields. This would allow us to enhance the workflow with forms, introduce transactional editing, simplify validation (drop our code in favor for the similar in FieldGroup).
  • Many duplicate actions and actions with wrong names (related to Form/Dialog but not mentioning the new editor concept). Also the code of actions should be reviewed (e.g. access to protected fields like 
    callback, validator, item in SaveFormAction is duplicated by getter methods).
  • Clear naming and structure of classes related to i18n: FormItem <- AbstractFormItem <- Form, Dialog, TabDefinition etc. The problem here is that the class names conflict with UI components,
    the hierarchy is not clear: both definition classes and field builders are present in it - we need to review it.
  • Utilize Vaadin commit form process. Instead of just validating the form in the save action we could actually do the normal Vaadin commit cycle - validation + updating the buffered components -> we can 
    use transactional properties and Buffered forms.

 

 

 

 

  • No labels

4 Comments

  1. The refactor will also need to address classes like DialogAdaptingToFormView and EditorLike.

    An Idea:

    • Creating a new component which simply handles the header and footer, and their contents such as title, description, toolbars, footer-actions.
    • This component also accepts a contents component (setContent)- which could be a form, or the contents of a dialog.
    • This component could be used in an item SubApp, or it could be included in a modal dialog. 
      • A Modal would just implement a panel which opens modally - and use composition to include this component to create the header and footer as described above.
      • A Form refers just to the form - it does not include the header and footer. (Hmm - but FormDefinition might still include Title, Desciption, Help message.)
      • An ItemSubApp uses composition to include this "ModalPanel", and put a Form in it.
    • It could be called something like:
      • DialogPanel
      • DialogFrame
      • InteractionPanel 
        • Its good to avoid using "Dialog" or "Form" since it can be used by both of these things.

     

     

    A diagram showing the different "elements" and how they are used. 
    Im suggesting that the elements should all be different classes, and that the uses use composition to assemble the elements to meet their UI requirements. 

  2. Meeting minutes February 12

    1 field builders
    -> vaadin 7

    2 Form / Builder depend on JCR API?
    -> Adapters

    3 Actions on Container(dialog etc)

    4 View / Edit

    4 Naming of fields and properties

    5 UML of Presenter, Callback
    Choose Dialog

    6 -> 2 Headers and footers
    - > Form & Dialog

    7 Modality

     

  3. Here's my input after the March 15th meeting


    what is a form?

    • it has label, description, i18nBasename, tabs with fields, and buttons
    • it does not imply a visual representation, but we provide widgets+presenter+views for the default look
    • it by default has two buttons, save and cancel
    • you can add buttons that execute custom code and either cause the form to be submitted/closed or remain open
    • a button is NOT responsible for closing the dialog when the form sits in a dialog

    what is a form dialog?

    • a form dialog displays a form in a window
    • it provides the visual representation of the form and shows the label and description of the form
    • a form dialog closes when a button in the form says the form is submitted

    whats in an item sub app?

    • it shows a form in a visual style that is similar to the way they appear in form dialogs
    • an item sub app does not necessarily close when a button in the form says the form is submitted

    what do you configure on a dialog?

    • the id and the form definition ONLY
    • the dialog does not have a label, or a description, or an i18nBasename
    • configuration of a dialog is NOT a configuration of a ui component

     actions / buttons

    • the only reason to have buttons execute actions is for reuse of configuration
    • most dialogs are used in templating, so their actions/buttons MUST NOT depend on an action registry somewhere
    • it can make sense if a button executed code that was specially crafted to execute an action with the sub apps executor
    • buttons MUST return whether the form is submitted or not

     IN SUMMARY

    • forms MUST be independent from dialogs and item sub apps or any other use case we come up with
    • when you configure a form you MUST NOT have to configure actions that are specific to where the form will be displayed, i.e. use a FormAction or a DialogAction
    • header + footer + other style elements is not part of the form, its a presentation style that is provided by whoever makes sure the form is shown on the screen. we will use the same vaadin component for this, maybe call it FormPanel
    • a user thinks about forms, not how they appear, the user doesn't care about dialogs
    • when a user designs a form he does NOT make it dependent on a certain use case because a form can appear in a number of places

     

    Screenshots of configuring a dialog and of configuring a form in an item sub app