File Actions Menu

FileActionsMenu is a simple API for registering entry to the file actions menu for ExApps. AppAPI takes responsibility to register FileActionsMenu, ExApps needs only to register it in AppAPI.

Note

FileActionsMenu rendered only for enabled ExApps.

Register

Note

With AppAPI 2.6.0 there is a new v2 OCS endpoint with redirect to ExApp UI support: OCS endpoint: POST /apps/app_api/api/v2/ui/files-actions-menu. Old v1 is marked as deprecated.

OCS endpoint: POST /apps/app_api/api/v1/ui/files-actions-menu

Params

Complete list of params (including optional):

{
        "name": "unique_name_of_file_actions_menu",
        "displayName": "Display name (for UI listing)",
        "actionHandler": "/action_handler_route"
        "mime": "mime of files where to display action menu",
        "icon": "img/icon.svg",
        "permissions": "permissions",
        "order": "order_in_file_actions_menu",
}

Note

Urls icon and actionHandler are relative to the ExApp root, starting slash is not required.

Optional params

permissions - File permissions required to display action menu, default: 31 (all permissions)

order - Order in file actions menu, default: 0

icon - Url to icon, default: null

mime - One mime or mimes separated by commas, default: file

Unregister

OCS endpoint: DELETE /apps/app_api/api/v1/ui/files-actions-menu

Params

To unregister FileActionsMenu, you just need to provide name of registered FileActionsMenu:

{
        "name": "unique_name_of_file_action_menu"
}

Action payload to ExApp

When FileActionsMenu invoked, AppAPI forwards action for handling to ExApp. The following data is sent to ExApp FileActionsMenu handler from the context of action:

{
        "fileId": "123",
        "name": "filename",
        "directory": "relative/to/user/path/to/directory",
        "etag": "file_etag",
        "mime": "file_full_mime",
        "fileType": "dir/file",
        "mtime": "last modify time(integer)",
        "size": "integer",
        "favorite": "nc_favorite_flag",
        "permissions": "file_permissions_for_owner",
        "shareOwner": "optional, str",
        "shareOwnerId": "optional, str",
        "shareTypes": "optional, int",
        "shareAttributes": "optional, int",
        "sharePermissions": "optional, int",
        "userId": "string",
        "instanceId": "string",
}

Redirect to ExApp UI page (top menu)

Note

Supported only for Nextcloud 28+.

If you want to open some files in ExApp UI, your FileActionsMenu have to be registered using OCS v2 version (/apps/app_api/api/v2/ui/files-actions-menu).

After that, AppAPI will expect in the JSON response of the ExApp action_handler the redirect_handler - a relative path on the ExApp Top Menu page, to which AppAPI will attach a fileIds query parameter with the selected file ids, for example:

/index.php/apps/app_api/embedded/ui_example/first_menu/second_page?fileIds=123,124,125,

where the first_menu is the name of the Top Menu ExApp UI page, and the second_page relative route handled on the frontend routing of the ExApp, the fileIds query parameter contains the selected file ids separated by commas. After that you can get the files info via webdav search request, see ui_example.

Request flow

General workflow of ExApp based on FileActionsMenu.

User action

sequenceDiagram User->>FileActionMenu: Press on registered ExApp action FileActionMenu->>AppAPI: send action context payload AppAPI->>ExApp: forward request to handler ExApp->>AppAPI: handler accepted action status AppAPI->>User: Alert (action sent or error)

Action results

File processing results could be stored next to initial file or anywhere else, e.g. on configured location in ExApp settings (appconfig_ex) or ExApp user settings (preferences_ex).

sequenceDiagram ExApp->>Nextcloud: Upload result file ExApp->>AppAPI: Send notification about action results

Examples

Here is a list of simple example ExApps based on FileActionsMenu:

to_gif - ExApp based on FileActionsMenu to convert videos to gif in place
upscaler_example - ExApp based on FileActionsMenu to upscale image in place