Lesson 2: Creating Custom Fields

A manager of the Smart Fix company needs to specify that particular stock items on the Stock Items (IN202500) form of Acumatica ERP are repair items and select the type of each repair item. To implement this scenario, you need to change the UI of the Stock Items (IN202500) form and the database table that stores data for this form. In this lesson, you will use two approaches to perform these changes:

Using the Customization Project Editor to create the custom database column, the data access class (DAC) field, and the UI control
Using Visual Studio to add the DAC field and the Customization Project Editor to create the custom database column and the UI control

UI Changes

In this lesson, you will add the following custom controls to the Stock Items (IN202500) form of Acumatica ERP:

Repair Item: A check box that indicates (if selected) that the stock item can be used during the provision of the repair services of the Smart Fix company
Repair Item Type: A drop-down list box for the repair item type, which is one of the following:
Battery
Screen
Screen Cover
Back Cover
Motherboard You will add these controls to the Item Defaults section of the General tab of the form (see the following screenshot).
Figure: Custom elements to be added to the Stock Items form Lesson 2: Creating Custom Fields | 17

Database Changes

The General tab displays the stock item's general information, which is stored in the data record of the IN.InventoryItem data access class. Hence, you will add the custom fields to this class. To be able to save the repair item data to the database, you will add the database columns for the new values. The IN.InventoryItem class records are stored in the InventoryItem database table; therefore, you will add columns for the new fields to this table.

Lesson Objectives

As you complete this lesson, you will learn how to do the following:

Add a custom column to an Acumatica ERP database table
Add a custom field to an Acumatica ERP data access class
Add the control for the custom field to the form

Step 2.1: Creating a Custom Column and Field with the Project Editor

In this step, you will create a custom column in the InventoryItem database table and a custom field in the IN.InventoryItem data access class for this column. This column and field will be used to store and edit the value of the Repair Item check box. You will use the Customization Project Editor to add the column and field.

          The approach described in this step is the easiest way to create both the column in the database and
          the bound field in the corresponding data access class.
          We recommend that you not write custom SQL scripts to add changes to the database schema. If
          you add a custom SQL script, you must adhere to platform requirements that apply to custom SQL
          scripts, such as the support of multitenancy and the support of SQL dialects of the target database
          management systems. If you use the approach described in this topic, during the publication of the
          customization project, the platform generates SQL statements to alter the existing table so that this
          statement conforms to all platform requirements.

You will create an extension of the IN.InventoryItem DAC to hold custom fields (which is referred to as a DAC extension or cache extension). Acumatica Customization Platform creates an extension for every customized DAC to hold custom fields and customized attributes. At runtime, during the first initialization of a base class, the platform automatically finds the extension for the class and applies the customization by replacing the base class with the merged result of the base class and the extension it found. For more information about DAC extensions, see Changes in the Application Code (C#).

You will also move the generated code to the extension library and adjust it with Acuminator.

Creating the Custom Column and Field

To create the custom column and the custom field, perform the following steps:

Open the Stock Items (IN202500) form, and then open the Screen Editor for it as follows: a. On the form title bar, click Customization > Inspect Element, as shown in the following screenshot. Lesson 2: Creating Custom Fields | 18
Figure: Customization menu

b. Click the name of the General tab to open the Element Properties dialog box for the tab control, as shown in the following screenshot. In the dialog box, notice the following:

Tab (the PXTab control) is the type of UI container whose area you have clicked for inspection.

The InventoryItem data access class provides the data fields for the controls on the inspected tab.

          By clicking the link with the name of the DAC you can view details about this DAC in the
          DAC Schema Browser.

The ItemSettings data view provides data for the container.
The InventoryItemMaint graph provides business logic for this form.
Figure: Element Properties dialog box

c. Click Customize. d. In the Select Customization Project dialog box, which opens, select the PhoneRepairShop customization project, and click OK. Lesson 2: Creating Custom Fields | 19

  The Customization Project Editor opens for the PhoneRepairShop project; the Screen Editor page is
  displayed for the Tab: ItemSettings node, which is selected in the control tree.

2. To add a custom field for the Repair Item check box in the customization project, do the following: a. On the Screen Editor page, click the Add Data Fields tab. b. On the table toolbar, click New Field. c. In the Create New Field dialog box, which opens, specify the following settings for the new field:

Field Name: RepairItem

               As soon as you move the focus out of the Field Name box, the system adds the Usr
               prefix to the field name, which provides a distinction between the original fields and the
               new custom fields that you add to the class. Keep the prefix in the field name.

Display Name: Repair Item
Storage Type: DBTableColumn
Data Type: bool d. Click OK to create the specified extension to both the data access class and the database table. The DAC extension name contains the name of the original DAC and the Ext suﬀix. The IN.InventoryItem customization item is added to the Customized Data Classes page of the Customization Project Editor. e. On the page toolbar, click Save. The platform saves the changes to the customization project that is opened in the Project Editor. However, the changes have not yet been applied to the application because the project has not been republished.

Move the data access class extension to the PhoneRepairShop_Code extension library: a. In the navigation pane, click Data Access. The Customized Data Classes page opens. b. On the Customized Data Classes page, click the line with InventoryItem. c. On the page toolbar, click Convert to Extension. The InventoryItemExtensions Code item appears in the Code Editor page. d. On the toolbar of the Code Editor, click Move to Ext. Library.
```
       For details how to move a DAC to an extension library, see To Move a DAC Item to an Extension
       Library.
```
In Visual Studio, adjust the DAC extension as follows: a. Move the InventoryItemExtensions.cs file to the DAC folder and open the file. Notice that Acuminator displays the PX1016 error and the PX1011 warning for the InventoryItemExt class. The PX1016 error indicates that the class does not implement the IsActive method, which conditionally makes the extension active or inactive. For details, see To Enable a DAC Extension Conditionally (IsActive). In this course, for simplicity, the extension will be always active and you will suppress the error. The PX1011 warning shows that the InventoryItemExt class can be marked with the sealed modifier because multiple levels of inheritance are not supported for PXCacheExtension. You will use the fix provided by Acuminator. b. To suppress the PX1016 error, place the cursor on the InventoryItemExt class name and in the Quick Actions menu select Suppress the PX1016 diagnostic with Acuminator > in a comment, as shown in the screenshot below. Acuminator adds the suppression comment. Lesson 2: Creating Custom Fields | 20
```
       Figure: Suppression of the error in a comment

    c. Place the cursor on the InventoryItemExt class name and in the Quick Actions menu select Mark
       the type as sealed, as the following screenshot shows. Acuminator adds the sealed modifier.


       Figure: Fix of the warning

    d. Remove virtual from the UsrRepairItem property field.
    e. Make sure the UsrRepairItem field has the attributes shown in the following code.

                  [PXDBBool]
                  [PXUIField(DisplayName="Repair Item")]

    f. Add the PXDefault attribute as shown in the following code. The check box that will correspond to the
       field will be cleared by default and the value of the field will not be required.

                  [PXDefault(false, PersistingCheck = PXPersistingCheck.Nothing)]

    g. Change the namespace in which the InventoryItemExt class is declared to PhoneRepairShop.
    h. Build the project.
```
Related Links

To Add a Custom Data Field
To Move a DAC Item to an Extension Library
To Publish the Current Project
Changes in the Application Code (C#)
To Enable a DAC Extension Conditionally (IsActive)

Step 2.2: Creating a Control for the Custom Field

Now you will create a control for the custom field that you added to the PhoneRepairShop customization project in the previous step. For you to create a control for a field on a form in an application instance, both of the following conditions must be met:

The field exists in the instance. Lesson 2: Creating Custom Fields | 21
The field is available through a data view that refers to the data access class containing the field declaration.

Creating the Control

To create the control for the custom field, perform the following actions:

Open the Screen Editor page for the Stock Items (IN202500) form.
In the control tree of the Screen Editor, click the Tab: ItemSettings node.
On the Add Data Fields tab, select the Custom filter tab to view the custom fields that are available through the data view of the container. Notice that the Control column displays the available control type for the custom field.

Create the control for the custom field as follows: a. In the control tree of the Screen Editor, select the Type node (shown in the following screenshot) to position the new control beneath it.

      Figure: The Type node in the control tree

   b. On the Add Data Fields tab, select the unlabeled check box for the row with the custom field.
   c. On the table toolbar, click Create Controls to create the control for the selected field.
      The control appears in the control tree of the Screen Editor beneath the Type node (see the following
      screenshot). Notice that the Used check box has been selected for the field, meaning that a control for
      this field has been added to the layout.

Lesson 2: Creating Custom Fields | 22

  Figure: The added control

5. On the menu of the Customization Project Editor, click Publish > Publish Current Project to apply the customization to the site.

         The Modified Files Detected dialog box opens before publication because you have rebuilt
         the extension library in the PhoneRepairShop_Code Visual Studio project. The Bin
         \PhoneRepairShop_Code.dll file has been modified and you need to update it in the
         project before the publication.

As the system applies the customization to the website, the system generates the proper SQL script by using the definition of the new database column added to the project; it then executes the script on the database. The system also generates ASPX code for the custom control.

         If you unpublish the project, the changes to the database schema and any custom data
         already entered remain in the database; the UI changes are removed.

6. Close the Compilation window. 7. Refresh the Stock Items (IN202500) form in the browser to view the added control on the General tab of the form, which is shown in the following screenshot. Lesson 2: Creating Custom Fields | 23

      Figure: The Repair Item check box

Creating the Custom Column and Field

Do the following to create the custom column and field:

Add the database column as follows: a. In the Customization Project Editor, open the PhoneRepairShop project. b. On the le pane, click Database Scripts. c. On the More menu of the Database Scripts page of the Customization Project Editor, click Add Custom Column to Table.

                 The InventoryItem database script is already present on the page. So, alternatively, you can
                 click on the InventoryItem row, and in the Edit Table Columns dialog box which appears,
                 click Add > Add New Column.

   d. In the dialog box that opens, specify the following values:

Table: InventoryItem
Field Name: UsrRepairItemType
Data Type: string
Length: 2 e. Click OK to close the dialog box. The Acumatica Customization Platform adds the column to the InventoryItem Table item in the customization project. f. Publish the customization project.

In Visual Studio, in the Helper\Constants.cs file, define the RepairItemTypeConstants class (if it has not been defined yet) as shown in the following code.

         //Constants for the repair item types
         public static class RepairItemTypeConstants
         {
             public const string Battery = "BT";
             public const string Screen = "SR";
             public const string ScreenCover = "SC";
             public const string BackCover = "BC";
             public const string Motherboard = "MB";
         }

In the Helper\Messages.cs file, add the constants for the repair item types (if they have not been added yet) to the Messages class, as shown in the following code.

              //Repair item types
              public const string Battery = "Battery";
              public const string Screen = "Screen";
              public const string ScreenCover = "Screen Cover";
              public const string BackCover = "Back Cover";
              public const string Motherboard = "Motherboard";

In the InventoryItemExt class of the InventoryItemExtensions.cs file, add a custom field for the Repair Item Type box, as the following code shows.
```
              #region UsrRepairItemType
              [PXDBString(2, IsFixed = true)]
              [PXStringList(
```

Lesson 2: Creating Custom Fields | 25

                     new string[]
                     {
                         PhoneRepairShop.RepairItemTypeConstants.Battery,
                         PhoneRepairShop.RepairItemTypeConstants.Screen,
                         PhoneRepairShop.RepairItemTypeConstants.ScreenCover,
                         PhoneRepairShop.RepairItemTypeConstants.BackCover,
                         PhoneRepairShop.RepairItemTypeConstants.Motherboard
                     },
                     new string[]
                     {
                         PhoneRepairShop.Messages.Battery,
                         PhoneRepairShop.Messages.Screen,
                         PhoneRepairShop.Messages.ScreenCover,
                         PhoneRepairShop.Messages.BackCover,
                         PhoneRepairShop.Messages.Motherboard
                     })]
                 [PXUIField(DisplayName = "Repair Item Type")]
                 public string? UsrRepairItemType { get; set; }
                 public abstract class usrRepairItemType :
                   PX.Data.BQL.BqlString.Field<usrRepairItemType>
                 { }
                 #endregion

      In the first parameter of the PXStringList constructor, you specify the list of possible values for the field,
      while in the second parameter, you specify the labels that correspond to the values and are displayed on
      the form. Because the possible values for the field have a fixed two-character length, you have specified the
      IsFixed = true and the length equal to 2 for the PXDBString attribute.

5. Build the project.

Changes in the DAC

You will make the Repair Item Type box unavailable by default by setting the Enabled property of the PXUIField attribute to false.

          The user can edit a field value in the UI if the control for the field is available on the form. You can
          make a control available or unavailable by specifying the Enabled parameter of the PXUIField
          attribute in the data access class, or by specifying the Enabled property of the control in the
          ASPX page. Generally, for a data field that should be unconditionally unavailable in the UI, you
          set the Enabled property of the control to False in the ASPX page. For example, you use this
          approach for calculated fields with totals that users will never edit. As the result, the UI controls are
          unconditionally unavailable, regardless of the logic implemented in event handlers.

Lesson 2: Creating Custom Fields | 27

Changes in the Graph

You will add the RowSelected event handler to make the box become available when a user selects the Repair Item check box. You will use the RowSelected event handler because it is intended for the implementation of UI presentation logic. In the RowSelected event handler, you will do the following:

Access the UsrRepairItem extension field of the InventoryItem DAC by invoking the GetExtension method on the cache. (For details on this method, see Access to a Custom Field in the documentation.)
Use the PXUIFieldAttribute.SetEnabled<>() method to change the value of the Enabled property of the PXUIField attribute of the UsrRepairItemType extension field. You will use the Customization Project Editor to create the graph extension, and you will edit the business logic in Visual Studio.

Changes in the ASPX Page

To make the Repair Item Type box available if a user has selected the Repair Item check box and then the Repair Item check box has lost input focus, you will set the CommitChanges property of this control to True. If you do not set the CommitChanges property to True, then when a user selects the Repair Item check box, the Repair Item Type box will become available only when the stock item record is saved or when the value of another field with the CommitChanges property set to True is changed. For details about the CommitChanges property, see Use of the CommitChanges Property of Boxes in the documentation.

Instructions for Adding the UI Presentation Logic

To add this presentation logic, perform the following steps:

In Visual Studio, in the InventoryItemExtensions.cs file, make the Repair Item Type box unavailable by default by setting the Enabled property of the PXUIField attribute of the UsrRepairItemType field to false, as the following code shows.

              [PXUIField(DisplayName = "Repair Item Type", Enabled = false)]
              public string? UsrRepairItemType { get; set; }
              public abstract class usrRepairItemType :
                PX.Data.BQL.BqlString.Field<usrRepairItemType>
              { }

Add the event handler as follows: a. Open the Screen Editor page for the Stock Items (IN202500) form. b. In the control tree, open the Repair Item node, and click the Events tab. c. On the tab, in the event list, click the row with the RowSelected event. Notice that the Handled in Source check box is cleared for the RowSelected event of the InventoryItem DAC, which means that the Acumatica ERP source code does not include an implementation of this event handler. However, to not override possible future implementations of this event handler in the source code of Acumatica ERP, you will extend the base method with your own code. d. On the table toolbar, click Add Handler > Keep Base Method to create a RowSelected event handler for the selected DAC, as shown in the following screenshot. Lesson 2: Creating Custom Fields | 28
Figure: The generation of the event handler
The platform creates a template for the InventoryItem_RowSelected event handler in the extension for the InventoryItemMaint graph. The platform opens the InventoryItemMaint Code item on the Code Editor page of the Customization Project Editor. Note that the created InventoryItemMaint_Extension class that defines the extension for the InventoryItemMaint graph is declared with the public access modifier to be correctly recognized by the Acumatica Customization Platform. e. To move the generated template to the extension library, click Move to Ext. Library on the toolbar of the Code Editor.
```
       Alternatively, you can add the InventoryItemMaint.cs file in Visual Studio and add the
       event handler in the file.
```

In Visual Studio, adjust the graph extension as follows: a. Change the namespace in which the InventoryItemMaint_Extension class is declared to PhoneRepairShop. b. In the InventoryItemMaint.cs file, use Acuminator to suppress the PX1016 error in a comment as you have done for the DAC extension in the first step of this lesson. c. Use the Acuminator fix for the PX1041 message to change the signature of the event to a generic one.

          For details about generic event handlers, see Types of Graph Event Handlers.

d. Remove unnecessary using directives.

          While Acumatica Customization Platform creates an extension for an original class of
          Acumatica ERP, the platform inserts all the using directives from the original class to
          the extension. Some using directives are unused in the customization code and can be
          removed.

e. Redefine the RowSelected event handler as follows. Lesson 2: Creating Custom Fields | 29

              protected void _(Events.RowSelected<InventoryItem> e)
              {
                  if (e.Row == null) return;
                  InventoryItem item = e.Row;
                  InventoryItemExt itemExt = PXCache<InventoryItem>.
                      GetExtension<InventoryItemExt>(item);
                  bool enableFields = itemExt != null &&
                      itemExt.UsrRepairItem == true;
                  //Make the Repair Item Type box available
                  //when the Repair Item check box is selected.
                  PXUIFieldAttribute.SetEnabled<InventoryItemExt.usrRepairItemType>(
                      e.Cache, e.Row, enableFields);
              }

   The code above makes the usrRepairItemType custom field available for editing if the value of
   the UsrRepairItem field of the row in PXCache is true. Otherwise, it makes the custom field
   unavailable.
f. Build the project.

Update the customization project with the changes you have made in this lesson, and publish the project.
Open the Screen Editor page for the Stock Items (IN202500) form.
Set the CommitChanges property to True for the UsrRepairItem data field, as the following screenshot shows.
```
Figure: The CommitChanges property
```
Click Save to save the changes to the customization project.
Publish the customization project.

PXUIFieldAttribute Class
Use of the CommitChanges Property of Boxes
Access to a Custom Field
Configuration of the User Interface in Code Lesson 2: Creating Custom Fields | 30

Step 2.6: Testing the Customized Form

Now you will modify the BAT3310, BAT3310EX, and BCOV3310 stock item records to indicate that they are repair items. To do this, perform the following actions:

On the Stock Items (IN202500) form, select the BAT3310 stock item.
Notice that the Repair Item Type box in the Item Defaults section of the General tab is unavailable because the Repair Item check box is cleared.
In the Item Defaults section of the General tab, specify the following settings:

Repair Item: Selected Notice that once you select the check box, the Repair Item Type box becomes available.
Repair Item Type: Battery

On the form toolbar, click Save to save the record in the database.

Repeat the previous instructions to modify the BAT3310EX and BCOV3310 stock item records as specified in the following table.

    UI Element (Location)                First Modified Record                Second Modified Record

    Inventory ID (Summary area)          BAT3310EX                            BCOV3310

    Repair Item (Item Defaults sec-      Selected                             Selected
    tion of the General tab)

    Repair Item Type (Item De-           Battery                              Back Cover
    faults section of the General
    tab)

   To ensure that the InventoryItem table of the database contains the custom columns and the data
   entered, you can review the table by using SQL Server Management Studio.

Lesson Summary

In this lesson, you have learned how to create a control so that you can display on a form a custom field bound to the database. To implement this customization, you have learned how to add the necessary modifications to a customization project and how to publish the project to apply the changes to the system. As you have completed the lesson, you have added the following elements to the PhoneRepairShop customization project:

Two column definitions in the InventoryItem table of the database.
Two custom field declarations in the extension of the IN.InventoryItem data access class (in the PhoneRepairShop_Code extension library).
Two controls to display the custom fields on the Stock Items (IN202500) form.
One custom event handler, which you have added to the InventoryItemMaint graph. You have used the RowSelected event handler to configure the UI presentation logic. The following diagram shows the results of the lesson. Lesson 2: Creating Custom Fields | 31 Additional Information: Custom Elements
In this lesson, you have learned how to create a custom check box and drop-down list on an Acumatica ERP form. The creation of other custom elements, such as tabs, is outside of the scope of this course. You can find information about the creation of custom elements, along with examples, in the lessons of the T210 Customized Forms and Master-Detail Relationship training course. Lesson 3: Implementing the Update and Validation of Field Values | 33