Adding Custom Actions Using Extension Points

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

Note:

For information about SAP Fiori elements for OData V4, see Adding Custom Actions Using Extension Points.

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 placement and layout) and system behavior (for example, model and binding usage, busy handling) lies within the application's responsibility. SAP Fiori elements provides support only for the official extensionAPI functions. Don't access or manipulate controls, properties, models, or other internal objects created by the SAP Fiori elements framework.

You can define custom actions for:

List report page (global action)

For global actions, you do not have to select a line in the list report page table. This type of action refers to the whole list report page, for example, Display Log. Global actions are placed in the list report page filter bar next to the Share button.
Table toolbar of the list report page
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 MainObjectPage controller), MySubObjectPageExt.controller.js (extending the SubObjectPage controller). Individual Controller extensions can be created for each object page. For more information, see Extending SAP Fiori Elements-Based Apps.
  - 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([], 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 page 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 on the list report page and the 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 page 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
`<applicablePath>`	Determines if a custom action should be visible or enabled.
`<command>`	Represents the command mapped to a keyboard shortcut defined under `sap.ui.commands` Note: If you are adding the command settings to an existing custom action, the parameter, that is, `oEvent` passed to the event handler of that custom action, is changed. It requires code adaptation if the code in the event handler depends on the `oEvent` parameter. You must not use a keyboard shortcut that is provided by default as custom action keyboard shortcut. For example, [Ctrl] + [E] , [Ctrl] + [Enter] and all other default keyboard shortcut should not be overridden.

Table toolbar action for the list report page
```
...
"extends": {
    "extensions": {
        "sap.ui.commands": {
            "<ComponentName>#<Component ID without app ID prefix>": {
                "<CustomActionCommandName>": {
                    "shortcut": "Ctrl+G"
                }
            }
        },
        "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 >,
                                    "applicablePath": <path>,
                                    "command": "<CustomActionCommandName>"
                                 },
                                "<Action 2>": {
                                    ...
                                },
                            ...
                        }
                        ...
                    }
                }
            }
        }
    }
}
```
An example of <ComponentName>#<Component ID without app ID prefix> is sap.suite.ui.generic.template.ListReport#sap.suite.ui.generic.template.ListReport::STTA_C_MP_Product.

In order to construct this string, you need the following information:
- <ComponentName>: You can use the component name used in the pages structure of sap.ui.generic.app namespace in the manifest. For example, sap.suite.ui.generic.template.ListReport.
- <Component ID without app ID prefix>: You can get the corresponding component first, that can be fetched in the following ways:
  - Using the corresponding xml view
    
    For example, Element.getElementById('STTA_MP::sap.suite.ui.generic.template.ListReport.view.ListReport::STTA_C_MP_Product').getController().getOwnerComponent().getId() where STTA_MP::sap.suite.ui.generic.template.ListReport.view.ListReport::STTA_C_MP_Product is the XmlView ID, and Element is required from module sap/ui/core/Element.
  - Using ComponentContainer
    
    Element.getElementById('__xmlview0-__clone0--host').getComponent() where __xmlview0-__clone0--host is the ComponentContainer ID, and Element is required from module sap/ui/core/Element.
  The result is generated in this <app component prefix>---<local component ID> format. For example,application-EPMProduct-manage_st-component---sap.suite.ui.generic.template.ListReport::STTA_C_MP_Product. You can remove the app component prefix from the string along with the dashes.

Action for the object page header

...
"extends": {
    "extensions": {
        "sap.ui.commands": {
            "<ComponentName>#<Component ID without app ID prefix>": {
                "<CustomCommandName>": {
                    "shortcut": "Ctrl+K"
                }
            }
        },
        "sap.ui.controllerExtensions": {
            ...
            "sap.suite.ui.generic.template.ObjectPage.view.Details#my_app::sap.suite.ui.generic.template.ObjectPage.view.Details:: <entity set>": {
                "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>"
                                    "applicablePath": <path>,
                                    "command": "<CustomCommandName>"
                                },
                                "<Action 2>": { 
                                    ... 
                                }
                            }
                        },
...

Table toolbar action for the object page

"extends": {
    "extensions": {
        "sap.ui.controllerExtensions": {
            "sap.suite.ui.generic.template.ObjectPage.view.Details#my_app::sap.suite.ui.generic.template.ObjectPage.view.Details::<entity set>": {
                "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>",
                                        "applicablePath": "<path>",
                                        "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>",
                                        "applicablePath": "<path>"
                                    },
                                    "<Action 2>": {
                                        
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Footer bar action on the list report page:

"sap.ui5": {
   "extends": {
      "extensions": {
         "sap.ui.controllerExtensions": {
            "sap.suite.ui.generic.template.ObjectPage.view.Details#my_app::sap.suite.ui.generic.template.ObjectPage.view.Details:: <entity set>":  {
               "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
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

Tip:

Please note that this feature is deprecated. SAP Fiori elements supports this feature only for compatibility reasons. We recommend that you avoid using determining buttons.

Footer bar action in the object page:

"sap.ui5": {
   "extends": {
      "extensions": {
         "sap.suite.ui.generic.template.ObjectPage.view.Details#my_app::sap.suite.ui.generic.template.ObjectPage.view.Details:: <entity set>":  {
            "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>",
                              "applicablePath": <path>,
                              "determining": true
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

List report page (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>": {
                                
                            }
                        }
                    }
                }
            }
        }
    }
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adding Custom Actions Using Extension Points

Note:

Context

Caution:

Procedure

Note:

Note:

Note:

Note:

Tip:

FilesExpand file tree

adding-custom-actions-using-extension-points-3530e6b.md

Latest commit

History

adding-custom-actions-using-extension-points-3530e6b.md

File metadata and controls

Adding Custom Actions Using Extension Points

Note:

Context

Caution:

Procedure

Note:

Note:

Note:

Note:

Tip: