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, a Method with either Method name needs to be present in the *.ManualCode.cs file of the Form/UserControl:

private void ValidateDataManual(RowType ARow)

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)

The name of the Method depends on whether the Data Validation of a Form/UserControl should validate data in a 'Details Section' (=a pnlDetails Panel).

• If it should not validate data in a 'Details Section', the name of the Method needs to be 'ValidateDataManual' in order to validate the Form's/UserControl's data.
• If it should validate data in a 'Details Section' then the name of the Method needs to be 'ValidateDataDetailsManual' in order to validate the data in a 'Details Section'.
  • If data of the Form/UserContol outside of the 'Details Section' should be validated as well, then the Method named 'ValidateDataManual' needs to be present in addition to the 'ValidateDataDetailsManual' Method in order to validate the data outside of the 'Details Section'. An example of this can be found in \csharp\ICT\Petra\Client\MFinance\Gui\AP\APEditDocument.ManualCode.cs

After adding this Method/these Methods, nant generateWinForms needs to be run for the corresponding YAML file. This ensures that this Method/these Methods is/are 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 either of the Methods follows a standard pattern:

1. The content of the first line is always TVerificationResultCollection VerificationResultCollection = FPetraUtilsObject.VerificationResultCollection;
2. A single empty line follows.
3. A single call to a Method that is to be defined in a Shared DLL follows. That Method performs the actual Data Validation.

NOTE: Although the called Method could reside in a client-side DLL, doing so will make it impossible to perform the Data Validation from the server side! The same would be true if any other code would be added to the Method described in this section - it would be inaccessible from the server side. Since we want Data Validation to work both on client and on server side, the called Method (that contains the Data Validation code) needs to be placed in shared DLL's.

Sample code: (found in 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 called Method that is to be defined in a Shared DLL and which performs the actual Data Validation please see the section Shared Libraries.

For Information Only: Generated Form File

TODO

Shared Libraries

The Data Validation Method

The ValidateDataManual / ValidateDataDetailsManual Method situated in the *.ManualCode.cs file of the Form/UserContro needs to call a Method in a shared DLL. That called Method performs the actual Data Validation:

• If a Data Validation occurs, a TVerificationResult object is created
  • the TVerificationResult object gets appended to a Collection that is held in the Form where the Data Validation is run.
• Once a Data Validation error got rectified by the user, the corresponding TVerificationResult object is removed from the Collection.

NOTE: Although this Method could reside in a client-side DLL, doing so will make it impossible to perform the Data Validation from the server side! Since we want Data Validation to work both on client and on server side, the Method that contains the Data Validation code needs to be placed in shared DLL's!

Typical Method signature:

public static void ValidateMailingSetup(object AContext, PMailingRow ARow,
    ref TVerificationResultCollection AVerificationResultCollection, TValidationControlsDict AValidationControlsDict)

The 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). (The 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!)

The content of the Method follows a standard pattern:

1. There is a Variable declaration section. This is 'boiler plate' code.
2. 1..n 'Data Validation Code Blocks' follow.

Each 'Data Validation Code Block' follows a standard pattern:

1. The DataColumn that is to be validated is stored in the ValidationColumn Variable.
2. A check is done whether that DataColumn should be validated at the current execution of the Method. This is done with a single line of 'boiler plate' code.
3. If so,
   1. the actual data validation code is run,
   2. the addition/removal of the corresponding TVerificationResult is handled. Again, this is done with a single line of 'boiler plate' code.

The check whether the DataColumn should be validated seems strange, but that makes it possible to check for a different set of DataColumns, depending if the Method got called from the client-side or the server-side of OpenPetra.

Sample code: (found in \csharp\ICT\Petra\Shared\lib\MPartner\validation\Partner.Validation.cs)

// 'MailingDate' must not be empty
ValidationColumn = ARow.Table.Columns[PMailingTable.ColumnMailingDateId];

if (AValidationControlsDict.TryGetValue(ValidationColumn, out ValidationControlsData))
{
  // actual Data Validation code goes here

  // Handle addition to/removal from TVerificationResultCollection
  AVerificationResultCollection.Auto_Add_Or_AddOrRemove(AContext, VerificationResult, ValidationColumn);
}

Data Validation Code for a single Data Validation Code Block

The data validation code uses a pattern that is presented here. It can be followed in most data validation scenarios. For scenarios that require a different methodology, code that has the same net effect needs to be written.

Net effect of the data validation code:

• If the data validation fails, a TVerificationResult instance is to be created and it is to be assigned to the local VerificationResult Variable;
• If the data validation succeeds, the local VerificationResult Variable must not be assigned any value. Alternatively, null can be assigned to the local VerificationResult Variable (it is null by default).

Sample code (found in file \csharp\ICT\Petra\Shared\lib\MPartner\validation\Partner.Validation.cs):

VerificationResult = TDateChecks.IsNotUndefinedDateTime(ARow.MailingDate,
    ValidationControlsData.ValidationControlLabel,
    true, AContext, ValidationColumn, ValidationControlsData.ValidationControl);

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

Choosing the right Shared DLL

TODO

Server Side

TODO