API документация
=================


Настройка прав доступа по URL
````````````````````````````````

Следует различать несколько видов URL, отличающихся доступностью:
    * открытый - URL  доступный всем без авторизации;
    * закрытый - URL  доступный только авторизованным пользователям;
    * ограниченный  - URL  доступный только авторизованным пользователям, с определенными ролями.

Для создания URL с закрытым вариантом доступа требуется указать специальный декоратор перед определением обработчика URL.

Специальный декоратор можно получить с помощью функции get_auth_decorator из API приложения (модуль app_api в корне приложения).

Пример кода обработчика URL::

    _auth_decorator = app_api.get_auth_decorator()

    @mod.route('/test/handler', methods=['GET'])
    @_auth_decorator
    def test_handler():
        """
        Тело обработчика
        """
        return ''

Для создания  URL с ограниченным вариантом доступа помимо использования специального декоратора, как в закрытом варианте, требуется указать роль(роли) для которых будет доступен данный URL.

Указать перечень ролей для доступа к определенному URL возможно только в dublin.ttl с помощью отношения ``splm:isAvailableFor``, например:
``splm:mod_url splm:isAvailableFor “role”``.
где splm:mod_url -  URL  модуля для которого требуется предоставить для определенной роли, а “role”  наименование роли которой требуется предоставить доступ (возможность получить ответ от сервера по указанному URL).
Для предоставления доступа к URL больше чем одной роли требуется повторить запись по количеству ролей в dublin.ttl.

Важно! При отрисовке страницы вывод элементов навигации учитывает роли, указанные для URL и отображает только те элементы, которые доступны текущему пользователю на основании ролей.

.. caution::
    Проверка на соответствие ролей для URL с ролями назначенными текущему пользователю находится в зоне ответственности разработчика обработчика URL.


Пример кода проверки ролей текущего пользователя::

    if g.user:
        if g.user.has_role('role'):
::



Событийная модель в SPLM
````````````````````````````````

SPLM поддерживает функционал регистрации и обработки событий - ``EventManager``.

..  autoclass:: app.utilites.event_manager.EventManager
    :members:
    :show-inheritance:



Для регистрирации события необходимо задать параметры:
    * ``event_name`` - название события
    * ``handler`` - функцию-обработчик, которая будет вызвана при отработке события

Функция-обработчик принимает два аргумента:
    * ``event`` - экземпляр события
    * ``data`` - данные, переданные обработчику в момент возникновения события.
и возвращает переменную data в том же виде, в котором она была получена.


Для отработки события передать параметры:
    * ``event_name`` - название события
    * ``data`` - данные, которые будут переданы обработчику

Все очень просто!


``````
Пример:
``````

Для начала зарегистрируем наше событие с именем ``"event_test"`` и обработчиком ``event_test_hadler()``

Получаем экземпляр ``EventManager``::

    from app.app_api import get_event_manager
    event_manager = get_event_manager()
::

Описываем обработчик и регистрируем событие::

    def event_test_hadler(event, data):
        ....
        return data

    event_manager.register_event("event_test", event_test_hadler)
::

С этого момента будет запущен процесс, который слушает наше событие.


В случае регистрации нескольких обработчиков на одно событие они будут выполняться последовательно в том порядке, в котором были зарегистрированы. Результат предыдущего обработчика передается на вход следующему.

При возникновении ошибки (ошибка исполнения кода) при выполнении обработчика цепочка выполнения не прерывается. Входные данные для обработчика с ошибкой (ошибка исполнения кода) передаются следующему в очереди обработчику.


Теперь, чтобы наше событие ``"event_test"`` отработало, вызовем его, передав параметры ``params`` для функции-обработчика ``event_test_hadler()``.

Здесь ``data`` - это результат работы обработчика::

    data = event_manager.raise_event("event_test", params)
::

Все. Теперь при отработке метода ``raise_event`` возникнет событие ``"event_test"`` и будет вызвана функция-обработчик ``event_test_hadler()``.