-

docs/extcmp.rst

+Внешние модули-компоненты (ВМК)
+===============================
+
+Интеграция с помощью внешнего-модуля компонента предназначена для добавления
+или замены каких-либо элементов пользовательского web-интерфейса ARTA Synergy.
+Для этого необходимо описать пользовательский компонент, который и будет
+служить внешним модулем-компонентом, а затем указать для него место размещения
+и способ вставки.
+
+Добавление ВМК
+--------------
+
+Для настройки пользовательских компонентов методологу нужно во вкладке
+"Процессы" конфигуратора выбрать пункт "Пользовательские компоненты".
+
+![Пользовательские компоненты](resources/img/integration/user-component.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` и корректности возвращаемой структуры.
+
+**Пример:**
+
+В качестве примера расмотрим реализацию пользовательского компонента "Load info",
+который показывает перегруженных сотрудников при создании работы (данный
+компонент входит в стандартную поставку Synergy).
+
+Итерационные задачи по реализации:
+[0193: Компонент предупреждение о перегрузке](../../../../additional/statements/2/html/t0193.html)
+
+Исходный код содержит следующий простой `HTML` код:
+
+```xml
+<!-- Определим добавляемый элемент, указав для него необходимый стиль. -->
+<span id = "workloadLable" style="color:red; padding-top: 10px"> </span>
+<!-- За содержимое элемента будет отвечать исходный код скрипта.       -->
+```
+
+Исходный код скрипта устроен более сложным образом. Рассмотрим реализацию
+функции получающей данные из `api`:
+
+```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++) {
+
+                    // Проверка на перегруженность.
+                    if (parseFloat(user[j].value) > 100) {
+                        res.push(ar[i]);
+                    }
+                }
+            }
+
+            // Функция определяет формат, в котором будет выводиться инофрмация.
+            overloadUsers(res);
+        }
+    });
+}
+```
+
+Итерационные задачи по реализации:
+[0195: API получения нагрузки](../../../../additional/statements/2/html/t0195.html)
+
+**Замечание:**
+
+> Полную реализацию компонента можно посмотреть в настройках пользовательских
+> компонентов, выбрав компонент "Load info".
+
+**Замечание:**
+
+> Для API, находящихся по `URL` rest/%api/method%, авторизация будет происходить
+> по куки (как в браузере), поэтому его можно вызывать авторизованному в Synergy
+> пользователю. Для API, находящихся по другим адресам `URL`, необходимо
+> настроить процесс авторизации (см. [Способы авторизации](#integration.auth)).
+> Сделать это можно например так: вызвать API по адресу
+> `https://%логин%:%пароль%@%адрес/метода/api%`
+
+Для того, чтобы выбрать, где использовать пользовательский компонент, методологу
+необходимо во вкладке "Процессы" выбрать пункт "Внешние модули-компоненты"
+и добавить новый внешний модуль-компонент.
+
+![Внешние модули-компоненты](resources/img/integration/vmk.png)
+
+Настройка внешнего модуля-компонента включает в себя настройку следующих полей:
+
+*   "Название" - название внешнего модуля-компонента, является обязательным
+    полем;
+
+*   "Место размещения" - выбрать один из доступных вариантов для указания
+места, в котором будет находиться пользовательский компонент. На данный
+момент доступны следующие альтернативы:
+    +   "onLoad" - пользовательский компонент будет выводиться при загрузке
+    приложения;
+    +   "Depricated" - место, используемое для вывода пользовательских
+    компонентов в старых версиях, не рекомендуется к применению;
+    +   "BPM/Workflow/Create/Work" - пользовательский компонент будет
+    выводиться в диалоговом окне создания работы;
+    +   "Shell/TopPanel/Right" - пользовательский компонент будет выводиться
+    на верхней панели оболочки Synergy, левее поля "Поиск".
+
+    Для размещения пользовательского компонента в новом месте необходимо
+    его запрашивать у центра решений (в качестве доработки API).
+
+*   "Название пользовательского компонента" - выбрать один из доступных
+    вариантов пользовательских компонентов, настроенных ранее;
+
+*   "Тип вставки" - выбрать один из доступных вариантов:
+    +   "ADD" - добавляет тег пользовательского компонента к тегу места
+    размещения;
+    +   "REPLACE" - удаляются потомки тега места размещения и в него
+    помещается пользовательский тег (замена всех потомков тега места размещения).
+
+
+#### События для ВМК {#integration.methods.user-component.events}
+
+Для работы ВМК в Synergy реализована отправка событий в JS EventBus.
+
+**Пример использования события из нового проигрывателя форм в JS:**
+
+```javascript
+AS.FORMS.bus.on(AS.FORMS.EVENT_TYPE.formShow, function (event, model, view) {
+    var calendarModel = model.getModelWithId('cmp-1'); //Передается идентификатор компонента
+    calendarModel.on(AS.FORMS.EVENT_TYPE.valueChange, function () {
+        var value = calendarModel.getValue();
+        console.log(value);
+    });
+});
+```
+
+Ниже описаны параметры для каждого события.
+
+##### WORK_USERS_CHANGED {#integration.methods.user-component.events.WORK_USERS_CHANGED}
+
+WORK_USERS_CHANGED - изменены исполнители работы в диалоге создания работы.
+
+* в качестве аргумента передается список выбранных пользователей в виде массива JSON с полями: *userId, lastname, firstname, patronymic*
+
+* *добавлено в версии 3.0*
+
+##### WORK_DIALOG_UPDATE {#integration.methods.user-component.events.WORK_DIALOG_UPDATE}
+
+WORK_DIALOG_UPDATE - обновлен диалог создания работы.
+
+* в качестве аргумента передается список выбранных пользователей в виде массива JSON с полями: *userId, lastname, firstname, patronymic*
+
+* *добавлено в версии 3.0*
+
+##### SETTINGS_LOADED {#integration.methods.user-component.events.SETTINGS_LOADED}
+
+SETTINGS_LOADED - загружены настройки приложения.
+
+* в качестве аргумента передается *null*
+
+* *добавлено в версии 3.3*
+
+##### DEPARTMENT_ENTITY_CHANGED {#integration.methods.user-component.events.DEPARTMENT_ENTITY_CHANGED}
+
+DEPARTMENT_ENTITY_CHANGED - подразделение обновлено в компоненте формы.
+
+* в качестве аргумента передается JSON с полями *id* и *values*
+
+* values - массив JSON с полями: *value* - отображаемое имя, *key* - идентификатор пользователя
+
+* *добавлено в версии 3.6*
+
+##### FORM_LOADED {#integration.methods.user-component.events.FORM_LOADED}
+
+FORM_LOADED - компоненты формы прорисованы
+
+* в качестве аргумента передаётся пустой JSON объект с полем dataID.
+
+* *добавлено в версии 3.6*
+
+**Пример использования события в JS:**
+
+```javascript
+$EVENT_BUS.subscribe(new EventHandler('FORM_LOADED', handlerUsersSelected));
+        function handlerUsersSelected(event, args) {
+            console.log("event FORM_LOADED");
+            var component = jQuery('img#image_for_portlet');
+            if (component === null || component.length === 0) {
+                console.log("no success");
+                return;
+            }
+            console.log("success!!");
+            console.log(component.parentNode);
+            console.log(component);
+            var mySpan = document.createElement("div");
+            mySpan.innerHTML = "<div id='portlet_div' ><iframe frameborder = \"0\" height = \"100%\" id = \"portlet1\" src = \"http://192.168.2.119:8080/widget/web/guest/home/-/meetups\" width = \"100%\" > </iframe ></div > ";
+            component.replaceWith(mySpan.innerHTML);
+        }
+            var checkAgain = function() {
+                setTimeout(handlerUsersSelected, 5000);
+            };
+```
+
+##### REGISTRY_SELECTED {#integration.methods.user-component.events.REGISTRY_SELECTED}
+
+REGISTRY_SELECTED - нажата кнопка "Создать", когда в навигаторе выделен активный
+реестр.
+
+* в качестве аргумента передаётся JSON объект вида:
+
+```
+registryCode:"reg_code"
+registryId:"9034810f-5f18-44b9-948a-8f78a5f1ec9d"
+```
+
+* *добавлено в версии 3.14*
+
+Кроме того, атрибуты `registryCode` и `registryId` содержатся в элементе списка реестров,
+например:
+
+```xml
+<table cellspacing="0"
+       cellpadding="0"
+       synergytest="RegistryTreeElement"
+       registryid="82356e07-a859-49cc-8adf-896c32725810"
+       registrycode="Заявление_о_приеме_на_работу_(вариант_2,_на_двух_языках)"
+       style="display: inline;"
+       class="commonLabelBold">
+<colgroup> <col> </colgroup>
+<tbody>
+    <tr>
+        <td>007 Заявление о приеме на работу на период</td>
+        <td style="white-space: nowrap;"></td>
+    </tr>
+</tbody>
+</table>
+```
+
+##### USER_CHOOSER_CREATED {#integration.methods.user-component.events.USER_CHOOSER_CREATED}
+
+USER_CHOOSER_CREATED - обновлено тэговое поле выбора пользователя в диалоге.
+
+* в качестве аргумента передаются два параметра: событие и объект, содержащий ссылку на компонент выбор пользователя (в поле args).
+
+* *добавлено в версии 3.12 Tengri*
+
+**Пример обработчика события добавления компонента выбора пользователя,
+который выводит идентификатор компонента в консоль браузера:**
+
+```javascript
+function onUserChooserCreated(evt, chooser){
+        var id = getUserChooserId(chooser.args);
+        console.log(id);
+}
+```
+
+Оперировать компонентом выбора пользователя можно следующими функциями:
+
+- `getUserChooserId(chooserComponent)` - получение идентификатора компонента
+выбора пользователя;
+
+- `getUserChooserShowAll(chooserComponent)` - получение настройки "Разрешить
+добавлять соисполнителей к работам, не являющихся подчиненными"
+
+- `setUserChooserSelectedIds(chooserComponent, arrayOfUsersIds)` - выбрать
+переданных пользователей;
+
+- `getUserChooserSelectedIds(chooserComponent)` - получить идентификаторы
+выбранных пользователей.
+
+**Идентификаторы компонентов выбора пользователя:**
+
+1. Диалог создания работы создания работы:
+
+	- исполнитель - `editWorkUserChooser`
+
+	- ответственные - `editWorkResponsibleUserChooser`
+
+	- автор - `editWorkAuthorUserChooser`
+
+2. Отправить-> переслать:
+
+	- адресаты - `sendDocumentUserChooser`
+
+3. Отправить -> перепоручить:
+
+	- исполнитель - `assignmentSendUserChooser`
+
+	- ответственные - `assignmentSendResponsibleUserChooser`
+
+4. Отправить на согласование, утверждение, ознакомление:
+
+	- адресаты - `sendWorkUserChooser`
+
+5. Отправить по маршруту:
+
+	- ответственный - `editRouteSendDialog`
+
+6. все остальные компоненты будут иметь идентификатор `userChooser`.
+
+В каждый DOM элемент компонента выбора пользователя добавляется атрибут
+`userchooser` со значением идентификатора компонента выбора пользователя.

docs/index.rst

@@ -15,4 +15,5 @@
    dev_process
    form_scripting
    interpreter
+   extcmp
    dashboards