Wizard API - Summary of problems and plan for changes$Revision: 1.2 $ Jiri Rechtacek
Abstract:The document describes known issues, known requirements, plans, future directions of wizard's framework. Also describes typically use-cases wizard's framework and general principles of redesigned API. The standard API architecture review is tracked by issue 36584.
October 16, 2003:
Preliminary plan was attached. Also this document was
split to this summary, document Requirements on
changes and Solution design documents design the
Wizard API? was proposed.
Names conventionIn order to provide a good comprehension and clarity of this document, user means end-user works with wizard, client means a developer who builds on the top
Wizard API. Page means one sheet (or dialog) in sequence of wizard's dialogs. User's forward/backward from one page to another is Step.
- Current implementation
- Problems and the suspect places in current
- Strong asked requirements
- Holes in current
- Fix or redesign
- General basics and constraints
- The supported use cases
- Extend new API with aspects from Templates
- How to handles templates with new
UI Guidelines for NetBeans Wizards
Wizard API (javadoc)
Templates wizard (javadoc)
Wizard API should be easy and useful framework provides creating and
handling dialogs which leads a user step-to-step through task. We want to bring
a response on requirements to the clients to make the API easy-to-use and easy-to-build on it. First
goal is make the summary of the requirements, next, to propose the changes and also
to document the supported use-cases.
- general problem of wizard's framework (the main area of interest of this document)
- problems of template wizard's implementation (although template
wizard is only one extension of
Wizard APIis a key use-case, very close of wizards framework, it's also matter this document)
- issues of the concrete wizards provided by core module, e.g. Mount wizard (these problems partly depend on general wizard's problem, partly are specific in concrete implementation). These won't be a point of interest this document.
- UI (focus, fontsize problem, A11Y problems)
- step management
- performance (memory leak)
Wizard APIdoesn't provide a asked control of movement across wizard's panels, more control the enabling/disabling of the buttons and make more possible cooperation several modules on a shared wizard.
- enable/disable buttons
The Next and Finish are controlled by
WizardDescriptor.Panel.isValid(), it cannot be enabled or disabled independently. Moreover, Finish button can enabled only on panel which implements FinishPanel, it's static and prohibitive of react to filled values.
Enhancement requires extension of
Wizard APIwith suitable methods. It's tracked by issue 7706.
- enable veto processing Next/Finish buttons and keep user on
During enter values in a wizard's panel, framework does validation on all changes. If the panel is valid, user can forward to next panel or finish wizard. If the panel is not valid that user cannot forward. There are a several problems: user doesn't know what's wrong why a panel is not valid, the validation on all changes must be lightweight for performance reasons and there is not place for heavy validation e.g. deploy a remote object on application server which can pass or fail. Next problem appears if a wizard finished unsuccessfully, user cannot change some value and finish wizard again. Here will be vetoable processing Next/Finish buttons very useful.
For reach this functionality, current
Wizard APIshould be enlarged for "off-line" validation, called in right time. Corresponding issue is feature 23116.
- postpone irreversible changes (e.g. create a folder) during walk
around the panels
During walk around the panels might create new objects e.g. new folder in filesystem or deployed remote object on server. These object can persist although the wizard is canceled. The changes could be postponed till Finish action is performed if possible. It also depends on a support of reversible creating object on a target system (e.g. filesystems).
Wizard framework should allow postpone creating new objects if possible and also allow cleanup these objects when the wizard is canceled. The current API could do that with the minor problems. Strengthen support depends on support of reversible changes in target system.
- add a compound iterator to support sharing a wizard between
Because wizard can be shared between several modules then
Wizard APIshould support the compound iterator which reflects this fact. The panels involved in a wizard could be branched by infilled values. The step management in current API doesn't support it, especially TemplateWizard breaks it. This is one of key requirements, tracked by issue 35787. The concept, how to handle this, hasn't been known yet. A depending requirement asks a possibility of declarative registration of panels.
- add support for long-term processing a forward step (mainly the
Processing Next or Finish buttons can take long-term, the current wizards don't provide feedback to user (i.e. wizard is closed and some task runs). Feedback should use a progress bar and provide a Summary page at the end of panel which will inform about upcoming actions. "off-line" validation (described above) could help too. See issues 27512 and 30216.
- separate Template wizard from openide/loaders and don't depend on old
Most used wizard, Template Wizard is based on openide/datasystems which are currently deprecated thus there are the required actions: Separate
TemplateWizardfrom openide/loaders package and don't depend of old datasystems, research how to handle creating templates on the top of new datasystems. This will be discussed in Templates section. A other requirement is how to enlarge
Wizard APIwith useful methods from
TemplateWizard.instantiate()is called when the wizard is finished and performs instantiation of new objects. Method like this should be added in
Wizard APIas central point for creating new object. It's tracked by issue 34043
Wizard APIforces developers to use
JComponent.putClientProperty()to communicate to the wizard infrastructure. API is not well-documented, not specify definite contract about a calling sequence. Some desired methods are missing.
The implementation of
WizardDescriptormixes the control functionality and UI presentation, some UI aspects are hardcoded.
- Minimalize changes of client's side.
- Allows incremental delivery.
- The massive changes in API implementation could break the undocumented contracts.
- The API will remarkable enlarged with new concepts (new methods and new interfaces, the possibility to declare the panels), it makes the API less well-arranged and more inconsistent.
- The asked requirements will be cleanly covered in new API and its implementation
- Get rid of using
- Split the
Wizard APIson one execute/data part and UI part.
- Guided the clients with new API.
- Changes of client's side if s/he will used use API.
- Some (wanted) features of current implementation will not be supported.
Submitter's proposal: In the light in Fixes cons and Redesign pros I propose make new API based on supported use-cases. To avoid force the changes on the client side then the current API and its implementation won't be changed but will be deprecated. The new API will be separated to own package contained API, SPI and the whole wizard's framework. This intention was submitted to Architecture Review, tracked by issue 36584.
Reviewer's proposal: In the light in Fixes cons and Redesign pros I propose make new API based on supported use-cases. To avoid big bang effect and to pick up as much of low hanging fruits as possible while minimazing the impact on the existing implementation we propose to start with incremental implementation of small changes (get rid of
putClientProperty, better control of next/finish buttons, composition of iterators, etc.) in a
alternative(e.g. provide special handling of some interfaces, while leaving the handling of original interfaces untouched as much as possible). The ultimate goal is of course clean and powerful API, but in our current state that seems like a holy grail and we can improve the user and API user experience by a small compatible improvements than big bang rewrite. The complete rewrite could be a solution, but only if the implementation team provided some guarantees that a the new implementation will be
better(support those good things currently supported, will be more stable, more performant, the API flow will be cleared, etc.). But as current comments to the Architecture Review show, there is not too much opinions that would support such expectation.