From c4cb0aeb269bc74170db8c509c6ce3991cfeb417 Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Mon, 9 Sep 2024 17:37:39 -0300 Subject: [PATCH 1/9] [UI] Displaying elements based on user permissions in Twig --- ...ing_elements_based_on_user_permissions.rst | 101 ++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 102 insertions(+) create mode 100644 docs/design/displaying_elements_based_on_user_permissions.rst diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst new file mode 100644 index 00000000..2bdb81e9 --- /dev/null +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -0,0 +1,101 @@ +Displaying elements based on user permissions +============================================= + +In Mautic, it's possible to control the visibility of elements on the user interface based on the user's permissions. This allows for showing or hiding certain features, links, or sections depending on the user's role and the permissions associated with that role. + +This approach enhances security and provides a tailored experience for each user based on their role and access level. + +Using the securityIsGranted function +------------------------------------ + +To display elements conditionally based on user permissions, use the securityIsGranted function in Twig templates. The securityIsGranted function checks if the current user has the specified permission and returns a boolean value indicating whether the permission is granted or not. + +Here's the basic syntax: + +.. code-block:: twig + + {% if securityIsGranted('permission:string') %} + + {% endif %} + +In this structure, 'permission:string' represents the specific permission being checked for. Mautic uses a hierarchical permission system, in the format of 'bundle:level:permission'. + +Displaying a user invitation link as example +-------------------------------------------- + +Let's examine a practical example of how to use this function to display a link for inviting new users to the platform. This link should only be visible to users who have the permission to create new user accounts. + +In this example, we're using the securityIsGranted function to check if the current user has the 'user:users:create' permission. This permission string is structured to indicate that we're checking for the ability to create new users within the user management system. + +.. code-block:: twig + + {% if securityIsGranted('user:users:create') %} +
  • + + + {{ 'mautic.user.profile.invite'|trans }} + +
    • + {% endif %} + +If the current user has the user:users:create permission, the code inside the if block will be rendered, displaying the link to invite new users. The link is created using the path function, which generates a URL based on the specified route (mautic_user_action) and any additional parameters ({objectAction: 'new'}). + +The 'mautic.user.profile.invite'|trans expression is used to translate the text "Invite your team" using Mautic's translation system. This ensures that the text is displayed in the appropriate language based on the user's locale settings. + +This not only prevents unauthorized access but also keeps the interface clean and relevant for each user's role. + +When implementing permission-based displays, it's essential to also secure the backend routes and actions that these interface elements might trigger. The frontend permission check should be considered an additional layer of security and user experience enhancement, not the sole method of access control. + +Locating defined permissions +---------------------------- + +Mautic organizes its permissions on a per-bundle basis. Each bundle typically defines its own set of permissions in a dedicated PHP file. The standard location for these permission definitions is: + +[BundleName]/Security/[BundleName]Permissions.php + +For example: + +- User permissions: UserBundle/Security/UserPermissions.php +- Email permissions: EmailBundle/Security/EmailPermissions.php +- SMS permissions: SmsBundle/Security/SmsPermissions.php + +These PHP files contain classes that extend AbstractPermissions and define the specific permissions available for that bundle. They usually include methods for building the permission matrix and checking individual permissions. + +Examining permission files +-------------------------- + +When opening one of these permission files, they'll typically find: + +- A definePermissions method that outlines all available permissions for the bundle. +- Constants defining permission levels (e.g., LEVEL_VIEW, LEVEL_EDIT, LEVEL_FULL). +- Methods for checking specific permissions (e.g., canViewUsers, canEditEmails). + +For example, in the UserPermissions.php file, the UserPermissions class defines the available permissions for the UserBundle using a more structured approach. Let's go through the important parts: + +.. code-block:: php + + $this->permissions = [ + 'profile' => [ + 'editusername' => 1, + 'editemail' => 2, + 'editposition' => 4, + 'editname' => 8, + 'full' => 1024, + ], + ]; + +In this example, the profile key represents the permission category, and the nested array defines the specific permission levels for actions like editing the username, email, position, name, and having full access to the user profile. + +To use these permission keys with the securityIsGranted function in Twig templates, construct the appropriate permission string. The permission string follows the format: [bundle]:[level]:[permission]. + +Map the permission keys from the UserPermissions class to the corresponding permission strings: + +- editusername => user:profile:editusername +- editemail => user:profile:editemail +- editposition => user:profile:editposition +- editname => user:profile:editname +- full => user:profile:full + +In each if statement, the securityIsGranted function is used with the corresponding permission string. If the current user has the specified permission, the code inside the if block will be executed, displaying the relevant form fields for editing the user profile information. + +For more information, refer to the Security documentation. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 5182201d..185abfd0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -57,6 +57,7 @@ There are several ways to support Mautic other than contributing with code. :hidden: design/retrieving_system_settings + design/displaying_elements_based_on_user_permissions .. toctree:: :maxdepth: 2 From 7eaa5c41df6fb2c2e3e226ad22a168c4219db5ba Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:04:23 -0300 Subject: [PATCH 2/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index 2bdb81e9..3322ee70 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -1,4 +1,4 @@ -Displaying elements based on user permissions +Displaying elements based on User permissions ============================================= In Mautic, it's possible to control the visibility of elements on the user interface based on the user's permissions. This allows for showing or hiding certain features, links, or sections depending on the user's role and the permissions associated with that role. From 28272a6d98d3f7863bbee37cd5b7b6cae2f27729 Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:04:33 -0300 Subject: [PATCH 3/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index 3322ee70..de4be404 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -1,7 +1,7 @@ Displaying elements based on User permissions ============================================= -In Mautic, it's possible to control the visibility of elements on the user interface based on the user's permissions. This allows for showing or hiding certain features, links, or sections depending on the user's role and the permissions associated with that role. +In Mautic, it's possible to control the visibility of elements on the user interface based on the User's permissions. This allows for showing or hiding certain features, links, or sections depending on the User's Role and the permissions associated with that Role. This approach enhances security and provides a tailored experience for each user based on their role and access level. From 4379dd8773b2b84def7c07585d0396acb15811a2 Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:04:39 -0300 Subject: [PATCH 4/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index de4be404..fe267778 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -3,7 +3,7 @@ Displaying elements based on User permissions In Mautic, it's possible to control the visibility of elements on the user interface based on the User's permissions. This allows for showing or hiding certain features, links, or sections depending on the User's Role and the permissions associated with that Role. -This approach enhances security and provides a tailored experience for each user based on their role and access level. +This approach enhances security and provides a tailored experience for each User based on their role and access level. Using the securityIsGranted function ------------------------------------ From 215162c4571d461ecfcebe93110a5088251e755e Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:04:44 -0300 Subject: [PATCH 5/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index fe267778..a31ff708 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -5,7 +5,7 @@ In Mautic, it's possible to control the visibility of elements on the user inter This approach enhances security and provides a tailored experience for each User based on their role and access level. -Using the securityIsGranted function +Using the ``securityIsGranted`` function ------------------------------------ To display elements conditionally based on user permissions, use the securityIsGranted function in Twig templates. The securityIsGranted function checks if the current user has the specified permission and returns a boolean value indicating whether the permission is granted or not. From 6da049353b548479c603234d7b49011665de490c Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:04:51 -0300 Subject: [PATCH 6/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index a31ff708..adc7dc23 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -8,7 +8,7 @@ This approach enhances security and provides a tailored experience for each User Using the ``securityIsGranted`` function ------------------------------------ -To display elements conditionally based on user permissions, use the securityIsGranted function in Twig templates. The securityIsGranted function checks if the current user has the specified permission and returns a boolean value indicating whether the permission is granted or not. +To display elements conditionally based on User permissions, use the ``securityIsGranted`` function in Twig templates. The ``securityIsGranted`` function checks if the current User has the specified permission and returns a boolean value indicating whether the permission is granted or not. Here's the basic syntax: From 5c1b5051cbba3521245ff07cf22b2d91162dac2d Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:05:07 -0300 Subject: [PATCH 7/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index adc7dc23..66dd1ab4 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -92,7 +92,7 @@ Map the permission keys from the UserPermissions class to the corresponding perm - editusername => user:profile:editusername - editemail => user:profile:editemail -- editposition => user:profile:editposition +- ``editposition`` => ``user:profile:editposition`` - editname => user:profile:editname - full => user:profile:full From e2f1a69b1fbaa495ba42c0f088a311bb1f81b698 Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:05:17 -0300 Subject: [PATCH 8/9] Update docs/design/displaying_elements_based_on_user_permissions.rst Co-authored-by: Ruth Cheesley --- docs/design/displaying_elements_based_on_user_permissions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index 66dd1ab4..c0f52753 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -93,7 +93,7 @@ Map the permission keys from the UserPermissions class to the corresponding perm - editusername => user:profile:editusername - editemail => user:profile:editemail - ``editposition`` => ``user:profile:editposition`` -- editname => user:profile:editname +- ``editname`` => ``user:profile:editname`` - full => user:profile:full In each if statement, the securityIsGranted function is used with the corresponding permission string. If the current user has the specified permission, the code inside the if block will be executed, displaying the relevant form fields for editing the user profile information. From 93f828fcbf8556b0f35429a32f9cb45dc48a80e7 Mon Sep 17 00:00:00 2001 From: "Anderson, from Dropsolid" <116097999+andersonjeccel@users.noreply.github.com> Date: Thu, 24 Oct 2024 10:08:15 -0300 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Ruth Cheesley --- ...ing_elements_based_on_user_permissions.rst | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/design/displaying_elements_based_on_user_permissions.rst b/docs/design/displaying_elements_based_on_user_permissions.rst index c0f52753..44eb8bb8 100644 --- a/docs/design/displaying_elements_based_on_user_permissions.rst +++ b/docs/design/displaying_elements_based_on_user_permissions.rst @@ -18,14 +18,14 @@ Here's the basic syntax: {% endif %} -In this structure, 'permission:string' represents the specific permission being checked for. Mautic uses a hierarchical permission system, in the format of 'bundle:level:permission'. +In this structure, ``permission:string`` represents the specific permission being checked for. Mautic uses a hierarchical permission system, in the format of ``bundle:level:permission``. -Displaying a user invitation link as example +Displaying a User invitation link as example -------------------------------------------- -Let's examine a practical example of how to use this function to display a link for inviting new users to the platform. This link should only be visible to users who have the permission to create new user accounts. + Let's examine a practical example of how to use this function to display a link for inviting new Users to the platform. This link should only be visible to Users who have the permission to create new User accounts. -In this example, we're using the securityIsGranted function to check if the current user has the 'user:users:create' permission. This permission string is structured to indicate that we're checking for the ability to create new users within the user management system. +In this example, we're using the ``securityIsGranted`` function to check if the current User has the ``user:users:create`` permission. This permission string is structured to indicate that we're checking for the ability to create new Users within the User management system. .. code-block:: twig @@ -38,9 +38,9 @@ In this example, we're using the securityIsGranted function to check if the curr {% endif %} -If the current user has the user:users:create permission, the code inside the if block will be rendered, displaying the link to invite new users. The link is created using the path function, which generates a URL based on the specified route (mautic_user_action) and any additional parameters ({objectAction: 'new'}). +If the current User has the ``user:users:create`` permission, the code inside the if block is rendered, displaying the link to invite new users. The path function creates the link, which generates a URL based on the specified route (``mautic_user_action```) and any additional parameters (``{objectAction: 'new'}``). -The 'mautic.user.profile.invite'|trans expression is used to translate the text "Invite your team" using Mautic's translation system. This ensures that the text is displayed in the appropriate language based on the user's locale settings. +The ``'mautic.user.profile.invite'|trans`` expression is used to translate the text 'Invite your team' using Mautic's translation system. This ensures that the text is displayed in the appropriate language based on the user's locale settings. This not only prevents unauthorized access but also keeps the interface clean and relevant for each user's role. @@ -51,26 +51,26 @@ Locating defined permissions Mautic organizes its permissions on a per-bundle basis. Each bundle typically defines its own set of permissions in a dedicated PHP file. The standard location for these permission definitions is: -[BundleName]/Security/[BundleName]Permissions.php +``[BundleName]/Security/[BundleName]Permissions.php`` For example: -- User permissions: UserBundle/Security/UserPermissions.php -- Email permissions: EmailBundle/Security/EmailPermissions.php -- SMS permissions: SmsBundle/Security/SmsPermissions.php +- User permissions: ``UserBundle/Security/UserPermissions.php`` +- Email permissions: ``EmailBundle/Security/EmailPermissions.php`` +- SMS permissions: ``SmsBundle/Security/SmsPermissions.php`` -These PHP files contain classes that extend AbstractPermissions and define the specific permissions available for that bundle. They usually include methods for building the permission matrix and checking individual permissions. +These PHP files contain classes that extend ``AbstractPermissions`` and define the specific permissions available for that bundle. They usually include methods for building the permission matrix and checking individual permissions. Examining permission files -------------------------- When opening one of these permission files, they'll typically find: -- A definePermissions method that outlines all available permissions for the bundle. -- Constants defining permission levels (e.g., LEVEL_VIEW, LEVEL_EDIT, LEVEL_FULL). -- Methods for checking specific permissions (e.g., canViewUsers, canEditEmails). +- A ``definePermissions`` method that outlines all available permissions for the bundle. +- Constants defining permission levels (for example, ``LEVEL_VIEW, LEVEL_EDIT, LEVEL_FULL``). +- Methods for checking specific permissions (for example, ``canViewUsers``, ``canEditEmails``). -For example, in the UserPermissions.php file, the UserPermissions class defines the available permissions for the UserBundle using a more structured approach. Let's go through the important parts: +For example, in the ``UserPermissions.php`` file, the ``UserPermissions`` class defines the available permissions for the ``UserBundle`` using a more structured approach. Let's go through the important parts: .. code-block:: php @@ -86,16 +86,16 @@ For example, in the UserPermissions.php file, the UserPermissions class defines In this example, the profile key represents the permission category, and the nested array defines the specific permission levels for actions like editing the username, email, position, name, and having full access to the user profile. -To use these permission keys with the securityIsGranted function in Twig templates, construct the appropriate permission string. The permission string follows the format: [bundle]:[level]:[permission]. +To use these permission keys with the ``securityIsGranted`` function in Twig templates, construct the appropriate permission string. The permission string follows the format: ``[bundle]:[level]:[permission]``. Map the permission keys from the UserPermissions class to the corresponding permission strings: -- editusername => user:profile:editusername -- editemail => user:profile:editemail +- ``editusername`` => ``user:profile:editusername`` +- ``editemail`` => ``user:profile:editemail`` - ``editposition`` => ``user:profile:editposition`` - ``editname`` => ``user:profile:editname`` -- full => user:profile:full +- ``full`` => ``user:profile:full`` -In each if statement, the securityIsGranted function is used with the corresponding permission string. If the current user has the specified permission, the code inside the if block will be executed, displaying the relevant form fields for editing the user profile information. +In each if statement, the ``securityIsGranted`` function is used with the corresponding permission string. If the current user has the specified permission, the code inside the if block will be executed, displaying the relevant form fields for editing the user profile information. For more information, refer to the Security documentation. \ No newline at end of file