Filter role functions
---------------------

.. index:: Macro function;fn.filter_roles_by_user_access_profile

Given a list of user roles as a function parameter, the 
``fn.filter_roles_by_user_access_profile`` function returns the
list of roles with permissions equal to or less than
that of the user executing the function.


For example, given a list of roles: 

::

   macro.ALL_Roles 

   [TestRole01, TestRole02, TestRole03]

where ``TestRole01`` has the least permissions and ``TestRole03`` has the most permissions.
If the request user is assigned with ``TestRole02``, and executes the following macro:

::

   {{ fn.filter_roles_by_user_access_profile macro.ALL_Roles }}

The output of this macro will be

::

   [TestRole01, TestRole02]


.. note::

   This filter will only have an effect if the setting in ``data/Settings``
   called Additional Role Access Profile Validation is enabled (check box is enabled).

   Refer to the *Additional role access profile validation* settings topic.