From e9117ab3702bb37c12995e85c7cbd82c3cce15a9 Mon Sep 17 00:00:00 2001 From: Neill Magill Date: Fri, 9 May 2025 08:44:46 +0100 Subject: [PATCH] #1339 Improve description of contextlevel in capability declaration There was confusion in the developer chat channel around how the context level should be set in. This change will hopefully help make it clear how the context level should be set and what its effect is. --- docs/apis/subsystems/access.md | 2 +- versioned_docs/version-4.1/apis/subsystems/access.md | 2 +- versioned_docs/version-4.4/apis/subsystems/access.md | 2 +- versioned_docs/version-4.5/apis/subsystems/access.md | 2 +- versioned_docs/version-5.0/apis/subsystems/access.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/apis/subsystems/access.md b/docs/apis/subsystems/access.md index 28e85e6e5..c382c09da 100644 --- a/docs/apis/subsystems/access.md +++ b/docs/apis/subsystems/access.md @@ -62,7 +62,7 @@ Where the meaning of array keys is: | --- | --- | | `riskbitmask` | associated risks. These are explained on [Hardening new Roles system](./roles.md). | | `captype` | _read_ or _write_ capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users | -| `contextlevel` | specified as context level constant. Declares the typical context level where this capability is checked. This capability can be checked with contexts that are at a lower level (e.g. `moodle/site:accessallgroups` could be checked with CONTEXT_MODULE). | +| `contextlevel` | specified as context level constant. Declares the lowest context level where this capability is checked. The definition affects where users have the ability to override the capability, for example if a capability is defined as having a `CONTEXT_SYSTEM` context users would not be able to override it at any other levels; however if it was set at `CONTEXT_MODULE` user would be able to override it at the activity, course, and category levels | | `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` | diff --git a/versioned_docs/version-4.1/apis/subsystems/access.md b/versioned_docs/version-4.1/apis/subsystems/access.md index 28e85e6e5..c382c09da 100644 --- a/versioned_docs/version-4.1/apis/subsystems/access.md +++ b/versioned_docs/version-4.1/apis/subsystems/access.md @@ -62,7 +62,7 @@ Where the meaning of array keys is: | --- | --- | | `riskbitmask` | associated risks. These are explained on [Hardening new Roles system](./roles.md). | | `captype` | _read_ or _write_ capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users | -| `contextlevel` | specified as context level constant. Declares the typical context level where this capability is checked. This capability can be checked with contexts that are at a lower level (e.g. `moodle/site:accessallgroups` could be checked with CONTEXT_MODULE). | +| `contextlevel` | specified as context level constant. Declares the lowest context level where this capability is checked. The definition affects where users have the ability to override the capability, for example if a capability is defined as having a `CONTEXT_SYSTEM` context users would not be able to override it at any other levels; however if it was set at `CONTEXT_MODULE` user would be able to override it at the activity, course, and category levels | | `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` | diff --git a/versioned_docs/version-4.4/apis/subsystems/access.md b/versioned_docs/version-4.4/apis/subsystems/access.md index 28e85e6e5..c382c09da 100644 --- a/versioned_docs/version-4.4/apis/subsystems/access.md +++ b/versioned_docs/version-4.4/apis/subsystems/access.md @@ -62,7 +62,7 @@ Where the meaning of array keys is: | --- | --- | | `riskbitmask` | associated risks. These are explained on [Hardening new Roles system](./roles.md). | | `captype` | _read_ or _write_ capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users | -| `contextlevel` | specified as context level constant. Declares the typical context level where this capability is checked. This capability can be checked with contexts that are at a lower level (e.g. `moodle/site:accessallgroups` could be checked with CONTEXT_MODULE). | +| `contextlevel` | specified as context level constant. Declares the lowest context level where this capability is checked. The definition affects where users have the ability to override the capability, for example if a capability is defined as having a `CONTEXT_SYSTEM` context users would not be able to override it at any other levels; however if it was set at `CONTEXT_MODULE` user would be able to override it at the activity, course, and category levels | | `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` | diff --git a/versioned_docs/version-4.5/apis/subsystems/access.md b/versioned_docs/version-4.5/apis/subsystems/access.md index 28e85e6e5..c382c09da 100644 --- a/versioned_docs/version-4.5/apis/subsystems/access.md +++ b/versioned_docs/version-4.5/apis/subsystems/access.md @@ -62,7 +62,7 @@ Where the meaning of array keys is: | --- | --- | | `riskbitmask` | associated risks. These are explained on [Hardening new Roles system](./roles.md). | | `captype` | _read_ or _write_ capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users | -| `contextlevel` | specified as context level constant. Declares the typical context level where this capability is checked. This capability can be checked with contexts that are at a lower level (e.g. `moodle/site:accessallgroups` could be checked with CONTEXT_MODULE). | +| `contextlevel` | specified as context level constant. Declares the lowest context level where this capability is checked. The definition affects where users have the ability to override the capability, for example if a capability is defined as having a `CONTEXT_SYSTEM` context users would not be able to override it at any other levels; however if it was set at `CONTEXT_MODULE` user would be able to override it at the activity, course, and category levels | | `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` | diff --git a/versioned_docs/version-5.0/apis/subsystems/access.md b/versioned_docs/version-5.0/apis/subsystems/access.md index 28e85e6e5..c382c09da 100644 --- a/versioned_docs/version-5.0/apis/subsystems/access.md +++ b/versioned_docs/version-5.0/apis/subsystems/access.md @@ -62,7 +62,7 @@ Where the meaning of array keys is: | --- | --- | | `riskbitmask` | associated risks. These are explained on [Hardening new Roles system](./roles.md). | | `captype` | _read_ or _write_ capability type, for security reasons system prevents all write capabilities for guest account and not-logged-in users | -| `contextlevel` | specified as context level constant. Declares the typical context level where this capability is checked. This capability can be checked with contexts that are at a lower level (e.g. `moodle/site:accessallgroups` could be checked with CONTEXT_MODULE). | +| `contextlevel` | specified as context level constant. Declares the lowest context level where this capability is checked. The definition affects where users have the ability to override the capability, for example if a capability is defined as having a `CONTEXT_SYSTEM` context users would not be able to override it at any other levels; however if it was set at `CONTEXT_MODULE` user would be able to override it at the activity, course, and category levels | | `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` |