Current File : //www/varak.net/nextcloud.varak.net/apps/app_api/docs/tech_details/api/fileactionsmenu.rst
.. _file_actions_menu_section:
=================
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):
.. code-block:: json
{
"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:
.. code-block:: json
{
"name": "unique_name_of_file_action_menu"
}
.. _node_info:
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:
.. code-block:: json
{
"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 <https://github.com/cloud-py-api/ui_example>`_.
Request flow
^^^^^^^^^^^^
General workflow of ExApp based on FileActionsMenu.
User action
***********
.. mermaid::
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``).
.. mermaid::
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 <https://github.com/cloud-py-api/nc_py_api/tree/main/examples/as_app/to_gif>`_ - ExApp based on FileActionsMenu to convert videos to gif in place
* `upscaler_example <https://github.com/cloud-py-api/upscaler_example.git>`_ - ExApp based on FileActionsMenu to upscale image in place
Mini Shell