Entry Update

The EntryUpdateCL class is responsible for managing the UPDATE (PUT/PATCH/MERGE) operation through the OData V2 model. This class eliminates the need for developers to concern themselves with fragments, user input validations, and value help creation when working on custom SAPUI5 applications or Fiori Elements extensions. The following section outlines the key features of the Entry Update class.

Features

• sap.m.Dialog generation with a SmartForm, SimpleForm, or custom content
• sap.uxap.ObjectPageLayout generation with a SmartForm, SimpleForm, or custom content
• User input validation via the ValidationLogicCL class
• Value Help Dialog generation via the ValueHelpCL class
• Property sorting, readonly properties
• Label generation for the SmartForm, SimpleForm elements
• submitChanges(), and resetChanges() handling based on the user interaction
• Call a fragment and bind the context in case you do not want to use the auto-generated dialog

Attention

Please be advised that the majority of features available in the Entry Create class are also accessible in the Entry Update class. However, please note that the original documentation was created on the Entry Create page. To view a list of available features, please refer to the Available Features section.

Use Case

Let's assume you have an EntitySet named Products, which is bound to a table. You would like to enable the end user to select a line from the table and edit the selected entity on a pop-up screen using the OData V2 service in your custom SAPUI5 application. To do so, you must follow these steps.

1) It is necessary to create a .fragment.xml file that contains a dialog with form content (Simple, Smart, etc.) and to call it from the controller or to generate the dialog directly on the controller.

2) If you do not use the sap.ui.comp.smartfield.SmartField component with the OData Annotations, you will need to write a significant amount of Value Help code.

3) It is essential to validate user input, such as checking mandatory fields and ensuring that the values entered align with your business logic.

4) It is necessary to handle the selection of the table and the binding of the selected entity to the dialog or form.

The EntryUpdateCL class is responsible for executing all of the steps mentioned above.

Constructor

In order to utilise the functionality of EntryUpdateCL, it is necessary to initialise the object.

Parameter	Type	Mandatory	Default Value	Description
controller	sap.ui.core.mvc.Controller	Yes		The controller object (usually this object)
settings	object	Yes
entityPath	string	Yes		The name of the EntitySet. It can start with a "/" (slash)
initializer	string | sap.ui.model.Context | EntityKeysT	Yes		This parameter identifies the table ID, context binding, or key values of the entity that will be updated.
modelName?	string	No	undefined	The name of the OData V2 model which can be found on the manifest.json file. Leave this parameter undefined if the name of the OData model = "" (empty string)

There are three distinct methods for constructing an object from the Entry Update class.

Constructor with a Table ID

The most straightforward method for utilizing the capabilities of the Entry Update class is to construct an object with the ID of a table that you have on your XML view. This method offers several advantages.

1) The table row selected by the end user is automatically detected by the Entry Update class, and the context binding of the selected row will be bound to the auto-generated dialog.

2) If no table row is selected by the end user, a default message is displayed in the sap.m.MessageBox.error to the end user.

Attention

Please note that this method supports only the table types and selection modes listed below. In the event that the selection mode of the table whose ID is being used for object construction is not supported, an error will be thrown by the library.

Tip

The default message displayed when the end user has not selected a row from the table yet can be modified using the setSelectRowMessage() method.

Supported Table Types

Table Type	Selection Mode
sap.m.Table	SingleSelect | SingleSelectLeft | SingleSelectMaster
sap.ui.table.Table	Single
sap.ui.comp.smarttable.SmartTable	Single
sap.ui.table.AnalyticalTable	Single
sap.ui.table.TreeTable	Single

Example

Let us consider an EntitySet named Products, which is bound to an sap.m.Table on the XML view. Our objective is to add an sap.m.Button to the header toolbar of the table. When the user selects a row from the table and presses the Update Product button, a dialog will open so the end user can modify the entity.

Tip for TypeScript

The EntryUpdateCL<EntityT, EntityKeysT> class is a generic class and can be initialized with 2 types.

• The EntityT type contains all properties of the EntitySet that is specified on the class constructor.
• The EntityKeysT type contains the key properties of the EntitySet that is specified on the class constructor.

The EntityT type is utilized as the return type of the getResponse(): EntityT method of the ResponseCL class, whose object is passed as a parameter into the function attached by the attachSubmitCompleted(submitCompleted: (response: ResponseCL<EntityT>) => void, listener?: object) method.

The EntityKeysT type is utilized as one of the types of the initializer parameter in the class constructor.

TypeScriptJavaScript

import Controller from "sap/ui/core/mvc/Controller";
import EntryUpdateCL from "ui5/antares/entry/v2/EntryUpdateCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onUpdateCategory() {
    // Initialize without a type and with the table id
    const entry = new EntryUpdateCL(this, {
      entityPath: "Categories",
      initializer: "tblCategories" // table id       
    }); 
  }

  public async onUpdateProduct() {
    // Initialize with a type and the table id
    const entry = new EntryUpdateCL<IProducts, IProductKeys>(this, {
      entityPath: "Products",
      initializer: "tblProducts" // table id       
    }); 
  }

  public async onUpdateCustomer() {
    // Initialize with a model name and the table id
    const entry = new EntryUpdateCL(this, {
      entityPath: "Customers",
      initializer: "tblCustomers" // table id      
    }, "myODataModelName"); 
  }
}

interface IProducts {
  ID: string;
  name: string;
  description: string;
  brand: string;
  price: number;
  currency: string;
  quantityInStock: number;
  categoryID: string;
  supplierID: string;
}

interface IProductKeys {
  ID: string;
}

sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/entry/v2/EntryUpdateCL" // Import the class
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, EntryUpdateCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onUpdateProduct: async function () {
          // Initialize with the table id
          const entry = new EntryUpdateCL(this, {
            entityPath: "Products",
            initializer: "tblProducts" // table id                
          }); 
        },

        onUpdateCategory: async function () {
          // Initialize with a model name
          const entry = new EntryUpdateCL(this, {
            entityPath: "Categories",
            initializer: "tblCategories" // table id                 
          }, "myODataModelName");
        }
      });

    });

Constructor with a Context Binding

An alternative approach to constructing an object from the Entry Update class is to utilise the context of the entity that will be updated by the end user.

Example

Let us consider an EntitySet named Products, which is bound to an sap.m.Table on the XML view. Our objective is to add an sap.m.Button to the header toolbar of the table. When the user selects a row from the table and presses the Update Product button, we will retrieve the context of the selected row and use it to construct an object from the Entry Update class.

Tip for TypeScript

The EntryUpdateCL<EntityT, EntityKeysT> class is a generic class and can be initialized with 2 types.

• The EntityT type contains all properties of the EntitySet that is specified on the class constructor.
• The EntityKeysT type contains the key properties of the EntitySet that is specified on the class constructor.

The EntityT type is utilized as the return type of the getResponse(): EntityT method of the ResponseCL class, whose object is passed as a parameter into the function attached by the attachSubmitCompleted(submitCompleted: (response: ResponseCL<EntityT>) => void, listener?: object) method.

The EntityKeysT type is utilized as one of the types of the initializer parameter in the class constructor.

TypeScriptJavaScript

import Controller from "sap/ui/core/mvc/Controller";
import EntryUpdateCL from "ui5/antares/entry/v2/EntryUpdateCL"; // Import the class
import MessageBox from "sap/m/MessageBox";
import Table from "sap/m/Table";

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onUpdateCategory() {
    // Get the selected item and warn the end user if no row was selected
    const selectedItem = (this.getView().byId("tblCategories") as Table).getSelectedItem();

    if (!selectedItem) {
      MessageBox.error("Please select a row from the table");
      return;
    }

    // Get the selected context
    const selectedContext = selectedItem.getBindingContext();

    // Initialize without a type and use the binding context
    const entry = new EntryUpdateCL(this, {
      entityPath: "Categories",
      initializer: selectedContext // binding context
    }); 
  }

  public async onUpdateProduct() {
    // Get the selected item and warn the end user if no row was selected
    const selectedItem = (this.getView().byId("tblProducts") as Table).getSelectedItem();

    if (!selectedItem) {
      MessageBox.error("Please select a row from the table");
      return;
    }

    // Get the selected context
    const selectedContext = selectedItem.getBindingContext();

    // Initialize with a type and use the binding context
    const entry = new EntryUpdateCL<IProducts, IProductKeys>(this, {
      entityPath: "Products",
      initializer: selectedContext // binding context
    }); 
  }

  public async onUpdateCustomer() {
    // Get the selected item and warn the end user if no row was selected
    const selectedItem = (this.getView().byId("tblCustomers") as Table).getSelectedItem();

    if (!selectedItem) {
      MessageBox.error("Please select a row from the table");
      return;
    }

    // Get the selected context
    const selectedContext = selectedItem.getBindingContext();

    // Initialize with a model name and use the binding context
    const entry = new EntryUpdateCL(this, {
      entityPath: "Customers",
      initializer: selectedContext // binding context   
    }, "myODataModelName"); 
  }
}

interface IProducts {
  ID: string;
  name: string;
  description: string;
  brand: string;
  price: number;
  currency: string;
  quantityInStock: number;
  categoryID: string;
  supplierID: string;
}

interface IProductKeys {
  ID: string;
}

sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/entry/v2/EntryUpdateCL", // Import the class
    "sap/m/MessageBox"
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, EntryUpdateCL, MessageBox) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onUpdateProduct: async function () {
          // Get the selected item and warn the end user if no row was selected
          const selectedItem = this.getView().byId("tblProducts").getSelectedItem();

          if (!selectedItem) {
            MessageBox.error("Please select a row from the table");
            return;
          }

          // Get the selected context
          const selectedContext = selectedItem.getBindingContext();

          // Initialize with the binding context
          const entry = new EntryUpdateCL(this, {
            entityPath: "Products",
            initializer: selectedContext // binding context     
          }); 
        },

        onUpdateCategory: async function () {
          // Get the selected item and warn the end user if no row was selected
          const selectedItem = this.getView().byId("tblCategories").getSelectedItem();

          if (!selectedItem) {
            MessageBox.error("Please select a row from the table");
            return;
          }

          // Get the selected context
          const selectedContext = selectedItem.getBindingContext();

          // Initialize with the binding context
          const entry = new EntryUpdateCL(this, {
            entityPath: "Categories",
            initializer: selectedContext // binding context               
          }, "myODataModelName");
        }
      });

    });

Constructor with Entity Keys

The final method for constructing an object from the Entry Update class is to utilize the key values of the entity that will be updated by the end user.

Example

For the purposes of this example, let us consider an EntitySet named Products with a single key property named ID, whose type is Edm.Guid. We would like to allow the end user to edit a specific entity with the key value: ID = "b2f0013e-418f-42aa-9a24-3770fe17ce18".

Tip

Please note that if the EntitySet is bound to a table, you can retrieve the values of the key properties of the selected row using the getBindingContext().getObject() method.

Info

The EntryUpdateCL class creates a binding context with the values of the specified key properties using the initializer parameter in the class constructor and subsequently binds the created context to the dialog.

Tip for TypeScript

The EntryUpdateCL<EntityT, EntityKeysT> class is a generic class and can be initialized with 2 types.

• The EntityT type contains all properties of the EntitySet that is specified on the class constructor.
• The EntityKeysT type contains the key properties of the EntitySet that is specified on the class constructor.

The EntityT type is utilized as the return type of the getResponse(): EntityT method of the ResponseCL class, whose object is passed as a parameter into the function attached by the attachSubmitCompleted(submitCompleted: (response: ResponseCL<EntityT>) => void, listener?: object) method.

The EntityKeysT type is utilized as one of the types of the initializer parameter in the class constructor.

TypeScriptJavaScript

import Controller from "sap/ui/core/mvc/Controller";
import EntryUpdateCL from "ui5/antares/entry/v2/EntryUpdateCL"; // Import the class

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onUpdateCategory() {
    // Prepare the key values of a specific entity
    const keyValues = {
      ID: "b2f0013e-418f-42aa-9a24-3770fe17ce18"
    };

    // Initialize without a type and use the key values as the initializer
    const entry = new EntryUpdateCL(this, {
      entityPath: "Categories",
      initializer: keyValues // key values of the entity
    });
  }

  public async onUpdateProduct() {
    // Prepare the key values of a specific entity
    const keyValues = {
      ID: "b2f0013e-418f-42aa-9a24-3770fe17ce18"
    };

    // Initialize with a type and use the key values as the initializer
    const entry = new EntryUpdateCL<IProducts, IProductKeys>(this, {
      entityPath: "Products",
      initializer: keyValues // key values of the entity
    });
  }

  public async onUpdateCustomer() {
    // Prepare the key values of a specific entity
    const keyValues = {
      ID: "b2f0013e-418f-42aa-9a24-3770fe17ce18"
    };

    // Initialize with a model name and use the key values as the initializer
    const entry = new EntryUpdateCL(this, {
      entityPath: "Customers",
      initializer: keyValues // key values of the entity
    }, "myODataModelName"); 
  }
}

interface IProducts {
  ID: string;
  name: string;
  description: string;
  brand: string;
  price: number;
  currency: string;
  quantityInStock: number;
  categoryID: string;
  supplierID: string;
}

interface IProductKeys {
  ID: string;
}

sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/entry/v2/EntryUpdateCL"
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, EntryUpdateCL) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onUpdateProduct: async function () {
          // Prepare the key values of a specific entity
          const keyValues = {
            ID: "b2f0013e-418f-42aa-9a24-3770fe17ce18"
          };

          // Initialize with the entity set name and use the key values as the initializer
          const entry = new EntryUpdateCL(this, {
            entityPath: "Products",
            initializer: keyValues // key values of the entity
          });  
        },

        onUpdateCategory: async function () {
          // Prepare the key values of a specific entity
          const keyValues = {
            ID: "b2f0013e-418f-42aa-9a24-3770fe17ce18"
          };

          // Initialize with the entity set name and use the key values as the initializer
          const entry = new EntryUpdateCL(this, {
            entityPath: "Categories",
            initializer: keyValues // key values of the entity        
          }, "myODataModelName");          
        }
      });

    });

Select Row Message

If the object from the Entry Update class is constructed using the Constructor with a Table ID approach, a default error message is displayed in an sap.m.MessageBox.error to the end user when the user has not yet selected a row from the table.

To change the default message, the setSelectRowMessage() method can be utilized.

Setter (setSelectRowMessage)Getter (getSelectRowMessage)

Parameter	Type	Mandatory	Description
message	string	Yes	The message that is displayed when the end user has not selected a row from the table

Returns	Description
string	Returns the value that was set using setSelectRowMessage() method. Default value is Please select a row from the table.

Update Entry

The updateEntry() method establishes a connection between the context, determined by the initializer parameter in the class constructor, and the dialog that is either automatically generated or loaded from the fragment placed in the application files. Once the context is linked, the generated or loaded dialog is opened.

The updateEntry() method utilizes the ODataMetaModel to determine the EntityType of the EntitySet designated through the constructor. It then generates the form with the properties in the same order as the OData metadata, in accordance with the EntityType.

Note

Please note that all key properties are marked as mandatory/required, and the labels are generated assuming that the naming convention of the EntityType is camelCase. For further details, please see the Label Generation section.

Attention

It is not possible to modify any of the key properties of an EntitySet on the auto-generated dialog. This behaviour cannot be altered.

Warning

Please be advised that the updateEntry() method must be called after any configurations have been made through the public methods of the Entry Update class. Any configurations (form title, mandatory properties, etc.) made after the updateEntry() method will not be reflected. As a best practice, the updateEntry() method should be called at the end of your code block.

Note

The key properties with Edm.Guid type are not visible by default on the generated form. However, this behavior can be modified using the setDisplayGuidProperties() method.

Attention

Please be advised that the random UUID generation for properties with the Edm.Guid type is not available in the Entry Update class.

Method Parameters

Returns	Description
Promise<void>	Once the promise has been fulfilled, the bound entry can be retrieved using the getEntryContext() method with the object instantiated from the EntryUpdateCL class.

Info

The updateEntry() method uses the default configurations when creating the dialog. However, these configurations can be modified using the public setter methods.

Default Values

Term	Default Value	Description	Setter	Getter
Naming Strategy	NamingStrategies.CAMEL_CASE	The default naming strategy is CAMEL_CASE	setNamingStrategy()	getNamingStrategy()
Resource Bundle Prefix	antares	The default resource bundle prefix is antares	setResourceBundlePrefix()	getResourceBundlePrefix()
Use Metadata Labels	false	The labels are not derived from the metadata, but rather generated.	setUseMetadataLabels()	getUseMetadataLabels()
Form Type	FormTypes.SMART	The SmartForm with SmartFields is generated as the default option.	setFormType()	getFormType()
Form Title	Update + ${entityPath}	The entityPath parameter of the constructor is used	setFormTitle()	getFormTitle()
Begin Button Text	Update	The default begin button text is Update	setBeginButtonText()	getBeginButtonText()
Begin Button Type	ButtonType.Success	The default button type is Success	setBeginButtonType()	getBeginButtonType()
End Button Text	Close	The default end button text is Close	setEndButtonText()	getEndButtonText()
End Button Type	ButtonType.Negative	The default button type is Negative	setEndButtonType()	getEndButtonType()
Mandatory Error Message	Please fill in all required fields.	The displayed message when the mandatory check is unsuccessful	setMandatoryErrorMessage()	getMandatoryErrorMessage()

Example

TypeScriptJavaScript

import Controller from "sap/ui/core/mvc/Controller";
import EntryUpdateCL from "ui5/antares/entry/v2/EntryUpdateCL"; // Import the class
import Table from "sap/m/Table";
import MessageBox from "sap/m/MessageBox";

/**
 * @namespace your.apps.namespace
 */
export default class YourController extends Controller {
  public onInit() {

  }

  public async onUpdateProduct() {
    // Initialize without a type and with a table id
    const entry = new EntryUpdateCL(this, {
      entityPath: "Products",
      initializer: "tblProducts"
    });

    // Call 
    entry.updateEntry(); 
  }

  public async onUpdateCategory() {
    const selectedItem = (this.getView().byId("tblCategories") as Table).getSelectedItem();

    if (!selectedItem) {
      MessageBox.error("Please select a row from the table");
      return;
    }

    const selectedContext = selectedItem.getBindingContext();

    // Initialize with a type and a binding context
    const entry = new EntryUpdateCL<ICategory>(this, {
      entityPath: "Categories",
      initializer: selectedContext
    }); 

    // Call
    entry.updateEntry();
  }

  public async onUpdateCustomer () {
    const selectedItem = (this.getView().byId("tblCustomers") as Table).getSelectedItem();

    if (!selectedItem) {
      MessageBox.error("Please select a row from the table");
      return;
    };

    const customerKeys = {
      ID: selectedItem.getBindingContext().getObject().ID
    };

    // Initialize without a type and with the key values
    const entry = new EntryUpdateCL(this, {
      entityPath: "Customers",
      initializer: customerKeys
    });

    // Call
    entry.updateEntry();
  }
}

interface ICategory {
  ID: string;
  name?: string;
}

sap.ui.define([
    "sap/ui/core/mvc/Controller",
    "ui5/antares/entry/v2/EntryUpdateCL", // Import the class
    "sap/m/MessageBox"
], 
    /**
     * @param {typeof sap.ui.core.mvc.Controller} Controller
     */
    function (Controller, EntryUpdateCL, MessageBox) {
      "use strict";

      return Controller.extend("your.apps.namespace.YourController", {
        onInit: function () {

        },

        onUpdateProduct: async function () {
          // Initialize with a table id
          const entry = new EntryUpdateCL(this, {
            entityPath: "Products",
            initializer: "tblProducts"
          }); 

          // Call
          entry.updateEntry();
        },

        onUpdateCategory: async function () {
          const selectedItem = this.getView().byId("tblCategories").getSelectedItem();

          if (!selectedItem) {
            MessageBox.error("Please select a row from the table");
            return;
          }

          const selectedContext = selectedItem.getBindingContext();

          // Initialize with a binding context
          const entry = new EntryUpdateCL(this, {
            entityPath: "Categories",
            initializer: selectedContext
          }); 

          // Call
          entry.updateEntry();
        },

        onUpdateCustomer: async function () {
          const selectedItem = this.getView().byId("tblCustomers").getSelectedItem();

          if (!selectedItem) {
            MessageBox.error("Please select a row from the table");
            return;
          }

          const customerKeys = {
            ID: selectedItem.getBindingContext().getObject().ID
          };

          // Initialize with the key values
          const entry = new EntryUpdateCL(this, {
            entityPath: "Customers",
            initializer: customerKeys
          }); 

          // Call
          entry.updateEntry();          
        }
      });

    });

The generated form with default values will be similar in appearance to the following example. However, it should be noted that the exact appearance may vary depending on the configurations and the EntityType properties of the EntitySet.

Available Features

The EntryUpdateCL class is derived from the same abstract class as the EntryCreateCL class and contains the same methods. However, some of these functions are not applicable to the EntryUpdateCL class.

Warning

Please note that the default values for the available functions may differ.

The features listed below are identical to those available in EntryCreateCL. Methods can be accessed through the object constructed from the EntryUpdateCL class.

Tip

To access the documentation for a particular feature, please click on the name of the feature.

Feature	Availability	Default Value	Remarks
Manual Submit	✔
Disable Auto Dialog Close	✔	false
Label Generation	✔
Resource Bundle Prefix	✔	antares
Naming Strategy	✔	CAMEL_CASE
Form Type	✔	SMART
Form Title	✔	Update ${entityPath}
Form Grouping	✔	[]
Custom Data	✔	[]
Text In Edit Mode Source	✔	[]
Begin Button Text	✔	Update
Begin Button Type	✔	ButtonType.Success
End Button Text	✔	Close
End Button Type	✔	ButtonType.Negative
Properties with Edm.Guid Type	✔		The random UUID generation is not available. You can only modify the visibilities of the properties with Edm.Guid type
Form Property Order	✔	[]
Excluded Properties	✔	[]
Mandatory Properties	✔	[]
Readonly Properties	✔	[keys]	By default, the key properties are readonly and cannot be changed, but additional readonly properties can be added
Attach Submit Completed	✔
Attach Submit Failed	✔
Response Class	✔
Value Help	✔
Validation Logic	✔
Object Page	✔
Custom Control	✔
Custom Content	✔
Custom Fragment	✔