These definitions are from the docblock comment on the DAO properties. A quick search for public $is_reserved
showed 10 entities with this property, but I will focus on these three for now.
is_reserved
: Is this a predefined system option group (i.e. it can not be deleted)?is_locked
: A lock to remove the ability to add new options via the UI.
is_reserved
: Is this a predefined system object?
is_reserved
: Is this a reserved Custom Group?
Type | Editable via UI | Editable via API |
---|---|---|
Reserved Custom Group | No, does not appear in civicrm/admin/custom/group |
Yes, could delete |
Locked Option Group | Yes**, but addding new options is disabled. Non-reserved option values can be deleted | Yes, could delete |
Reserved Option Group | Yes**, options can be added and deleted | Yes, could delete |
Reserved Option Value | Yes, but option to delete doesn't appear | Yes, could delete |
** I can't find any way to delete any option group via the UI
is_reserved
: For custom groups it means "hide it from editing in the UI". For option values it means "hide delete option in the UI". For option groups it means nothing.is_locked
: For options groups it means "hide the option to add a new option value"
- As an extension developer I want to ensure some critical option groups and custom groups will not be deleted. I still want to be able to edit or delete them via the API (for example in
hook_civicrm_uninstall
). - As an organization we want to have a consistent language with the same rules being applied each time a concept such as
is_reserved
is used.
is_reserved
means it will be uneditable from the UI. Attempts to modify via API will fail. Modification is possible, but only after changingis_reserved
tofalse
.is_locked
is only for groups containing child items. It means no items can be added or removed.is_reserved
is ignored on child items if the parent is deleted. For example, deleting a non-reservedoption_group
will also delete reservedoption_values
in it.
- While it would be simpler to say
is_reserved
means uneditable, there are some properties would be very helpful to edit, even if the entity was reserved. For example "Title" and "Descrption" foroption_group
, "Weight", "Description" and "Label" foroption_value
or "Title" and "Weight" forcustom_group
. We might consider allowing edits to just these properties for reserved entities. That said, it would be much easier to stick to the logic of disallowing any edit to reserved entities. - There could be some confusion if we hide reserved items. We might decide to show reserved items, but in uneditable form.
For CustomGroups the flag is important because it hides the reserved groups from the edit screen, regardless of user permissions.
Reserved CustomGroups are hidden from the UI (civicrm/admin/custom/group) right now. While I like how this prevents them from being edited, I think it's a bit confusing if someone knows these CustomGroups do exist, but just can't see them. In my mind it would be clearer to show them, but just don't allow them to be deleted.
That's true, it might be a step too far. It's like a safeguard to protect against unintended edits, but it doesn't stop the user in the end.
What I'd like it a broad definition of what it means to be "is_reserved" and "is_locked", for example these questions might be used to make a definition. I'm not talking about permissions here. Like you said, you need the "Administer CiviCRM" permission to edit these anyway, this definition would be for all users, regardless of permission.
name
?extends
for Custom Group?label
,description
?n/a
n/a
We might also consider the same list of questions to define
is_locked