Plugins
Plugin capabilities — let administrators choose which role can do what
Declare a plugin's own permissions in the manifest, and administrators tick them per role under Users → Permissions — used by routes, admin pages, actions, content types and user.can() in code
On this page
A plugin can declare permissions of its own, such as "View statistics", "Publish docs" or "Change the API key", and the site's administrators choose which role gets which under Users → Permissions → 🔌 Plugin permissions. The plugin's code no longer hard-codes role names (available since Anasaki Studio 2.0.6, for JavaScript, service and WASM plugins).
1. Declare them in manifest.json#
{
"id": "page-translate",
"minCore": "2.0.6",
"capabilities": [
{ "id": "manage",
"label": { "th": "ตั้งค่าการแปลภาษา", "en": "Manage page translation" },
"description": { "th": "เปิดหน้า แปลภาษา (ตั้งค่า) และแก้โหมด", "en": "Open the settings page and change the mode" },
"default": ["administrator", "editor"] },
{ "id": "api_key",
"label": { "th": "แก้ Google API Key", "en": "Change the API key" },
"default": ["administrator"] }
]
}
| Field | Rules |
|---|---|
id | Starts with a-z, then a-z 0-9 _, 2–31 characters, unique in the plugin. The permission's full name is <plugin id>.<id>, e.g. page-translate.manage |
label | {th, en} or a string, up to 80 characters, shown on the Permissions page and at install |
description | Optional {th, en}, up to 300 characters |
default | Roles that get the permission on first install (administrator editor author contributor subscriber or custom roles), at most 20 |
At most 30 capabilities per plugin, and the Store checks the same rules at upload (Store 1.2.2 and later).
2. Using them in code#
A plugin may refer only to its own capabilities (<own id>.*) and system permissions — referring to another plugin's capability fails at registration.
access lists#
Add 'cap:<capability>' alongside role names; every role with that capability passes.
site.adminPage('settings', { label: { th: 'แปลภาษา (ตั้งค่า)', en: 'Page Translate' }, access: ['cap:page-translate.manage'], render });
site.action('saveApiKey', { access: ['cap:page-translate.api_key'], input: { apiKey: 'text?' }, run });
site.route('GET /reports/export', { access: ['cap:reports.export', 'administrator'] }, handler);
Works with site.route, site.page, site.collection, site.action, site.adminPage, site.dashboardWidget, site.adminNotice and access.edit of content types. Administrators can still override under Site Code → Access.
Checking in code#
run: ({ user }) => {
if (!user?.can('page-translate.api_key')) return { message: 'Not allowed to change the API key', errors: { form: 'forbidden' } };
// …
}
site.can(user, 'reports.export'); // user is null → false
user.caps; // system permissions + this plugin's capabilities the user has
Hiding buttons or forms with user.can() is cosmetic only — always check again in access or in the action's run.
Plugin content types#
site.postType('docs_doc', {
label: { th: 'เอกสาร', en: 'Docs' },
caps: { edit: 'docs.edit', publish: 'docs.publish' }, // who writes/edits and who publishes
});
caps.editreplaces the default list of editor rolescaps.publishrestricts publishing (without it, anyone who can edit can publish). Published articles can be edited or deleted only by those who can publish- REST
/api/v1/postsanddb.postsenforce this, andGET /api/v1/post-typesreportscanEdit/canPublishfor the calling user
Service / WASM plugins#
- Admin pages: set
service.admin[].capto"<own id>.<id>" - The user data sent along (the
X-Anasaki-Userheader and theplugins.callbody) hasuser.caps, combining system permissions and this plugin's capabilities
3. Supporting older Anasaki Studio versions#
Versions before 2.0.6 don't know capabilities (they simply skip it) but do not accept cap: in access. Check for site.can first:
const CAPS = typeof (site as any).can === 'function'; // 2.0.6+
const ACCESS_MANAGE = CAPS ? ['cap:page-translate.manage'] : ['editor'];
site.adminPage('settings', { label: 'Page Translate', access: ACCESS_MANAGE, render });
If you don't need older versions, set "minCore": "2.0.6" or later and use cap: directly.
4. Install, update and uninstall#
- Install or update: capabilities the site has never seen go to the roles in
default; existing ones keep what the administrator set. An update therefore never gives back a capability the administrator removed - An update that drops a capability, or uninstalling: it disappears from every role; the roles' other permissions stay. On reinstall, only never-seen capabilities get their defaults
- Administrators always have every permission, and plugin capabilities apply only while the plugin is installed
- The install dialog lists the capabilities the plugin will add, so administrators see them before installing
5. Naming capabilities well#
- Split by what people do, not by screen:
view,edit,publish,manage,export - Keep risky actions separate, such as changing an API key or deleting all data, with
defaultset toadministratoronly - Write
labelanddescriptionfor administrators who don't code — that text is all they see on the Permissions page
Full details in Plugin API; the official Docs and Analytics plugins are examples that use their own capabilities.
