Before you start to create an add-on solution for an Acumatica ERP application or to customize an Acumatica ERP application instance, we recommend that you learn about the structure of the involved webpages by exploring .aspx pages, the code of the business logic controllers (BLCs, also referred to as graphs), and the data access classes (DACs) that are used within BLCs.
To help you gain the needed knowledge, this topic covers how to do the following: • Get access to the Acumatica ERP source code
• Analyze attributes of the DACs that are used within the BLC • Find and analyze the data views that are used on the webpage • Explore the structure of the webpage by viewing the .aspx code To facilitate your understanding, this topic includes an example.
| Customization Stages | 81
Getting Access to the Source Code for the Employees Webpage
Suppose that you need to implement a dependency between two Date type fields—Hire Date and Date Of Birth of the Employees webpage, 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 data displayed on the Employees webpage won't be saved unless the user enters an allowed hire date.
First, you should start the Acumatica ERP application and open the webpage to be used in this example by navigating to Organization > Organization Structure > Manage > Employees (which is shown in the screenshot below).
Figure: Exploring the structure of the Employees webpage
As you can see in the screenshot, the General Info tab of the Employees webpage has four groups of input controls. The Hire Date and Date of Birth fields, indicated with green frames, are organized in different groups.
Notice that splitting the webpage into groups (to ease the user's work) is not the same thing as placing input controls onto container controls (the main or auxiliary PXFormView or the auxiliary PXTabItem and
PXListView). Each input UI control belongs to a data view, while this data view depends on the container
control, onto which the particular input UI control is placed. For details, see the Analyzing the Webpage
| Customization Stages | 82
Searching for the DAC and BLC Code
To get optimal results, you should first analyze the corresponding original source code fragments to find out which data access classes contain the fields that are to be validated, as well as how these DACs depend on each other within the appropriate business logic controller data views.
Open the Employees page in page design mode, right-click the Date Of Birth UI field, and select Attributes. In the DataField Attributes window that appears (shown in the following screenshot), note the exact Field Name value (DateOfBirth). Also notice the View Name and Cache Type values: These values appropriately denote the data view of the BLC, to which the container of the UI field is bound, and its main DAC containing the selected UI field. (The main DAC is the DAC that has been specified as the first type parameter of the BQL expression.) Click Cancel to close the window.
Figure: Checking the attributes of the Date Of Birth field
The full data view and DAC names are displayed: PX.Objects.EP.EmployeeMaint::Contact and
PX.Objects.CR.Contact, where PX.Objects is the name of the assembly, EP and CR are the names of namespaces, and EmployeeMaint::Contact and Contact are the names of the data view declared within the BLC and the DAC that includes the DateOfBirth field. The Contact DAC is the main DAC of the
EmployeeMaint::Contact data view.
On the Employees page, right-click the Hire Date field and select Attributes. In the DataField Attributes window that appears again (illustrated in the following screenshot), note the Field Name, View Name, and Cache Type values. Click Cancel to close the window.
| Customization Stages | 83
Figure: Checking the attributes of the Hire Date field
On the Employees page, select Customization and then View Source Code to open the Source Code browser, a special customization facility for UI and functional customization. This gives you access to the source code of the Employees webpage. As the screenshot below illustrates, the Source Code browser has four tabs and the Business logic tab is open by default. The Graph Name value indicates that the Employees webpage is bound to the PX.Objects.EP.EmployeeMaint BLC.
| Customization Stages | 84
Open the Find in Files tab. Type DateOfBirth in the Find Text field and click Find, as shown in the screenshot below. For each search result, you can see the DAC name, the code line number, and the content fragment that includes the DateOfBirth text.
Figure: Searching for the DAC that includes the DateOfBirth field
When more than one DAC is found, you should choose the DAC that includes the required field name (that is, the field name of the required DAC) in a content fragment with the #region declaration, because this means that this DAC actually has the BQL field and property with the same name.
Next, open the Data table declaration tab, click the Magnifier button of the Table Name lookup field, and type within the quick search box (at the bottom of the lookup window) the DAC name—in this case, Contact, and select the PX.Objects.CR.Contact item (because of the CR namespace), as shown in the screenshot below.
| Customization Stages | 85
Click the PX.Objects.CR.Contact full DAC name to specify this name in the Table Name field. As a result, the DAC code appears (see the screenshot below).
Find the DateOfBirth field name in the list of the regions of the DAC, and expand the region with the same name to look through the field definition code. You can expand any region to analyze the code of the region. Pay attention to the whole structure of the DAC—that is, the fields it includes and the order of field declaration.
Figure: Expanding the DAC region
Repeat these actions to find the PX.Objects.EP.EPEmployee DAC and analyze the whole structure of the DAC.
Searching for the Data Views that Contain the Specified DAC Names
Now you should allocate the data views of the PX.Objects.EP.EmployeeMaint BLC code to find out the possible dependence between the Hire Date and Date of Birth fields.
Open the Business logic tab and expand the Selects Declaration code region. Find the PXSelect BQL expressions (data views) with the CurrentEmployee and Contact names that contain, respectively, the EPEmployee and Contact main DACs, as the screenshot below illustrates.
| Customization Stages | 86
Figure: Searching for the views that contain the specified DAC names as main DACs
The BQL expression of the second view (Contact) shows the dependency between the Contact and EPEmployee DACs (through the EPEmployee.parentBAccountID field). This means that you can add logic to the PX.Objects.EP.EmployeeMaint BLC code to implement any kind of restriction, including the age one.
Analyzing the Webpage Structure Through the .aspx Code
By using the Page Aspx tab of the Source Code browser, you can see the webpage structure—that is, the layout of the container controls and the types and properties of the input UI controls.
Open the Page Aspx tab, and the EP203000 screen ID (Employees webpage) is displayed because we opened the Source Code browser from this page.
The screenshot illustrates a code fragment that belongs to the cont3 content ID placeholder. The .aspx code lines of all the tabs of the Employees webpage can be found within this placeholder.
| Customization Stages | 87
Figure: Exploring the first .aspx code fragment of the Employees webpage
If you look for the DataMember string within the current webpage and look through the content of the cont3 placeholder within the General Info tab item, you should notice the following:
• The General Info tab has the CurrentEmployees value for the DataMember property.
The DataMember property value is the name of the data view to which the current container control is bound (the tab control in this case). As you will see, three auxiliary PXFormView container controls had been added onto the PXTabItem control located within the PXTab container control with the following IDs: ContactInfo, AddressInfo, and PersonalInfo. Every PXTabItem control gets the binding from the PXTab container control. Don't confuse the IDs of container controls with the names of the input UI control groups.
• On the Employees page, the PXFormView (or original PXFormView) advanced controls have a DataMember property value that differs from the DataMember value of the selected tab item section.
• Each DataMember property value can correspond to any data view name of the BLC.
Any container control (such as form or grid) or advanced control (such as the PXFormView,
PXTabView, or PXListView ) must be bound to a data view declared within a BLC. Any data view
except for the primary data view, can be used by an unlimited number of containers. The primary data view must be connected to the datasource control (ds) and no more than to one container control.
The second fragment of the .aspx code of the Employees webpage, shown in the screenshot below, illustrates the layout and main properties of the Hire Date and Date of Birth fields.
These fields are placed within the px:PXTabItem tag with the General Info header. Within this tag, each of the four input control groups is defined. If you know the data view and DAC field names, you can find out to which group (the GroupCaption property of the PXLayoutRule class) or placeholder (the Caption property of the FormView class) this field belongs. (In this example, four different groups and three placeholders are used in the Employees webpage.)
Notice that the DataMember value is defined only for the px:PXFormView tag that contains the Date of Birth field—Contact, as highlighted in the screenshot below. As you can see from this and the previous screenshots, the Hire Date field is placed on the main container control and therefore has the CurrentEmployee parent data member.
| Customization Stages | 88
Figure: Exploring the second code fragment of the Employees webpage
You use the Aspx Control Tree or the Layout Editor to specify auxiliary container controls and groups of input controls.
The main difference between a container (or advanced) control and a group of UI controls is their usage: A container control is used both for placing UI controls and for binding them to a data view, while a group is used only for placing UI controls to improve the user interface and make the user's work more convenient.