Overview of the Data Validation Framework

DOCUMENTATION IS WORK IN PROGRESS

This wiki page is currently being overhauled to reflect the implementation of the Data Validation Framework.

What the Data Validation Framework Provides

• A common model in which data validation is done in OpenPetra.
  • Although the way how data validation is done differs on server and client side due to the different nature of these sides, there is still a common model (the Validation Framework) behind it.
• It supports a variety of situations in the most effective manner.
• It makes the raising of data validation errors and the handling of those as painless and easy for the software engineers as possible.
• It ensures that data validation errors are brought to the attention of the users in a standardised way.
• All data validation warning/error messages can be translated.
  • All data validation warnings/errors have a unique 'Error Code' that makes it possible to identify what warning/error the user is faced with. This is especially important for support staff as they will be able to identify the warning/error even if they aren't able to read the warning/error message (as it might be displayed in a language that they don't understand).

Client Side

Validation Scope

Field-level Validation

Data Validation runs when user leaves a Control that has associated data validation code.

• Manual Code performs the validation of the data that the Control is bound to.
  • In case the data validation of a Control fails...
    • a ToolTip is displayed near that control. The ToolTip text explains what is wrong.
    • the validation error is added to a Collection of validation errors of the Form that hosts the Control (FPetraUtilsObject.VerificationResultCollection).

Record-level Validation

Data Validation runs when user changes to a different record in a Grid.

• Manual Code performs the validation of the data of the record. All DataColumns may be checked for data validation errors.
  • In case the data validation of a record fails...
    • a MessageBox is displayed, potentially listing several validation errors of the one record. The text of the MessageBox explains what is wrong.
    • the user is prevented from navigating to another record in that Grid.
    • the validation error is added to a Collection of validation errors of the Form that hosts the Control (FPetraUtilsObject.VerificationResultCollection).

Form-level Validation

Data Validation runs when the user presses the 'Save' button or chooses Menu 'File' -> 'Save'.

• Code in the 'SaveChanges' Method causes data validation to be run on all parts of the Form that the user has been to (e.g. various UserControls that got delay-loaded by switching to various TabPages).
  • In case the Collection of validation errors of the Form (FPetraUtilsObject.VerificationResultCollection) contains errors or warnings, all validation messages are shown in a MessageBox to the user and the saving operation is cancelled. Exception: if there were only validation messages that are warnings and not errors, the saving is allowed to go ahead after the user chooses 'OK' in the MessageBox.

Tab-level Validation (On Screens with Tabs)

Data Validation needs to be done by the programmer (manually) when the user switches to another Tab. ** In case the Collection of validation errors of the Form (FPetraUtilsObject.VerificationResultCollection) contains errors or warnings for the UserControl that holds all the content of the TabPage, all validation messages that pertain to that UserControl need to be shown in a MessageBox to the user and the Tab-switching operation is to be cancelled. Exception: if there were only validation messages that are warnings and not errors, the Tab-switching is allowed to go ahead after the user chooses 'OK' in the MessageBox.

Data Validation Error Notifications to the User

Intrusive Notifications

These kind of notifications take the input focus away from the Controls in which the user is changing data. They should be used only when the user tries to save data in a form, or when trying to switch to a different TabPage, and data validation errors are present.

MessageBoxes

• Display 1..n TVerificationResults in a meaningful manner in a single MessageBox (rather than in a series of MessageBoxes).
  • In the future we would like to replace the use of MessageBoxes for that purpose with a standard dialog that would contains a Grid. 1..n TVerificationResults would be displayed in that Grid in a nicer way than is currently possible with pure text (e.g. showing an error or warning icon for each TVerificationResult line in the grid, providing hyperlinks to a help topic for certain TVerificationResults, ...).

Less Intrusive Notifications

These kind of notifications do not take the input focus away from the Controls in which the user is changing data.

ToolTips

• We use ToolTips to notify the user of Data Validation errors. One ToolTip at any given time is shown for a Control on the Form if the user leaves a Control that has associated data validation and that data validation fails.
  • The ToolTip is shown next to the Control that failed its data validation.

Idea for the future: Bottom-Docked Panel in Which Error Messages Would be Displayed

• This Panel would only be shown when data verification errors would be raised and would be hidden again once the data verification error(s) is/are resolved.
• Individual data verification errors could be LinkLabels on which the user can click. Clicking those would set the input focus to the offending Control.

WinForms Generator Support for Data Validation

The WinForms Generator creates all the program code that is necessary to automatically and consistently deal with the handling of the Data Validation for any type of Form or UserControl that is defined by a YAML file.

Code is generated for:

• the calling of the auto-generated Data Validation Method(s);
• the calling of the manual Data Validation Method(s) in the *.ManualCode.cs file;
• the evaluation of TVerificationResult objects stored in the TVerifcationResultCollection of the Form (held in FPetraUtilsObject.VerificationResultCollection) - these objects are created if a Data Validation fails;
• the showing of Data Validation ToolTips and MessageBoxes as appropriate and in various contexts (e.g. when the user wants to leave a Control, when the user wants to leave a record in a Grid, when the user wants to save data or close the Form);
• the prevention of saving of data if Data Validation errors are present (saving is allowed to go ahead if only warnings are recorded, though).

The auto-generated code also makes the Controls that are to be validated and the translated Labels of those Controls accessible to both the automatically generated and the manual Data Validation code. The former is needed for setting the input focus to the first Control for which Data Validation failed, the latter is important as it allows the validation messages to contain the Text of the Labels of Controls as they appear to the user in their selected language.

Server Side

Datastore 'SubmitChanges' Methods

At the moment our auto-generated '...SubmitChanges' Methods in the openPETRA Datastore return a TVerificationResultCollection, but that should be changed to Exceptions being thrown instead - see DB Discussions!

General

Use of Centralised Error Code System

See Central Place for Maintenance of Unique Error Codes.

Help File Integration

TODO