Skip to main content
Jump to: navigation, search

Difference between revisions of "Scout/Concepts/Form"

m (Description)
m (permute screenshot and lifecycle)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{ScoutPage|cat=Concepts}}
+
{{ScoutPage|cat=Client}}
  
 
A form is both a model structure of a ui concept known as dialog or view and also a model of a {{ScoutLink|Concepts|Wizard|wizard}} page. Wizard {{ScoutLink|Concepts|Button|buttons}} are added automatically to the main box if missing.
 
A form is both a model structure of a ui concept known as dialog or view and also a model of a {{ScoutLink|Concepts|Wizard|wizard}} page. Wizard {{ScoutLink|Concepts|Button|buttons}} are added automatically to the main box if missing.
Line 7: Line 7:
  
 
== Description ==
 
== Description ==
{{note|TODO|Add a description}}
+
Each form contains:
TODO:  
+
* 0..n {{ScoutLink|Concepts|Variable|Variables}}.
* Contains {{ScoutLink|Concepts|Field|fields}} and {{ScoutLink|Concepts|Variable|variables}}.
+
* 0..n {{ScoutLink|Concepts|KeyStroke|Key Strokes}} (inner classes implementing <tt>IKeyStroke</tt>).
* MainBox Field (the main {{ScoutLink|Concepts|GroupBox|GroupBox Field}} at the root of a Form)
+
* exactly 1 MainBox field (inner class implementing <tt>IGroupBox</tt>): this is the root {{ScoutLink|Concepts|GroupBox|GroupBox field}} containing the other {{ScoutLink|Concepts|Field|fields}}
* {{ScoutLink|Concepts|Form Handler|Handlers}}: start the form with different behaviors (e.g. <code>startNew()</code> and <code>startModify()</code>)
+
* 0..n {{ScoutLink|Concepts|ToolButton|Tool Buttons}} (inner classes implementing <tt>IToolButton</tt>),
 +
* 1..n {{ScoutLink|Concepts|Form Handler|Form Handlers}} (usually defined as inner classes implementing <tt>IFormHandler</tt>, but since the handler is set as parameter of <tt>AbstractForm.startInternal(IFormHandler)</tt> the handler can be defined everywhere). The form handler starts the form with different behaviors (e.g. <code>startNew()</code> and <code>startModify()</code>)
 +
 
 +
A Form can be opened as a Dialog or as a View (see {{ScoutLink|HowTo|Open_a_Form_in_a_View|How to open a form in a view}}).
  
 
{{ScoutLink|Concepts|Form/Example|Java code of a simple form}} as example.
 
{{ScoutLink|Concepts|Form/Example|Java code of a simple form}} as example.
  
See also {{ScoutLink|Concepts|Search_Form|SearchForm}}
+
See also {{ScoutLink|Concepts|Search_Form|SearchForm}}.
 +
 
  
 
== Screenshot ==
 
== Screenshot ==
{{note|TODO|Add a screenshot (or remove this section, if there is no screenshot to make)}}
+
<gallery>
 +
Image:Scout Form.png|Form as Dialog
 +
Image:Scout Form View.png|Form as View
 +
</gallery>
 +
 
 +
 
 +
== Form lifecycle ==
 +
 
 +
Typically a form will be loaded with data coming from the server (using a FormData as data transfert object) and be displayed to the user. The user can interact with the form and if he makes some modifications that needs to be persisted in the server.
 +
 
 +
In a lot of applications, the flow of data is not the same if the form is used to create a new entity or to modify an existing entity. This is why each form works with Form Handler that precise. By default the SDK creates a ModifyHandle and a NewHandler, but everything is possible depending on your use case. For example a ViewHandler might be useful for the case where the user cannot do any modification, or a WizardHandler might be useful for the special case where the form is embedded as step of a wizard. In a typical scenario the Form Handler will at least load the data during its {{ScoutEvent|Load}} event and store them during its {{ScoutEvent|Store}} event.
 +
 
 +
The state of the form can be checked with different methods:
 +
* isFormOpen()
 +
* isFormLoading()
 +
* isFormStored()
 +
* isFormClosed()
 +
 
 +
=== Unsaved changes ===
 +
Scout handles the notion of unsaved changes in a form. Depending on the rendering UI technology the user gets a visual confirmation that he needs to save the form. For example on SWT a form displayed in a view will have a star character <code>*</code> in its title to indicate that the form needs to be saved. Some developers speak from a “dirty marker” for this char. On Mac OSX, the red closing button is also lightly different when the form needs to be saved.
 +
 
 +
The behavior of the framework will not be the same when the user leaves a form if the form contains unsaved changes or not.
 +
 
 +
Each field can contribute information to determine if the form contains unsaved changes or not. By default the value fields compare the current value with the initial values. But custom logic can be implemented.
 +
 
 +
To check if the form contains unsaved changes the method: <code>IForm.isSaveNeeded()</code> can be called. The state returned by this function might be out of date (for example if the state changes due to some business logic like “wait 5 minutes” and not due to some user input). To be sure to get the correct state, you should call <code>IForm. checkSaveNeeded()</code> before calling <code>IForm.isSaveNeeded()</code>.
 +
 
 +
In addition of asking each fields it is also possible to mark that the form contains unsaved changes with the method <code>IForm.touch()</code>. Do not call this method during the formLoading phase (in other words: call <code>touch()</code> in <code>AbstractFormHandler.execPostLoad()</code> and not during <code>AbstractFormHandler.execLoad()</code>).
 +
<code>IForm.markSaved()</code> is the counter part of <code>IForm.touch()</code>. It will indicate that the form contains no unsaved changes. Concretely the state will be changed in each field (the markedChanged() call is propagated in each field of the form).
 +
 
 +
=== Actions and buttons ===
 +
TODO:
 +
* Ok button
 +
* Cancel Button
 +
* Save Button
 +
*Close Button
 +
*closing icon (“X”)
 +
* execOnCloseRequest
 +
https://www.eclipse.org/forums/index.php/mv/msg/796762/1416232/#msg_1416232
  
 +
=== Confirmation Dialog ===
 +
TODO:
 +
When and how to parameterize the form depending on the goal.
  
 
== Properties ==
 
== Properties ==
Line 37: Line 82:
 
* {{ScoutLink|Concepts|FormData|FormData}}
 
* {{ScoutLink|Concepts|FormData|FormData}}
 
* {{ScoutLink|Concepts|Wizard|Wizard}}
 
* {{ScoutLink|Concepts|Wizard|Wizard}}
 +
* {{ScoutLink|HowTo|Open_a_Form_in_a_View|How to open a form in a view}}
 
* {{ScoutLink|Concepts|Client Plug-In|Client Plug-In}}
 
* {{ScoutLink|Concepts|Client Plug-In|Client Plug-In}}

Latest revision as of 12:25, 25 September 2014


Scout
Wiki Home
Website
DownloadGit
Community
ForumsBlogTwitterG+
Bugzilla
Bugzilla


A form is both a model structure of a ui concept known as dialog or view and also a model of a wizard page. Wizard buttons are added automatically to the main box if missing.

  • implements: I obj.pngIForm
  • extends: C obj.pngAbstractForm

Description

Each form contains:

  • 0..n Variables.
  • 0..n Key Strokes (inner classes implementing IKeyStroke).
  • exactly 1 MainBox field (inner class implementing IGroupBox): this is the root GroupBox field containing the other fields
  • 0..n Tool Buttons (inner classes implementing IToolButton),
  • 1..n Form Handlers (usually defined as inner classes implementing IFormHandler, but since the handler is set as parameter of AbstractForm.startInternal(IFormHandler) the handler can be defined everywhere). The form handler starts the form with different behaviors (e.g. startNew() and startModify())

A Form can be opened as a Dialog or as a View (see How to open a form in a view).

Java code of a simple form as example.

See also SearchForm.


Screenshot


Form lifecycle

Typically a form will be loaded with data coming from the server (using a FormData as data transfert object) and be displayed to the user. The user can interact with the form and if he makes some modifications that needs to be persisted in the server.

In a lot of applications, the flow of data is not the same if the form is used to create a new entity or to modify an existing entity. This is why each form works with Form Handler that precise. By default the SDK creates a ModifyHandle and a NewHandler, but everything is possible depending on your use case. For example a ViewHandler might be useful for the case where the user cannot do any modification, or a WizardHandler might be useful for the special case where the form is embedded as step of a wizard. In a typical scenario the Form Handler will at least load the data during its Load event and store them during its Store event.

The state of the form can be checked with different methods:

  • isFormOpen()
  • isFormLoading()
  • isFormStored()
  • isFormClosed()

Unsaved changes

Scout handles the notion of unsaved changes in a form. Depending on the rendering UI technology the user gets a visual confirmation that he needs to save the form. For example on SWT a form displayed in a view will have a star character * in its title to indicate that the form needs to be saved. Some developers speak from a “dirty marker” for this char. On Mac OSX, the red closing button is also lightly different when the form needs to be saved.

The behavior of the framework will not be the same when the user leaves a form if the form contains unsaved changes or not.

Each field can contribute information to determine if the form contains unsaved changes or not. By default the value fields compare the current value with the initial values. But custom logic can be implemented.

To check if the form contains unsaved changes the method: IForm.isSaveNeeded() can be called. The state returned by this function might be out of date (for example if the state changes due to some business logic like “wait 5 minutes” and not due to some user input). To be sure to get the correct state, you should call IForm. checkSaveNeeded() before calling IForm.isSaveNeeded().

In addition of asking each fields it is also possible to mark that the form contains unsaved changes with the method IForm.touch(). Do not call this method during the formLoading phase (in other words: call touch() in AbstractFormHandler.execPostLoad() and not during AbstractFormHandler.execLoad()). IForm.markSaved() is the counter part of IForm.touch(). It will indicate that the form contains no unsaved changes. Concretely the state will be changed in each field (the markedChanged() call is propagated in each field of the form).

Actions and buttons

TODO:

  • Ok button
  • Cancel Button
  • Save Button
  • Close Button
  • closing icon (“X”)
  • execOnCloseRequest

https://www.eclipse.org/forums/index.php/mv/msg/796762/1416232/#msg_1416232

Confirmation Dialog

TODO: When and how to parameterize the form depending on the goal.

Properties

Defined with getConfiguredXxxxxx() methods.



Events

Defined with execXxxxxx() methods.



See Also

Back to the top