Settings
========

The application can be configured via settings with ``GROUPS_MANAGER`` dictionary.
Valid keys and values are described below.

Auth model synchronization
--------------------------

- ``"AUTH_MODELS_SYNC"``: enables Group, Member and GroupMember synchronization with django's Group and User (default: ``False``);
- ``"AUTH_MODELS_GET_OR_CREATE"``: use ``get_or_create`` method instead of ``create`` for django's Group and User models when associating to Group or Member (default: ``True``);
- ``"GROUP_NAME_PREFIX"``: prefix used for autogenerated django Group's name (default: ``"DGN_"``)
- ``"GROUP_NAME_SUFFIX"``: suffix used for autogenerated django Group's name. The special value ``"_$$random"`` can be used for generate a pseudo-unique suffix of length 8 (the first block of an UUID4) (default: ``"_$$random"``)
- ``"USER_USERNAME_PREFIX"``: prefix used for autogenerated django User's username (default: ``"DGN_"``)
- ``"USER_USERNAME_SUFFIX"``: suffix used for autogenerated django User's username. The special value ``"_$$random"`` can be used (default: ``"_$$random"``)

Permissions
-----------

- ``"PERMISSIONS"`` dictionary: this setting controls the ``assign_object`` method of a ``GroupMember`` instance.
   Each key controls a specific group type. Values are lists (or, in case of ``"owner"``, also a dictionary) with a combination of permissions' prefixes ``"view"`` (view), ``"change"`` (change), ``"delete"`` (delete) characters. Obviously, a ``"view_modelname"`` permission must be added to the model permissions. You can also add your custom permissions in form of ``<prefix>`` where your permission is ``<prefix>_modelname``.

Valid keys are:

	- ``"owner"``: a list or a dictionary (with keys as roles' codename attribute). This object-permissions are assigned directly to the user (default: ``['view', 'change', 'delete']``)
	- ``"group"``: a string. This object-permissions are assigned to the related group (default: ``['view', 'change']``)
	- ``"groups_upstream"``: a string. This object-permissions are assigned to the ancestors groups (default: ``['view']``)
	- ``"groups_downstream"``: a string. This object-permissions are assigned to the descendants groups (default: ``[]``)
	- ``"groups_siblings"``: a string. This object-permissions are assigned to the siblings groups (default: ``['view']``)

.. _permission-name-policy:

.. note::
   The four special permission names ``"add"``, ``"view"``, ``"change"``,  and ``"delete"`` are translated to ``<permission>_<model_name>`` string during permission's name lookup.
   This allows to use a standard permission policy (*view*, *change*, *delete*) but also allows to use :ref:`custom permissions <custom-permissions-by-role>`.

An example of permissions assigned by role can be found on use cases.

Defaults
--------

Default values are::

    GROUPS_MANAGER = {
        # User and Groups sync settings
        'AUTH_MODELS_SYNC': False,
        'GROUP_NAME_PREFIX': 'DGM_',
        'GROUP_NAME_SUFFIX': '_$$random',
        'USER_USERNAME_PREFIX': 'DGM_',
        'USER_USERNAME_SUFFIX': '_$$random',
        # Permissions
        'PERMISSIONS': {
            'owner': ['view', 'change', 'delete'],
            'group': ['view', 'change'],
            'groups_upstream': ['view'],
            'groups_downstream': [],
            'groups_siblings': ['view'],
        },
    }
