.. _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
