Defining Static Field Control and Value Helps

In RAP, update is one of the standard operations. Standard operations are also known as CRUD operations, which is an acronym for create, read, update, delete.

While the read operation is always implicitly enabled for each entity listed in a CDS behavior, the modifying operations have to be listed explicitly to be available.

To enable standard operation update for an entity, add the update; statement to the entity behavior body (curly brackets after statement define behavior for …). To disable the operation, remove the statement or turn it into a comment.

In a managed scenario, the standard operations do not require an ABAP behavior pool, because they are completely handled by the RAP BO framework. In an unmanaged scenario, however, the standard operations must be implemented in the ABAP behavior pool.

Some interesting additions to statement update are as follows:

Internal

Prefix which disables the operation for external consumers of the business object.

Features: instance or features: global

Enable dynamic feature control. The decision, where and when the operation is enabled, is made dynamically in a behavior implementation.

Precheck

A method is called before the update request to prevent unwanted changes from reaching the application buffer.

To make a standard operation update available in the OData Service, it has to be exposed in the behavior definition on projection level (behavior projection).

To include standard operation update in the OData service, add statement use update; to the entity behavior body (curly brackets after statement define behavior for …). To disable the operation, remove the statement or turn it into a comment.

When the standard operation Update is available in the OData service, the service preview displays an Edit button on the Object Page for the related RAP BO entity. By choosing this button, the user enters an edit mode for the data displayed on the page.

The field statement is used in behavior definitions, to specify the characteristics of fields. The statement is always located between the curly brackets after the statement define behavior (the entity behavior body). You can use commas to classify multiple fields in the same way.

For the readonly characteristic of fields, the following variants exist:

field ( readonly )

• Values of the specified fields must not be be created or updated by the RAP BO consumer.
• This is independent from the standard operation the consumers wants to perform (update, create).

field ( readonly : update)

• Defines a field as read-only during update operations.
• An external consumer can set the fields in question during create, but cannot change them later during update.
• Technically, this is a dynamic field attribute, but not implementation in the behavior pool is required.

To include the field characteristics into the OData service, it is not necessary to add the field statements in the behavior projection. The related information is directly propagated into the OData service. The SAP Fiori elements UI uses this metadata for UI hints, that is, depending on the operation, the fields are displayed as editable or read-only.

For the mandatory characteristic of fields, the following variants exist:

Field ( mandatory )

• The RAP BO always requires a value for the specified field(s) before persisting them on the database.
• This is independent from the standard operation the consumers wants to perform (update, create).

There is no runtime check for mandatory fields and no runtime error occurs if a mandatory field is not filled. If a runtime check is required, the application developer must implement it using a validation.

Field ( mandatory : create )

• Defines a field as mandatory during create operations.
• An external consumer must set the fields in question only during create.
• If a consumer tries to create a new instance without entering a value into a field defines as mandatory:create, a runtime error occurs.
• Technically, this is a dynamic field attribute, but not implementation in the behavior pool is required.

The SAP Fiori elements UI uses the metadata to display fields as mandatory.

Field(suppress) can be used to remove a field from the derived types, field mapping, and all RAP APIs. It is possible for all fields except for key fields, foreign key fields, and fields used by the current behavior definition, such as ETag fields.

If a RAP BO consumer tries to modify a suppressed field, an error message occurs that tells the consumer that no field of this name exists.

Instead of excluding a field from the RAP BO behavior, you can exclude it only from consumption, for example from the OData service, or from the user interface. It is done using annotations in the CDS view definition or the CDS metadata extension.

Fields can be hidden by one of the following annotations:

@Consumption.hidden: true

The field is not exposed for any consumption. This means that it is part of the OData Service and, therefore, not available on the UI.

@UI.hidden: true

The field is not available on the UI. This means that it is not displayed and the user cannot make it visible using personalization. If, however, there is no additional annotation @Consumption.hidden: true, the field can still be part of the OData service.

If you want to hide a field that is needed in the OData service, you cannot use @Consumption.hidden: true. You have to use @UI.hidden: true instead. A good example is the exclusion of technical key fields and ETag fields from the UI.

The implementation of a value help in CDS enables the end user to choose values from a predefined list for input fields on a user interface.

In SAP Fiori elements apps, value helps are invoked by choosing the value help button next to the input field or by pressing F4.

By default, the value help dialog consists of a filter dialog, which the user can hide and unhide, and a list with suggested values.

It is possible to provide more than one value help on one input field. The end user can select which value help to use from a dropdown list.

To provide a value help for a given field, you first need a CDS view that contains the values for the value help. This view is referred to as the value help provider. Then, you annotate your field with @Consumption.valueHelpDefinition and provide the name of the value help provider and an element for the mapping in the annotation.

You can use any CDS entity as a value help provider that contains the desired values of the element for the input field. However, developers often define dedicated value help views, because the layout and functionality of the value help dialog is derived from the metadata of the value help provider view.

To provide a simple value help for a field, edit the data definition of the source view and annotate the field with the following annotation:

12345
@Consumption.valueHelpDefinition: [ { 
                                 entity.name:    'entityRef', 
                                 entity.element: 'elementRef' 
                                                } ]

Here, entityRef is the name of the CDS entity that is used as value help provider and elementRef the element of the value help provider that is used as output parameter of the value help.

When you expose the source view in an OData service, the value help provider view is automatically exposed with it. You do not have to list value help provider views in the service definition.

On the SAP Fiori Elements UI, choosing F4 in the selection field opens a search mask and the end user can filter by any field in the value help provider view. Selecting an entry transfers the value of the element that is referenced in the annotation to the annotated element in the source view.

You use additional binding to define more than one binding conditions between elements of the source view and elements of the value help provider view.

The additional bindings are defined with the subannotation additionalBindings of annotation @Consumption.valueHelpDefinition. The subannotation is followed by a pair of square brackets ([..]) with a comma-separated list of element bindings.

Each element binding connects exactly one element of the source view (localElement) and one element of the value help provider view (element).

In addition, it specifies a usage with one of the following values:

#FILTER

 The value of the referenced element in localElement is used as input for the value help. The value help proposes only entries that match this filter value.

#RESULT

The value of the referenced element in element is used as extra output. When an entry is selected in the value help, this value is transferred to the input field that is based on the referenced element in localElement.

#FILTER_AND_RESULT

The binding is used for input and output.