Adding Custom Actions Using Extension Points

You can use extension points to add custom actions to the list report and the object page.

Context

Caution

Use app extensions with caution and only if you cannot produce the required behavior by other means, such as manifest settings or annotations. To correctly integrate your app extension coding with SAP Fiori elements, use only the extensionAPI of SAP Fiori elements. For more information, see Using the extensionAPI.

After you've created an app extension, its display (for example, control placing, CSS) and system behavior (for example, model and binding usage, busy handling) of the app extension lies within the application's responsibility. SAP Fiori elements provides support only for the official extensionAPI functions. Don't access or manipulate SAP Fiori elements' internal coding.

You can define custom actions for:

List reports (global action)
For global actions, you do not have to select a line in the list report table. This type of action refers to the whole list report, for example, Display Log. Global actions are placed in the list report filter bar next to the Share button.
Table toolbar of the list report
Header of the object page
Table toolbar for a specific table on the object page
Form in a section on the object page
Footer bar

These custom actions are displayed as buttons on the UI. When the user selects the action, the system calls a handler function that can be implemented within a controller extension.

Procedure

Implement controller extension
1. In your app, create a .controller.js file for your extension.
  In the code sample below, we assume the following:
  - App name: my_app
  - File names: MyListReportExt.controller.js (extending the ListReport controller), MyObjectPageExt.controller.js (extending the ObjectPage controller)
  - Location of controller files: my_app/webapp/ext/controller
2. In your controller extension, implement the event handler functions to be executed when the user selects the action. For example, if you want to extend the ListReport controller, your controller extension should look like this:
  sap.ui.define("my_app.ext.controller.ListReportExtension", [], function() { return { onCustomAction1 : function(oEvent) { … }, onCustomAction2 : function(oEvent) { … }, … } })
When implementing the handler functions for your custom actions, you must use the Using the extensionAPI.

Extend the manifest.json file

In your app's manifest.json file, under sap.ui5 → extends → extensions, you can specify extensions for the ListReport and the ObjectPage controllers.

Specify the following information and extend the manifest files as described below:

`<entity set>`	Entity set that is displayed on the list report or on the object page (for example, `SMART_C_Product`) Note If you use multiple views with different `entity sets` on the list report page, `Actions` need to be defined only for main entity set. It is not possible to execute `Actions` defined for other `entity sets`.
`<Action 1>`, `<Action 2>`, …	Action names
`<id>`	ID to be used for the action button Note The values of the action name and the ID should be identical.
`<button text>`	nullText to be displayed on the button (typically a binding to an i18n entry, for example, null<button text>nullnull`{i18n>MY_BUTTON_TEXT}`)
`<handler function>`	Handler function that is called when the user selects the action button
`<global>` (required)	Indicates whether this is a global action. The default value is `false`. Note If a determining property is set along with the global property, the action is rendered as a global action since this takes precedence.
Relevant only for table toolbar actions in the list report and object page: `<requiresSelection>` (optional)	Property that indicates whether the action requires a selection of items. The default value is `true`.
Relevant only for list report actions and object page header actions: `<determining>` (optional)	Property that indicates whether the action should be displayed in the footer of the page. The default value is `false`.
Relevant only for object page actions: `<SmartTable Facet ID>`	ID that either comes from the annotation in which you have provided an ID for the facet or that's made up of the annotation term plus the navigation property. For example: <entity type association>::com.sap.vocabularies.UI.v1.LineItem

Table toolbar action for the list report

...
"extends": {
  "extensions": {
    "sap.ui.controllerExtensions": {
      "sap.suite.ui.generic.template.ListReport.view.ListReport": {
        "controllerName": "my_app.ext.controller.ListReportExtension",
          "sap.ui.generic.app": {
            "<entity set>": {
              "EntitySet": "<entity set>",
              "Actions": {
                "<Action 1>": {
                  "id" : "<id>",
                  "text" : "<button text>",
                  "press" : "<handler function>",
                  "requiresSelection": <true|false>
                },
                "<Action 2>": {
                  ...
                },
                ...
              }
              ...

Action for the object page header

...
"extends": {
  "extensions": {
    "sap.ui.controllerExtensions": {
      ...
      "sap.suite.ui.generic.template.ObjectPage.view.Details": {
        "controllerName": "my_app.ext.controller.DetailsExtension",
          "sap.ui.generic.app": {
            "<entity set>": {
              "EntitySet": "<entity set>",
              "Header" : {
                "Actions": {
                  "<Action 1>": {
                    "id" : "<id>",
                    "text" : "<button text>",
                    "press" : "<handler function>"
                  },
                  "<Action 2>": { ... }
                }
              },
...

Table toolbar action for the object page

...
"extends": {
  "extensions": {
    "sap.ui.controllerExtensions": {
      ...
      "sap.suite.ui.generic.template.ObjectPage.view.Details": {
        "controllerName": "my_app.ext.controller.DetailsExtension",
          "sap.ui.generic.app": {
            "<entity set>": {
              "EntitySet": "<entity set>",
              "Sections": {
                "<SmartTable Facet ID>": {
                  "id" : "<SmartTable Facet ID>",
                  "Actions": {
                    "<SmartTable Action 1>": {
                      "id" : "<id>",
                      "text" : "<button text>",
                      "press" : "<handler function>",
                      "requiresSelection": <true|false>
                    },
                    "<SmartTable Action 2>": { ... }
                  }
...

Form action for the object page

...
"extends": {
  "extensions": {
    "sap.ui.controllerExtensions": {
      ...
      "sap.suite.ui.generic.template.ObjectPage.view.Details": {
        "controllerName": "my_app.ext.controller.DetailsExtension",
          "sap.ui.generic.app": {
            "<entity set>": {
              "EntitySet": "<entity set>",
              "Sections": {
                "<Form Facet ID>": {
                  "id": "<Form Facet ID>",
                  "Actions": {
                    "<Action 1>": {
                      "id" : "<id>",
                      "text" : "<button text>",
                      "press" : "<handler function>"
                    },
                    "<Action 2>": { ... }
                  }
...

Footer bar action in the list report:

"sap.ui5": {
   "extends": {
      "extensions": {
         "sap.ui.controllerExtensions": {
            "sap.suite.ui.generic.template.ListReport.view.ListReport": {
               "controllerName": "my_app.ext.controller.ListReportExtension",
               "sap.ui.generic.app": {
                  "<entity set>": {
                     "EntitySet": "<entity set>",
                     "Actions": {
                        "<Action 1>": {
                           "id": "<id>",
                           "text": "<button text>",
                           "press": "<handler function>",
                           "determining": true
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

Footer bar action in the object page:

"sap.ui5": {
   "extends": {
      "extensions": {
         "sap.ui.controllerExtensions": {
            "sap.suite.ui.generic.template.ObjectPage.view.Detail": {
               "controllerName": "my_app.ext.controller.DetailsExtension",
               "sap.ui.generic.app": {
                  "<entity set>": {
                     "EntitySet": "<entity set>",
                     "Header": {
                        "Actions": {
                           "<Action 1>": {
                              "id": "<id>",
                              "text": "<button text>",
                              "press": "<handler function>",
                              "determining": true
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

List report (global action)

...
"extends": {
"extensions": {
"sap.ui.controllerExtensions": {
      "sap.suite.ui.generic.template.ListReport.view.ListReport": {
"controllerName": "my_app.ext.controller.ListReportExtension",
"sap.ui.generic.app": {
"<entity set>": {
"EntitySet": "<entity set>",
"Actions": {
"<Action 1>": {
                  "id" : "<id>",
"text" : "<button text>",
"press" : "<handler function>",
"global": <true|false>
},
"<Action 2>": {
...
},
...
}
...

Note

Please note that this topic has not yet been updated with information specific to OData V4.

Adding Custom Actions Using Extension Points

Adding Custom Actions Using Extension Points

Context

Procedure

In this section:

Related information