-

docs/extcmp.rst

 Внешние модули-компоненты (ВМК)
 ===============================
 
-Интеграция с помощью внешнего-модуля компонента предназначена для добавления
+Механизм внешнего-модуля компонента предназначена для добавления
 или замены каких-либо элементов пользовательского web-интерфейса ARTA Synergy.
 Для этого необходимо описать пользовательский компонент, который и будет
 служить внешним модулем-компонентом, а затем указать для него место размещения
-и способ вставки.
+в интерфейсе (GUI) и способ вставки.
 
 Добавление ВМК
 --------------
 
-Для настройки пользовательских компонентов методологу нужно во вкладке
+Для настройки пользовательских компонентов необходимо во вкладке
 "Процессы" конфигуратора выбрать пункт "Пользовательские компоненты".
 
-![Пользовательские компоненты](resources/img/integration/user-component.png)
+.. figure:: _static/img/extcmp/extcmp-1.png
+
+    Пользовательские компоненты
 
 Настройка пользовательских компонентов включает в себя настройку следующих
 полей:
 
-*   "Название" - название пользовательского компонента, является обязательным
-    полем;
-
-*   "Исходный код" - код компонента, написанный на `HTML/CSS`. Можно также
-    добавить сюда и код на `javascript`, но делать этого не рекомендуется,
-    т.к. для `js` вызывать функции отсюда будет сложнее. Для написания
-    скрипта следует использовать поле "Исходный код скрипта";
-
-*   "Исходный код скрипта" - код скрипта, написанный на `javascript`, с
-    помощью которого можно настроить содержимое компонента, обратившись
-    к существующим в системе API, описание которых можно посмотреть в
-    [javadoc](../javadoc) и воспользовавшись возможностью обработать
-    необходимые клиентские события. Для этого нужно вызвать функцию
-    `$EVENT_BUS.subscribe()` и указать ей в качестве параметров необходимое
-    событие и функцию, которую это событие обрабатывает.
-
-    > `$EVENT_BUS.subscribe(new EventHandler`
-    > `('WORK_USERS_CHANGED', handlerUsersSelected));`
-
-    Также объект `EVENT_BUS` позволяет отписываться от событий и создавать
-    новые. Для возможности указания новых событий необходимо обратиться
-    к центру решений.
-
-.. warning::  Начиная с версии Synergy 3.14, все пользовательские скрипты
-              выполняются с добавлением директивы `use strict`. Эта директива
-              означает, что соответствующий ей код будет выполнятся в так
-              называемом **"строгом режиме"**, поддерживающем стандарт `JavaScript`
-              `ECMAScript5 <http://www.ecma-international.org/publications/standards/Ecma-262.htm>`_.
-
->> **Примечание:**
-
->> Если код скрипта содержит конструкции, не соответствующие стандарту ES5,
-то они не будут выполняться. Это не является ошибкой Synergy.
-
-**Использование пользовательских компонентов как полей формы**
-
-В общем случае пользовательские компоненты не участвуют в местах,
-где могут использоваться какие-либо другие компоненты формы:
-
--   отсутствует в полях формы реестра;
-
--   отсутствует в фильтрах реестра;
-
--   не учитывается при поиске в реестре;
-
--   не участвует в сортировке реестра;
-
--   отсутствует во всех видах сопоставлений;
-
--   не учитывается во всех спец.процессах (например, в условном
-переходе).
-
-Для того, чтобы пользователький компонент присутствовал в
-сопоставлениях, необходимо, чтобы в его модели были реализованы
-методы `setAsfData` и `getAsfData` (см.
-["Создание нового компонента"](#integration.methods.form_scripting.new_user_component)),
-а также чтобы возвращалась структура компонента вида:
-
-```
-{
-    "id": "id",
-    "type": "type",
-    "value": "value",
-    "key": "key"
-}
-```
-
-Для снятия остальных ограничений достаточно реализации метода
-`getAsfData` и корректности возвращаемой структуры.
+* **"Название"** - название пользовательского компонента, является обязательным
+  полем;
+* **"Код"** - название пользовательского компонента, является обязательным
+  полем;
+* **"Использовать в формах"** - данная опция позволяет использовать компонент
+  в формах (в качестве пользовательского компонента);
+* **"HTML код"** - HTML код(в том числе CSS), который будет вставлен в страницу
+  ARTA Synergy;
+* **"JAVASCRIPT код"** - основной код компонента на JavaScript, который будет
+  вставлен в страницу ARTA Synergy.
+
+.. attention::  Начиная с версии Synergy 3.14, все пользовательские скрипты
+                выполняются с добавлением директивы `use strict`. Эта директива
+                означает, что соответствующий ей код будет выполнятся в так
+                называемом **"строгом режиме"**, поддерживающем стандарт JavaScript
+                `ECMAScript5 <http://www.ecma-international.org/publications/standards/Ecma-262.htm>`_.
+
+.. warning::    Если код скрипта содержит конструкции, не соответствующие стандарту ES5,
+                то они не будут выполняться. Это не является ошибкой Synergy.
 
 **Пример:**
 
-В качестве примера расмотрим реализацию пользовательского компонента "Load info",
+В качестве примера рассмотрим реализацию пользовательского компонента "Load info",
 который показывает перегруженных сотрудников при создании работы (данный
 компонент входит в стандартную поставку Synergy).
 
-Итерационные задачи по реализации:
-[0193: Компонент предупреждение о перегрузке](../../../../additional/statements/2/html/t0193.html)
-
 Исходный код содержит следующий простой `HTML` код:
 
-```xml
-<!-- Определим добавляемый элемент, указав для него необходимый стиль. -->
-<span id = "workloadLable" style="color:red; padding-top: 10px"> </span>
-<!-- За содержимое элемента будет отвечать исходный код скрипта.       -->
-```
+.. code-block:: xml
 
-Исходный код скрипта устроен более сложным образом. Рассмотрим реализацию
-функции получающей данные из `api`:
+    <!-- Определим добавляемый элемент, указав для него необходимый стиль. -->
+    <span id = "workloadLable" style="color:red; padding-top: 10px"> </span>
+    <!-- За содержимое элемента будет отвечать исходный код скрипта.       -->
 
-```javascript
-function ajaxUserWL(ar){
-    // Функция filtrAr() исключает из массива повторения пользователей.
-    ar = filtreAr(ar);
-
-    // Используем массив, который подходит под формат `json`, определенный в `api`.
-    // Данный формат необходимо всегда уточнять в javadoc.
-    var req = [];
-    for (var i = 0; i < ar.length; i++){
-        var r = {userID: ar[i].userId,
-            startDate: getCurrentDateFormated(),
-            finishDate: getCurrentDateFormated()};
-        req.push(r);
-    }
 
-    // Вызываем функцию, которая для пользователей из массива req, вызовет
-    // api, возвращающую их загруженность. Перегруженные пользователи
-    // добавляются в массив res и формируют содержимое HTML тага.
-    jQuery.ajax({
-
-        // Вызов необходимого api.
-        url: 'rest/person/workload/m',
-        type: 'post',
-        data: JSON.stringify(req),
-        contentType: 'application/json',
-        dataType: 'json',
-
-        // Функция осуществляет проверку на перегруженность и помещает таких
-        // сотрудников в массив res
-        success: function (data) {
-            res = [];
-            for (var i = 0; i < ar.length; i++) {
-                var user = data[ar[i].userId];
-                if (user == null) {
-                    continue;
-                }
-                for (var j = 0; j < user.length; j++) {
+Исходный код скрипта устроен более сложным образом. Рассмотрим реализацию
+функции получающей данные посредством вызова REST API:
+
+.. code-block:: javascript
+
+    function ajaxUserWL(ar){
+        // Функция filtrAr() исключает из массива повторения пользователей.
+        ar = filtreAr(ar);
+
+        // Используем массив, который подходит под формат `json`, определенный в `api`.
+        // Данный формат необходимо всегда уточнять в javadoc.
+        var req = [];
+        for (var i = 0; i < ar.length; i++){
+            var r = {userID: ar[i].userId,
+                startDate: getCurrentDateFormated(),
+                finishDate: getCurrentDateFormated()};
+            req.push(r);
+        }
 
-                    // Проверка на перегруженность.
-                    if (parseFloat(user[j].value) > 100) {
-                        res.push(ar[i]);
+        // Вызываем функцию, которая для пользователей из массива req, вызовет
+        // api, возвращающую их загруженность. Перегруженные пользователи
+        // добавляются в массив res и формируют содержимое HTML тага.
+        jQuery.ajax({
+
+            // Вызов необходимого api.
+            url: 'rest/person/workload/m',
+            type: 'post',
+            data: JSON.stringify(req),
+            contentType: 'application/json',
+            dataType: 'json',
+
+            // Функция осуществляет проверку на перегруженность и помещает таких
+            // сотрудников в массив res
+            success: function (data) {
+                res = [];
+                for (var i = 0; i < ar.length; i++) {
+                    var user = data[ar[i].userId];
+                    if (user == null) {
+                        continue;
                     }
-                }
-            }
+                    for (var j = 0; j < user.length; j++) {
 
-            // Функция определяет формат, в котором будет выводиться инофрмация.
-            overloadUsers(res);
-        }
-    });
-}
-```
+                        // Проверка на перегруженность.
+                        if (parseFloat(user[j].value) > 100) {
+                            res.push(ar[i]);
+                        }
+                    }
+                }
 
-Итерационные задачи по реализации:
-[0195: API получения нагрузки](../../../../additional/statements/2/html/t0195.html)
+                // Функция определяет формат, в котором будет выводиться инофрмация.
+                overloadUsers(res);
+            }
+        });
+    }
 
-**Замечание:**
 
-> Полную реализацию компонента можно посмотреть в настройках пользовательских
-> компонентов, выбрав компонент "Load info".
+.. note:: Полную реализацию компонента можно посмотреть в настройках пользовательских
+          компонентов, выбрав компонент "Load info".
 
-**Замечание:**
+.. **Замечание:**
 
-> Для API, находящихся по `URL` rest/%api/method%, авторизация будет происходить
-> по куки (как в браузере), поэтому его можно вызывать авторизованному в Synergy
-> пользователю. Для API, находящихся по другим адресам `URL`, необходимо
-> настроить процесс авторизации (см. [Способы авторизации](#integration.auth)).
-> Сделать это можно например так: вызвать API по адресу
-> `https://%логин%:%пароль%@%адрес/метода/api%`
+    Для API, находящихся по `URL` rest/%api/method%, авторизация будет происходить
+    по куки (как в браузере), поэтому его можно вызывать авторизованному в Synergy
+    пользователю. Для API, находящихся по другим адресам `URL`, необходимо
+    настроить процесс авторизации (см. [Способы авторизации](#integration.auth)).
+    Сделать это можно например так: вызвать API по адресу
+    `https://%логин%:%пароль%@%адрес/метода/api%`
 
-Для того, чтобы выбрать, где использовать пользовательский компонент, методологу
+Для того, чтобы выбрать, где использовать пользовательский компонент,
 необходимо во вкладке "Процессы" выбрать пункт "Внешние модули-компоненты"
 и добавить новый внешний модуль-компонент.
 
-![Внешние модули-компоненты](resources/img/integration/vmk.png)
+.. figure:: _static/img/extcmp/extcmp-2.png
+
+    Внешние модули-компоненты
 
 Настройка внешнего модуля-компонента включает в себя настройку следующих полей:
 
@@ -189,8 +137,8 @@ function ajaxUserWL(ar){
     полем;
 
 *   "Место размещения" - выбрать один из доступных вариантов для указания
-места, в котором будет находиться пользовательский компонент. На данный
-момент доступны следующие альтернативы:
+    места, в котором будет находиться пользовательский компонент. На данный
+    момент доступны следующие альтернативы:
     +   "onLoad" - пользовательский компонент будет выводиться при загрузке
     приложения;
     +   "Depricated" - место, используемое для вывода пользовательских
@@ -213,7 +161,8 @@ function ajaxUserWL(ar){
     помещается пользовательский тег (замена всех потомков тега места размещения).
 
 
-#### События для ВМК {#integration.methods.user-component.events}
+События для ВМК
+---------------
 
 Для работы ВМК в Synergy реализована отправка событий в JS EventBus.