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 well be displayed to the user in a language that the support staff doesn't understand).

Client Side

Validation Scope

Field-level Validation

Data Validation is run when a user leaves a Control whose DataColumn that the Control is bound to has associated Data Validation code.

• Automatically generated and (optionally) manually written code performs the validation of the data that the Control is bound to. Multiple errors/warnings can be recorded for a single DataColumn.
• In case the Data Validation fails,
  • an instance of TVerificationResult is created for each Data Validation error/warning. This/these are then added to the Collection of Data Validation errors/warnings of the Form that hosts the Control (FPetraUtilsObject.VerificationResultCollection).
  • automatically generated code will display a ToolTip near the Control. The ToolTip text explains what is wrong (this text comes from the associated TVerificationResult).

Record-level Validation

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

• Automatically generated and (optionally) manually written code performs the validation of the data of the current record. All DataColumns may be checked for data validation errors/warnings. Multiple errors/warnings can be recorded for a single DataColumn.
• In case the Data Validation of a record fails,
  • an instance of TVerificationResult is created for each Data Validation error/warning. This/these are then added to the Collection of Data Validation errors/warnings of the Form that hosts the Grid (FPetraUtilsObject.VerificationResultCollection).
  • automatically generated code will display a MessageBox, potentially listing several data validation errors/warnings that pertain to the current record. The text of the MessageBox explains what is wrong (the texts come from the TVerificationResult[s] that pertain to the current record).
  • after the user chooses OK in that MessageBox automatically generated code will prevent the user from navigating to another record in that Grid if there was at least one TVerificationResult recorded for the pertaining record that constituted an error rather than a warning.

Form-level Validation

Data Validation is run when the user presses the 'Save' button or chooses Menu 'File' -> 'Save', or when the user closes a Form and the Form contained changed data.

• Automatically generated code in the 'SaveChanges' Method causes automatically generated and (optionally) manually written data validation code 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 Data Validation errors/warnings of the Form (FPetraUtilsObject.VerificationResultCollection) contains data validation errors or warnings,
  • automatically generated code will display a MessageBox, listing all Data Validation errors/warnings that are recorded for the Form. The text of the MessageBox explains what is wrong (the texts come from all the TVerificationResult[s] that are recorded for the Form);
  • after the user chooses OK in that MessageBox the data saving operation of the Form is cancelled by auto-generated code.
    • Exception: If all TVerificationResults in the FPetraUtilsObject.VerificationResultCollection were 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 manually by the programmer when the user tries to switch to another Tab.

• In case the Collection of Data Validation errors/warnings 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 by the programmer. This needs to be done in the same manner as it is done by the auto-generated code in the other Data Validation scopes.
  • after the user chooses OK in that MessageBox the Tab-switching operation is to be cancelled by the programmer.
    • Exception: If all TVerificationResults that pertain to that UserControl were warnings and not errors, the Tab-switching needs to be allowed to go ahead by the programmer 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