Evaluating user permissions via the FirstSpirit API

User permissions can also be evaluated via the FirstSpirit API.

Interfaces (FirstSpirit Access API)

The API is accessed via the Permissions object, which returns the permissions that have been defined on the current FirstSpirit object.

FirstSpirit Access API: de.espirit.firstspirit.access.editor.value.Permissions

FirstSpirit Access API manual: Permissions

Restrictions when evaluating via the API

In an evaluation triggered by the template syntax, the inheritance hierarchy of the user permissions is taken into account automatically; this is not the case for an evaluation via the FirstSpirit API.

Inherited permissions are not taken into account

Please note: User permissions always apply to the object in the tree for which they were defined and are inherited by all objects assigned underneath that object within the tree structure. This means if no user permissions are defined in a tree object, the permissions of the higher-level object shall apply. Thanks to this definition of inheritance, permissions can simply be defined at a folder or root node level, for example, and those permissions will then apply to all pages below that level.

Example

Structure of site store root, permission definition, and inheritance of permissions:

• Store-Root (permission definition in the metadata via CMS_INPUT_PERMISSION)
  Defined: Anonymous users (“allowed”)
  Defined: Registered members (“allowed”)
  
  • Sitestore-folder (permission definition in the metadata via CMS_INPUT_PERMISSION)
    Defined: Anonymous users (“forbidden”)
    Defined: Registered members (“allowed”)
    
    • Page reference (no permission definition – permissions inherited via the folder)
      Inherited: Anonymous users (“forbidden”)
      Inherited: Registered members (“allowed”)

Groups.xml:

<GROUPS id="GroupsFile" name="GroupsFile" version="1">
     <GROUP id=anonymous" name="Anonymous users"/>
     <GROUP id="member" name="Registered members"/>
 </GROUP>

Evaluating via the template syntax

The #global.node call in the template set returns the current object (e.g., the page). The metadata of the current object can then be retrieved via .meta() (see Meta information (→FirstSpirit Online Documentation)).

This output of user permissions in the metadata template (with the explicit specification to use inherited permissions (“inherit”)):

$CMS_SET(currPerm, #global.node.meta("perms", "inherit"))$
$CMS_VALUE(currPerm.getForbidden("").toString(","))$
$CMS_VALUE(currPerm.getAllowed("").toString(","))$

returns these values (*) for the folder:

anonymous
member

and these values (*) for the Page reference:

anonymous
member

(*) The ID of the group is returned from the default configuration file groups.xml, not the name of the group (see above).

Starting from the page, the #global.node.meta(...) query is used to automatically check whether permissions have been defined on the page or whether permissions have been inherited from a higher-level node (in this case, from the folder).

Evaluating via the FirstSpirit API

This is different when evaluating via the API. If the user permissions for the object have not been set explicitly (“allowed” or “forbidden”), but have only been “inherited”, i.e., from a higher-level node, the Permissions object returns an empty list.

Groups for which no permissions have been defined are usually interpreted as being forbidden.

In this example, this means the output of

<IDProvider>.getMetaFormData().get(null,"perms").get().getForbidden("");
<IDProvider>.getMetaFormData().get(null,"perms").get().getAllowed("");

via the BeanShell console returns the following values (*) for the folder, since the permissions have been set explicitly on the folder:

anonymous
member

But for the page reference, only an empty list is returned, since both permissions were simply inherited from the folder:

(*) The ID of the group is returned from the default configuration file groups.xml, not the name of the group (see above).

This behavior must be taken into account when evaluating via the API. Before querying the content, a check should always be carried out to see whether metadata has been defined for this element and whether these permissions have been set there or inherited.

The query:

(<IDProvider>.hasMeta() && !<IDProvider>.getMetaFormData().get(null,<Name der Eingabekomponente>).get().isInherited())

checks whether an object has metadata (.hasMeta()) and also whether it has user permissions from inherited metadata.

If this query returns false, then this element obtains user permissions via the next-highest parent node that returns the value true for this query (in this case via the folder or, if no permissions have been defined there either, via the store root).