Instructions for the Implementation of Data Validation

DOCUMENTATION IS WORK IN PROGRESS

This wiki page is under construction. Information contained on it should not be relied on until this message is no longer present!!!

Overview

In OpenPetra, different aspects of Data Validation need to be implemented in several places to make the whole 'Data Validation Framework' work - on Client Side and Server Side.

The sections below detail what needs to be done and in which places to make Data Validation work. Following the way that is presented in those sections will help you in creating Data Validation and should help the whole development team to code Data Validation in a common and standardised way.

Client Side

YAML File of a Form or UserControl

• For every Control to which manual Data Validation should be added, the Attribute Validation=true needs to be added.
  • The 'Validation' Attribute is not available for Controls that group other controls, such as GroupBoxes, Panels, TabPages, UserControls, etc. - It is available only for individual Controls.

Examples

• dtpDetailMailingDate: {Label=Mailing Date, Validation=True} (found in \csharp\Petra\Client\MPartner\Gui\Setup\MailingSetup.yaml)

Once the YAML file gets (re-)generated with the WinForms Generator (using the nant generateWinForms command), support for Data Validation will be added to the auto-generated C# code file of the Form/UserControl if the 'Validation' property has been set to 'true' for at least one Control. (If automatically generated Data Validation code for Controls is present in the auto-generated C# code file of the Form/UserControl, support for Data Validation will be added/will have been added to that file even if no manual Data Validation is specified.)

Multiple Controls involved in a single Data Validation

TODO

*.ManualCode.cs File

In order for the manual Data Validation to be doing something useful, the following Method needs to be present in the *.ManualCode.cs file of the Form/UserControl:

private void ValidateDataDetailsManual(RowType ARow)

(where RowType is the Type of the Typed DataRow that is to be validated in this screen, e.g. 'PMailingRow' for a screen that edits 'p_mailing' DB Table records)

After adding this Method, nant generateWinForms needs to be run for the corresponding YAML file. This ensures that this Method is called from the generated code of the Form/UserControl and that through that the manual Data Validation code will be run in all circumstances where it needs to be run.

The content of the Method follows a standard pattern:

1. The content of the first line is always TVerificationResultCollection VerificationResultCollection = FPetraUtilsObject.VerificationResultCollection;
2. A single emtpy line follows.
3. A single call to a Method that is defined in a Shared DLL follows.

This Method needs to have a ref VerificationResultCollection Argument, among other Arguments. By modifying that Collection this Method can add or remove specific TVerificationResult objects to/from the Form's Collection of TVerificationResult objects (which is always held in the FPetraUtilsObject.VerificationResultCollection object). (This Method can optionally inspect that Collection for other TVerificationResult objects and evaluate those [that is needed only for complex data validation scenarios, though]. As the Collection will hold all TVerificationResult objects of the Form, TVerificationResult objects from other parts of the screen [namely those created by another UserControl, perhaps situated even on a different TabPage of the same Form] can be inspected!)

Example: File \csharp\ICT\Petra\Client\MPartner\Gui\Setup\MailingSetup.ManualCode.cs

private void ValidateDataDetailsManual(PMailingRow ARow)
{
    TVerificationResultCollection VerificationResultCollection =  FPetraUtilsObject.VerificationResultCollection;

    TSharedPartnerValidation_Partner.ValidateMailingSetup(this, ARow, ref VerificationResultCollection, FPetraUtilsObject.ValidationControlsDict);
}

For information about the Method that is defined in a Shared DLL please see the section Shared Libraries.

For Information Only: Generated Form File

TODO

Shared Libraries

TODO

Utilising Special Functionality

Accessing a Cacheable DataTable

• Use Ict.Petra.Shared.TSharedDataCache

TODO

Accessing Server-side Functionality that is exposed to the Client

Example: Calling the TServerLookup.TMPartner.VerifyPartner Method

• PetraClientMain.cs, InitialiseClasses: TSharedPartnerValidationHelper.VerifyPartnerDelegate = @TServerLookup.TMPartner.VerifyPartner;
• Ict.Petra.Shared.MPartner.Validation.TSharedPartnerValidationHelper
  • public static TVerifyPartner VerifyPartnerDelegate
  • public static bool VerifyPartner

TODO

Server Side

TODO