Утилиты
=======

AS.FORMS.ApiUtils
~~~~~~~~~~~~~~~~~

.. js:class:: AS.FORMS.ApiUtils

    Утилиты для работы с REST API Synergy

    .. note:: При использовании данных методов адрес и порт Synergy, а также
              параметры авторизации определяются при подключении проигрывателя форм.
              Методы являются оберткой над `jQuery.ajax() <http://api.jquery.com/jquery.ajax/>`_
              и обладают всеми его свойствами.

    .. js:function:: simpleAsyncGet(urlPart[, callback[, dataType[, data[, errorHandler]]]])

        Выполнить GET запрос по указанному URL REST API.

        :param String urlPart:        Часть URL метода REST API, без ``http://host:port/Synergy/``,
                                      например ``rest/api/registry/create_doc?registryCode=someregistry``
        :param function callback:     Функция, которая будет вызвана в случае успешного выполнения запроса.
                                      В данную функцию передается один параметр - ответ на запрос.
        :param String dataType:       ``default:'json'`` Тип данных ответа на запрос.
                                      Может принимать значения: ``"xml"``, ``"html"``, ``"script"``, ``"json"``, ``"jsonp"``, ``"text"``.
                                      Если не передавать параметр, то будет использоваться дефолтное значение ``"json"``.
        :param object data:           Данные запроса. Могут быть строкой, объектом или массивом.
                                      Конвертируются в строку запроса и добавляются к URL.
        :param function errorHandler: Функция, которая будет вызвана в случае неуспешного выполнения запроса.

        :returns Object:             Объект, содержащий Promise объект, который используется для отслеживания асинхронных вызовов.

                                      С помощью него можно строить цепочки вызовов.

                                      Например так:

                                      .. code-block:: js

                                            jQuery.when(AS.FORMS.ApiUtils.get("url"))
                                                .then(function(result){
                                                    //do something
                                                    return AS.FORMS.ApiUtils.get("url2")
                                                }).then(function(result){
                                                    //do something
                                                }).fail(function(error){
                                                    // любая ошикаб которая произойдет во
                                                    // время выполнения будет обработана здесь
                                                });


                                      Или ждать результаты выполнения нескольких запросов.

                                      .. code-block:: js

                                             jQuery.when(AS.FORMS.ApiUtils.get("url"),
                                                        AS.FORMS.ApiUtils.get("url1"),
                                                        AS.FORMS.ApiUtils.get("url2"))
                                                 .then(function(result1, result2, result3){
                                                     //do something
                                                 }).fail(function(error){
                                                     // любая ошикаб которая произойдет во
                                                     // время выполнения будет обработана здесь
                                                 });

    .. js:function:: simpleAsyncPost(urlPart[, callback[, dataType[, data[, contentType[, errorHandler]]]]])

        Выполнить POST запрос по указанному URL REST API.

        :param String urlPart:        Часть URL метода REST API, без ``http://host:port/Synergy/``,
                                      например ``rest/api/asforms/data/save``
        :param function callback:     Функция, которая будет вызвана в случае успешного выполнения запроса.
                                      В данную функцию передается один параметр - ответ на запрос.
        :param String dataType:       ``default:'json'`` Тип данных ответа на запрос.
                                      Может принимать значения: ``"xml"``, ``"html"``, ``"script"``, ``"json"``, ``"jsonp"``, ``"text"``.
        :param object data:           Данные запроса. Должны соответствовать параметру ``contentType``
        :param String contentType:    ``default:'application/x-www-form-urlencoded; charset=UTF-8'`` Тип данных запроса.
        :param function errorHandler: Функция, которая будет вызвана в случае неуспешного выполнения запроса.

        :returns Object:             Объект, содержащий Promise объект, который используется для отслеживания асинхронных вызовов.

                                      .. note:: подробнее об этом написано в документации к методу ``simpleAsyncGet``