Heading fixes, vale fixes.

Author: RCheesley

docs/design/displaying_elements_based_on_user_permissions.rst

@@ -1,14 +1,14 @@
 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
-------------------------------------
+****************************************
 
-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 User has the permission granted or not.
 
 Here's the basic syntax:
 
@@ -18,14 +18,14 @@ Here's the basic syntax:
        <!-- Content to display if the user has the specified permission -->
    {% 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 permission to verify. 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.
+Here's 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, the ``securityIsGranted`` function verifies if the current User has the ``user:users:create`` permission. The structure of the permission string verifies if the User has the ability to create new Users within the User management system.
 
 .. code-block:: twig
 
@@ -38,16 +38,16 @@ In this example, we're using the ``securityIsGranted`` function to check if the
        </li>
    {% endif %}
 
-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'}``).
+If the current User has the ``user:users:create`` permission, the code inside the if block renders, 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.
 
-This not only prevents unauthorized access but also keeps the interface clean and relevant for each user's role.
+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.
+When implementing permission-based displays, it's also essential to secure the backend routes and actions that these interface elements might trigger. The frontend permission verification must be 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:
 
@@ -62,15 +62,15 @@ For example:
 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 (for example, ``LEVEL_VIEW, LEVEL_EDIT, LEVEL_FULL``).
-- Methods for checking specific permissions (for example, ``canViewUsers``, ``canEditEmails``).
+- 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. Here are the important parts:
 
 .. code-block:: php
 
@@ -84,7 +84,7 @@ For example, in the ``UserPermissions.php`` file, the ``UserPermissions`` class
        ],
    ];
 
-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.
+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]``.
 
@@ -96,6 +96,6 @@ Map the permission keys from the UserPermissions class to the corresponding perm
 - ``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.
+In each if statement, you pair the ``securityIsGranted`` function with the corresponding permission string. If the current User has the specified permission, the code inside the if block runs, displaying the relevant Form Fields for editing the User profile information.
 
 For more information, refer to the Security documentation.