Writing Nextcloud App with UI

Note

It is advisable to have experience writing PHP applications for Nextcloud, since the UI of applications not written in PHP is exactly the same.

One of the most interesting features is the ability to register a page in the Nextcloud Top Menu.

Full source of UI example can be found here: UiExample

Here we will simply describe in detail what happens in the example.

if enabled:
    nc.ui.resources.set_initial_state(
        "top_menu", "first_menu", "ui_example_state", {"initial_value": "test init value"}
    )
    nc.ui.resources.set_script("top_menu", "first_menu", "js/ui_example-main")
    nc.ui.top_menu.register("first_menu", "UI example", "img/icon.svg")
    if nc.srv_version["major"] >= 29:
        nc.ui.settings.register_form(SETTINGS_EXAMPLE)

set_initial_state is analogue of PHP OCP\AppFramework\Services\IInitialState::provideInitialState

set_script is analogue of PHP Util::addScript

There is also set_style (Util::addStyle) that can be used for CSS files and works the same way as set_script.

Starting with Nextcloud 29 AppAPI supports declaring Settings UI, with very simple and robust API.

Settings values you declare will be saved to preferences_ex or appconfig_ex tables and can be retrieved using nc_py_api._preferences_ex.PreferencesExAPI or nc_py_api._preferences_ex.AppConfigExAPI APIs.

Backend

class Button1Format(BaseModel):
    initial_value: str


@APP.post("/verify_initial_value")
async def verify_initial_value(
    input1: Button1Format,
):
    print("Old value: ", input1.initial_value)
    return responses.JSONResponse(content={"initial_value": str(random.randint(0, 100))}, status_code=200)


class FileInfo(BaseModel):
    getlastmodified: str
    getetag: str
    getcontenttype: str
    fileid: int
    permissions: str
    size: int
    getcontentlength: int
    favorite: int


@APP.post("/nextcloud_file")
async def nextcloud_file(
    args: dict,
):
    print(args["file_info"])
    return responses.Response()

Here is defining two endpoints for test purposes.

The first is to get the current initial state of the page when the button is clicked.

Second one is receiving a default information about file in the Nextcloud.

Frontend

The frontend part is the same as the default Nextcloud apps, with slightly different URL generation since all requests are sent through the AppAPI.

JS Frontend part is covered by AppAPI documentation: to_do

Important notes

We do not call top_menu.unregister or resources.delete_script as during uninstalling of application AppAPI will automatically remove this.

Note

Recommended way is to manually clean all stuff and probably if it was not an example, we would call all unregister and cleanup stuff during disabling.

All resources of ExApp should be avalaible and mounted to webserver(FastAPI + uvicorn are used by default for this).

Note

This is in case you have custom folders that Nextcloud instance should have access.

P.S.: If you are missing some required stuff for the UI part, please inform us, and we will consider adding it.