Side Effect Annotation Format

You can define side effects either in the back end or in the local annotation files.

Side Effect Annotation Properties

• Target Entities

  For 1:n, the request isn't sent by the binding of the table. This means that paging isn't considered. Therefore, 1:n must be used carefully.

• Side effect without a specific source

  You can define a side effect without any source properties or source entities. This is called a global side effect. For more information, see Using Global Side Effects.

Side Effects for Extension Fields in Forms

To enable side effects for extension fields in forms, you must configure the registerCustomFieldForSideEffect extension API in the onAfterRendering hook. The extension API requires the following parameters:

• Controls: The extension field controls.

• FieldName: The name of the custom field.

• EntitySet: The associated entity set.

The extension API returns a callback function, which must be invoked within the extension field event handler. The callback function requires the FieldName as input.

Additionally, the side effect annotation must be configured to ensure correct behavior.

The following sample code shows how a custom field is configured as the source for the side effect:

sap.ui.define("SOwoExt.ext.controller.ObjectPageExtension", ["sap/m/MessageBox"], function (MessageBox) {
    "use strict";
    var CustomFieldGroupChangeRegister;

    return {
        onCheckBoxEvent: function (oEvent) {
            var oView = this.getView();
            var model = oView.getModel();
            var context = oView.getBindingContext();
            var sFields = "SrcgProjNotesAreForbidden";
            var data = oEvent.getParameter("selected");

            model.setProperty(context.getPath() + "/" + sFields, data);
            CustomFieldGroupChangeRegister("SrcgProjNotesAreForbidden");
        },

        onAfterRendering: function (event) {
            var oView = this.getView();
            var sEntitySet = "C_STTA_SalesOrder_WD_20";
            var sProperty = "SrcgProjNotesAreForbidden";
            var oControl = sap.ui.getCore().getElementById(
                "SOwoExt::sap.suite.ui.generic.template.ObjectPage.view.Details::C_STTA_SalesOrder_WD_20--srcgProjNotesAreForbiddenCheckBox"
            );

            CustomFieldGroupChangeRegister = this.extensionAPI.registerCustomFieldForSideEffect(oControl, sProperty, sEntitySet);
        }
    };
});

Side Effects for Extension Columns in Tables

To enable side effects for extension columns in tables, you must configure the registerCustomColumnForSideEffect extension API within the onAfterRendering hook of the table. The extension API requires the following parameters:

• oTable: The extension field controls.

• FieldName: The property name associated with the custom column.

• EntitySet: The entity set associated with the custom column.

The extension API returns a callback function, which must be invoked within the extension column event handler. The callback function requires the Field Name as input.

Additionally, the side effect annotation must be configured to ensure correct behavior.

The following sample code shows how a custom table column with a check box is configured as the source for the side effect:

sap.ui.define("SOwoExt.ext.controller.ObjectPageExtension", ["sap/m/MessageBox"], function (MessageBox) {
    "use strict";
    
    var CustomFieldGroupChangeRegister;

    return {
        onSubSectionEnteredExtension: function (subSection) {
            if (subSection.getId().indexOf("C_STTA_SalesOrder_WD_20--to_Item") !== -1) {
                var sourcingProjectItemTreeTable = this.oView.byId(
                    "SOwoExt::sap.suite.ui.generic.template.ObjectPage.view.Details::C_STTA_SalesOrder_WD_20--to_Item::com.sap.vocabularies.UI.v1.LineItem::responsiveTable"
                );

                sourcingProjectItemTreeTable.addEventDelegate(
                    {
                        onAfterRendering: function (oEvent) {
                            var oControl = this.oView.byId(
                                "SOwoExt::sap.suite.ui.generic.template.ObjectPage.view.Details::C_STTA_SalesOrder_WD_20--to_Item::com.sap.vocabularies.UI.v1.LineItem::responsiveTable"
                            );

                            CustomFieldGroupChangeRegister = this.extensionAPI.registerCustomColumnForSideEffect(
                                oControl,
                                "Raiseamount_ac",
                                "C_STTA_SalesOrderItem_WD_20"
                            );
                        },
                    },
                    this
                );
            }
        },

        onCheckBoxPressed: function (event) {
            var sProperty = "Raiseamount_ac";
            CustomFieldGroupChangeRegister(sProperty);
        },
    };
});

Note

• Side effects for non-draft apps are supported. The side effects with source properties are triggered once the user saves the entity and the Save action is successful. They are also supported when structural changes are made to the items table in the object page that is configured as a source.

• If a text arrangement annotation is used, especially in combination with a value list annotation, you also need to provide a side-effect annotation to indicate that the text must be updated when the user sets a different key.

• Side effects for non-draft apps are also supported for action buttons. See Example: Side effect after executing an action in Side Effect Annotations: Examples.

Defining Side Effects on Unbound Actions

Target Entities

The list is refreshed if a 1:n association is provided as a target entity.

You can also specify absolute paths, that is, paths starting with the entity container. They can be defined as TargetEntities to refresh complete entity sets in the list report.

Value List Refresh

Value lists are cached during runtime for better performance. You can define an absolute side effect with the value list collection as the target in the following cases:

• If you are using a value list referring to transactional data.

• If you expect the value list to change due to actions or changes made by users.

The following sample code shows you an example:

<Annotation Term="com.sap.vocabularies.Common.v1.SideEffects" Qualifier="ChangeOfProperty">
     <Record>
          <PropertyValue Property="SourceProperties">
               <Collection>
                    <PropertyPath>PropertyName</PropertyPath>
               </Collection>
          </PropertyValue>
          <PropertyValue Property="TargetEntities">
               <Collection>
                    <NavigationPropertyPath>/Namespace.EntityContainer/ValueListCollection</NavigationPropertyPath>
               </Collection>
          </PropertyValue>
     </Record>
</Annotation>

Side Effects for Extension Fields in Forms

SAP Fiori elements for OData V4 supports executing side effects when using custom extension fields in a form if the following conditions are met:

• The source properties of a side effect contain the property used in an extension field.

• The property used in the extension field has been specified in the manifest.json file with the property key.

In the following example, the side effects with NameProperty as the source property are executed:

"targets": {
    "MyObjectPage": {
        "type": "Component",
        "id": "Default",
        "name": "sap.fe.templates.ObjectPage",
        "viewLevel": 1,
        "options": {
            "settings": {
                "contextPath": "/RootEntity",
                "editableHeaderContent": true,
                "controlConfiguration": {
                    "@com.sap.vocabularies.UI.v1.Identification": {
                        "fields": {
                            "customFormElementIdentification1": {
                                "template": "sap.fe.core.fpmExplorer.customFormElementContent.CustomFormElement1",
                                "label": "Custom FormElement 1",
                                "property": "NameProperty"
                            }
                        }
                    }
                }
            }
        }
    }
}

Side effects are executed when the focus moves away from the extension field.

Check out our live example in the flexible programming model explorer at Extension Points - Custom Form Element.