62 lines
7.3 KiB
Markdown
62 lines
7.3 KiB
Markdown
# go-nc-exapp
|
||
|
||
Shared Go Library for Nextcloud ExApp Services: AppAPI authentication, OCS calls, per-user ExApp preferences, Notifications, Users and Groups, the Requesting user's UI language, and optional Required Groups gating. ExApps import `gitea.neitzel.de/konrad/go-nc-exapp`. File storage and folder visits live in go-nc-files.
|
||
|
||
## Language
|
||
|
||
**AppAPI credentials**:
|
||
The ExApp's shared secret and Nextcloud base URL, plus optional per-request user identity. Used to sign outbound calls to Nextcloud and to read the requesting user from inbound AppAPI-proxied requests.
|
||
_Avoid_: API key (generic), session token
|
||
|
||
**Requesting user**:
|
||
The Nextcloud user on whose behalf the current ExApp request runs, taken from AppAPI authorization headers. WebDAV, preferences, and a Notification to that same user use this identity; there is no separate ExApp login.
|
||
_Avoid_: service account (for per-request identity), anonymous
|
||
|
||
**UI language**:
|
||
The Nextcloud language of the Requesting user, not the locale. A stored personal language is used. When none is stored, the browser language is used, then the instance default, then English. The Library resolves it once for a page. ExApp pages and the Library's own chrome use that same language for their Phrases. English and German are the languages the Library provides. A more specific code uses the broader language when that is the one provided. Any language the Library does not provide uses English. When the UI language cannot be read, it is English, and the page still renders.
|
||
_Avoid_: locale, Accept-Language, ExApp preference
|
||
|
||
**Phrase**:
|
||
A label or sentence on an ExApp page, identified by one stable name, not by the English text. English and German are two texts for that same Phrase. A Phrase is one text per language. A count is a hole, not a second form. English is the complete set. A Phrase with no text for the UI language shows the English text. An id with no English text shows the id. A Phrase may contain named holes for values the page inserts. English and German name the same holes and may place them differently. A hole with no value stays visible. Those values are not Phrases. The ExApp owns the Phrases of its pages and of its navigation items. The Library owns the Phrases of App navigation chrome and of Dialog buttons. A Library or an ExApp has one default set. A module keeps its own set with that module. The English text stays on the page, and the element names its Phrase, including a placeholder, a title, or an aria-label. The script shows the text for the UI language. A hole value is plain text. An error the page displays is the finished sentence for the UI language, not the id. The page and its script show the ExApp's default set and any module sets, as one map. A repeated id uses the text from the set added later. The Library writes its own Phrases into the chrome it renders, and that set is not in the map.
|
||
_Avoid_: Catalog, Message, user data, zone name, Notification subject
|
||
|
||
**Recipient**:
|
||
The Nextcloud user a Notification is created for. May be the Requesting user or another user. AppAPI accepts one Recipient per call; sending to a group or to all admins is many Notifications.
|
||
_Avoid_: destination, target (HTTP), addressee, treating a group as a Recipient
|
||
|
||
**ExApp preference**:
|
||
A string value stored in Nextcloud for one user and one ExApp, keyed by the ExApp (not admin AppConfig). Libraries expose a parameterized key; each ExApp chooses its own key names.
|
||
_Avoid_: settings file in User Files, instance-wide config
|
||
|
||
**Notification**:
|
||
A Nextcloud bell-icon message that an ExApp creates for one Recipient via AppAPI. It has a Subject, optional Message, optional Link, and optional rich-object params. AppAPI’s OCS is limited: no actions and no custom icon. One AppAPI call creates one Notification; the Recipient is the user the ExApp impersonates for that call, not a field in the message body.
|
||
_Avoid_: Denied UI, email, Talk message, in-app banner, toast, treating this as a full PHP INotifier
|
||
|
||
**OCS**:
|
||
Nextcloud's legacy HTTP API surface under `/ocs/v2.php/…`. This Library requests JSON responses (`format=json`) for machine-readable bodies.
|
||
_Avoid_: assuming XML responses, REST-only Nextcloud APIs for ExApp prefs
|
||
|
||
**Required Groups**:
|
||
The Nextcloud groups configured for an ExApp (comma-separated deploy env `REQUIRED_GROUPS`) such that membership in any one of them is enough to use the ExApp. Empty or unset means no group restriction. AppAPI does not enforce this; the ExApp does.
|
||
_Avoid_: AppAPI scopes, route access_level, admin-only top menu, treating the ExApp id as an implicit group name, Users and Groups (that is the OCS directory, not this ACL)
|
||
|
||
**Users and Groups**:
|
||
Nextcloud's Provisioning OCS this Library wraps as three reads: the groups of one user (as that user), the members of one group, and the instance group list. Member and instance lists run as the Requesting user and succeed only if that user is an admin or a subadmin of the group. Distinct from Required Groups.
|
||
_Avoid_: Group-API, Required Groups, AppAPI scopes, treating a group as a Recipient
|
||
|
||
**Access Gate**:
|
||
The Library check that enforces Required Groups for the Requesting user on ExApp HTTP traffic (403 or denied UI when not a member; 401 without a user; 503 when membership cannot be determined). It reads the user's groups through Users and Groups. Lifecycle paths and top-menu script URLs under `/js/` stay ungated so Denied UI can load in the Nextcloud shell.
|
||
_Avoid_: Nextcloud middleware, HaRP ACL, admin bypass, gating the top-menu bootstrap script
|
||
|
||
**App navigation**:
|
||
The tree of named items along the left of an ExApp page. The ExApp supplies the tree. The selected item is the page on display. It plays the same role as the navigation in Nextcloud Files. On a screen at most 1024px wide the tree is hidden until the user opens it; choosing an item, pressing Escape, or clicking outside closes it again. An ExApp that does not use App navigation shows its own page instead. The Library's own phrases on that chrome follow the UI language. The names of the items are the ExApp's.
|
||
_Avoid_: Top Menu, sidebar, NcAppNavigation
|
||
|
||
**Dialog**:
|
||
A modal window on an ExApp page, in the same Nextcloud theme as that page. It does not require App navigation. The page waits for the user's choice; that choice is not a server request. The heading, the message, and the button word are plain text. The heading may be omitted. The fixed buttons follow the UI language. The Library provides them in English and German. One of three kinds: a Message (short text at info, warning, or error, dismissed with one button), a Confirm (yes or no; the agreeing button may be destructive), or a Prompt (one entered value, or cancelled). A Prompt with no value cannot be agreed. A successful Prompt value has no surrounding spaces. The caller may supply a starting value. A Prompt field has no label of its own; the message is the text above it.
|
||
_Avoid_: popup, browser alert/confirm/prompt, Notification, toast, HTML message
|
||
|
||
**Top Menu visibility**:
|
||
Whether the ExApp app icon in the Nextcloud top menu is shown to all logged-in users or to Nextcloud admins only. Configured per deploy via env `TOP_MENU_ADMIN_REQUIRED` (`0` or `1`); the ExApp passes the value to AppAPI when registering the top-menu entry on enable. Independent of route `access_level` in info.xml and of Required Groups.
|
||
_Avoid_: route access_level, Required Groups, AppAPI group ACL
|