docs: clarify capability contextlevel guidance#1615
Conversation
✅ Deploy Preview for moodledevdocs ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
| | `archetypes` | specifies defaults for roles with standard archetypes, this is used in installs, upgrades and when resetting roles (it is recommended to use only CAP_ALLOW here). Archetypes are defined in mdl_role table. See also [Role archetypes](https://docs.moodle.org/dev/Role_archetypes). | | ||
| | `clonepermissionsfrom` | when you are adding a new capability, you can tell Moodle to copy the permissions for each role from the current settings for another capability. This may give better defaults than just using archetypes for administrators who have heavily customised their roles configuration. The full syntax is: `clonepermissionsfrom` => `moodle/quiz:attempt` | | ||
|
|
||
| When choosing `contextlevel`, pick the highest context where the capability is expected to be checked and overridden. Moodle can still check the capability in lower contexts, but it only appears in override screens where changing it can affect the result. For example, `moodle/site:config` uses `CONTEXT_SYSTEM`, so it is not shown in course or activity overrides because changing it there would have no effect when the capability is checked at system context. |
There was a problem hiding this comment.
By highest, do you mean "largest number"? Initially, I thought of "highest point, hierarchically", where CONTEXT_SYSTEM is the top of the pyramid and each "lower" level has more items (and thus more width).
Here is an idea that I had (it's not perfect, but I hope it is helpful):
When choosing contextlevel, use the most specific level where the capability can be overridden. A permission can only be managed at the chosen level or levels with a more general scope. For example, moodle/site:config uses CONTEXT_SYSTEM, so it can only be set or overridden at the system context (the widest scope). Moodle intentionally hides the capability from override screens that have a more specific scope.
2 participants
Summary
contextlevelshould match the highest context where a capability is checked and overriddenmoodle/site:configCloses #1339
Validation
corepack yarn mdlint docs/apis/subsystems/access.md versioned_docs/version-4.5/apis/subsystems/access.md versioned_docs/version-5.0/apis/subsystems/access.md versioned_docs/version-5.1/apis/subsystems/access.md versioned_docs/version-5.2/apis/subsystems/access.mdlint-stagedhook (markdownlint-cli2 --fixandcspell --no-must-find-files --no-progress) ran during commit