This topic includes an example of developing a customization project. In this example, a custom event will be used for the Employees webpage.
Suppose that you need to specify the Date Of Birth UI field as mandatory and organize a possible dependency between two Date type fields—Hire Date and Date Of Birth, for instance—to check the age of the hired employee (which shouldn't be less than 16 years old, in compliance with company and legal restrictions). If the employee is too young, the saving of the Employees webpage must be blocked unless the user enters an allowed hire date.
Analyzing the Source Code
To get optimal validation results, you must first analyze the corresponding original source code fragments to find out which data access classes (DACs) contain the fields that are to be validated, as well as how these fields are bound with one another within the appropriate business logic controller (BLC) views. See Exploring the Source Code.
Creating the New Project
Take the following actions to start creating validation logic:
1. Create a new project (see a project's definition in What is an Acumatica Customization Project?) by doing the following actions:
a. Navigate to Organization > Organization Structure > Manage > Employees, and on the Customization menu, select Open Customization Project.
b. On the Select Working Project window that appears, click New to add the new project. c. On the New Project window that appears, add the project name, such as EP1.
d. Click OK to close the New Project window; then select the Unpublish Existing Customization option (if one is available) and click OK again to close the Select Working Project window and create the new project.
By selecting the Unpublish Existing Customization check box after adding a new customization project's name, you revoke the procedure that cancels publication of all previously published customization projects. You need this procedure to have possibility to work with a single application instance with different customization projects without any risk to meet issues related to possible incompatibility with published projects. This is important for training purposes only.
After the unpublish procedure, which can take rather long time, finishes, you possibly have to select Open Customization Project again, select the created project name, and click
OK to open the project.
2. On the Customization menu, select Enter Page Design Mode to begin customization. Starting to Add Validation Logic
Proceed as follows to add validation logic:
1. On the General Info tab of the Employees page, right-click the Date of Birth input field and select Attributes.
| Customization Stages | 91
2. In the Custom attributes section of the DataField Attributes window that appears, add the default attribute as follows:
[PXDefault(PersistingCheck =
PXPersistingCheck.Nothing)]
, select Append to Original from the How to Apply drop- down list, and click OK (see the following screenshot).Figure: Adding the default attribute for the Date of Birth field
For the PXDefault attribute, the PXPersistingCheck parameter set to Nothing defines that by default, no additional validation logic is implemented to the Date of Birth input field throughout the application.
3. Right-click the Date of Birth input field and select Add Data Event.
4. In the Add Event Handler window that appears, select RowSelected as the event type, keep Contact as the table name, and click OK.
5. In the Custom Code editor, which appears in a separate browser window, modify the initial custom event code so that the resulting code will be the following.
... #region Event Handlers
protected override void Contact_RowSelected( PXCache sender, PXRowSelectedEventArgs e) {
base.Contact_RowSelected(sender, e); var row = (Contact)e.Row;
if (row == null) return;
PXDefaultAttribute.SetPersistingCheck<Contact.dateOfBirth>( sender, row, PXPersistingCheck.NullOrBlank);
}
#endregion
...
For the PXDefault attribute the PXPersistingCheck parameter set to NullOrBlank at run time defines that the Date of Birth input field value cannot equal to null or an empty string only when working with the Employees webpage.
| Customization Stages | 92
7. Return to the Employees webpage and on the Customization menu, select Save Project to Database (EP1).
Implementing the Validation Logic
To implement the validation logic, proceed as follows:
1. Right-click the area of the General Info tab and select Add Data Event.
2. In the Add Event Handler window that appears, select RowPersisting as the event type, keep EPEmployee as the table name, and click OK, as shown in the following screenshot.
Figure: Selecting the event type
3. On the Custom Code editor window that opens again, modify the initial custom event code so that the resulting code will be the following.
using System.Collections; using PX.Common; using PX.Objects.AP; using PX.Objects.GL; using PX.SM; using PX.TM; using System; using PX.Data; using PX.Objects.CS; using PX.Objects.CR; using PX.Objects.CA; using PX.Objects.CM; using System.Collections.Generic; using PX.Objects.AR; using PX.Objects.PM; using PX.Objects; using PX.Objects.EP; namespace PX.Objects.EP { [PXCustomization]
public class Cst_EmployeeMaint: EmployeeMaint {
#region Event Handlers
protected override void Contact_RowSelected(PXCache sender, PXRowSelectedEventArgs e) {
| Customization Stages | 93
base.Contact_RowSelected(sender, e); var row = (Contact)e.Row;
if (row == null) return;
PXDefaultAttribute.SetPersistingCheck<Contact.dateOfBirth> (sender, row, PXPersistingCheck.NullOrBlank); }
protected override void EPEmployee_RowPersisting(PXCache sender, PXRowPersistingEventArgs e) {
base.EPEmployee_RowPersisting(sender, e); var row = (EPEmployee)e.Row;
DateTime? hireDate = row.HireDate;
DateTime? dateOfBirth = Contact.Current.DateOfBirth; if (dateOfBirth == null || hireDate == null) return; DateTime allowedDate = dateOfBirth.Value.AddYears(16); if (hireDate < allowedDate)
{
throw new PXRowPersistingException (typeof(EPEmployee.hireDate).Name,
hireDate,"The employee's hire date must be+" "at least 16 years after birthdate.");
} }
#endregion }
}
The EPEmployee_PXRowPersisting event handler checks the condition to warn the user if the new employee is younger than 16. This validation approach prevents a record from being saved by throwing the PXSetPropertyException.
If the date of birth is null or empty, the common error message is displayed by the
PXDefaultAttribute (such as Error: 'Date Of Birth' may not be empty.)
4. Click Save, then click Validate and Publish. After the validation process has been finished successfully, click Publish to publish the customization project (see the screenshot below).
Figure: Validating and publishing the project
| Customization Stages | 94
Testing the Results
Now you should test the results of the implemented validation logic to ensure that the logic works properly. Perform the following actions:
1. Return to the Employees webpage, close the project, refresh the webpage, if necessary, and try to add a new employee record without entering the Date Of Birth value. Enter values for all the other required fields (marked with the asterisk left of these field names).
2. Click Save: The error message appears that the Lead/Contact record raised one or more errors and the record is not saved. After clicking OK in the error message window, you can position the cursor on the error label left of the Date of Birth label and read the reason of this error (that the Date of Birth may not be empty), as the following screenshot illustrates.
Figure: Trying to save a record with no Date of Birth value
3. Add the date of birth so that the difference between it and the hire date is less than 16 years, and the second error message appears (see the following screenshot). This is the message text added by you to the event code as a parameter of the PXSetPropertyException method.
| Customization Stages | 95
Figure: Entering the Birth Date for the person younger than 16 years
4. Make the hire date at least 16 years later than the date of birth, and click Save. The new record has been saved, as the following screenshot illustrates.
| Customization Stages | 96
To download the deployment package, navigate to System > Customization > Manage > Customization Projects and click Get Package on the form toolbar of the Customization Projects webpage. In the Opening EP1.zip dialog that appears, select Save File (see the screenshot below), then specify path and change the zip-file name, if necessary, in the navigation window that appears, and click OK.
Figure: Downloading the deployment package
To observe the whole XML content of the customization project and download the package, return to the Customization Projects webpage and click Edit XML on the form toolbar. In the window with the whole XML content of the customization project (the name of the project is displayed in the upper part of the window), select Download Package. The next actions are the same (they have been described in the previous paragraph).