Синтаксис JS¶

Методы для работы с ДП и основными параметрами задачи¶

В карточке задачи вся бизнес-логика (проверка значений на корректность и т.п.) срабатывает при вызове метода save().

Вставки для работы с ДП оформляются следующим образом:

Без использования jQuery	С использованием jQuery
в карточке задачи:	в карточке задачи:
window.addEventListener(\'MTFMainLoadFinished\', function() { JS-вставка})	\$window.on(\'MTFMainLoadFinished\', function() { JS-вставка });
в карточке новой задачи:	в карточке новой задачи:
window.addEventListener(\'NewTaskLoadFinished\', function() { JS-вставка })	\$window.on(\'NewTaskLoadFinished\', function() { JS-вставка });

ℹ️ При переходе на новый МТФ для работы с карточкой задачи с использованием JS-вставки обязательно должно быть использовано событие MTFMainDestroyed. Для карточки создания новой задачи (НТФ) должно быть использовано событие \'NewTaskLoadFinished\'. Подробнее

ℹ️ В карточке новой задачи методы save() и update() недоступны, т.к. задача еще не существует (нет соответствующей записи в БД).

Если в JS-вставке для карточки задачи или для карточки создания новой задачи привязано событие change(), то callback-функция срабатывает на следующие пользовательские действия:

установка значения через кнопку выбора;
установка автодополнением (когда пользователь набирает в окне ввода часть значения и затем выбирает нужную запись из выпадающего списка, который автоматически предлагает ему система);
установка через .val("abc"), когда значение назначается в самой JS-вставке;
удаление значения с помощью значка удаления;
вызов ep.change().

Обращение к основным параметрам¶

В JS вставках в карточке задачи можно обращаться к номеру задачи — taskId, и статусу задачи — StateID.

ID пользователя, от имени которого ведется работа, доступно в SessionUserID.

ℹ️ Названия основных параметров регистрозависимые

Методы для работы с ДП¶

Метод	Аналог	Что делает
`var ep = new ExtParam(1234)`	`ДП.{Имя_ДП}()` Пример: `ДП.Спринт()`	Получает JS-объект для управления ДП с ID=1234 (обращения к jQuery или к DOM на данном этапе еще не производится, объект находится на стадии формирования)
`ep.get()`		Возвращает jQ-объект, содержащий ДП
`ep.label()`		Возвращает jQ-объект подписи
`ep.label().html()`		Возвращает текст подписи
`ep.label("text")`		Меняет текст подписи к ДП и возвращает jQ-объект
`ep.show()`		Показывает ДП и подпись и возвращает объект управления
`ep.hide()`		Скрывает ДП и подпись, а также и возвращает объект управления

ℹ️ При использовании ep.hide() в разметке страницы останется пустое пространство, хотя сам ДП отображаться не будет. Если вам необходимо скрыть ДП, не оставляя пустого места, используйте css-селектор со свойством display: none.

Метод	Аналог	Что делает
`ep.val()`	`Значение()`	Получает значение ДП
`ep.textVal();`	`ТекстовоеЗначение()`	Получает значение ДП в текстовом виде. Пример результата для ДП "Lookup": `'{"taskId":1507666,"taskText":"текс задачи","taskColor":"Grey","taskIcon":"task-list-document-text"}'`
`ep.val(param)`	`{Имя_ДП}.Значение()` Пример: `Спринт.Значение()`	Устанавливает значение ДП, вызывает событие change. Пример для ДП "Выпадающий список": `ep.val(val({name:'Выпсписокjs', value:'1'}))` Параметр "name" является опциональным. Пример для ДП "Lookup": `ep.val(val({taskId: 1234, taskText:'text'}))`
`ep.getAvailableValues(handler)`	`ВозможныеЗначения()`	Получает список возможных значений ДП Lookup и Multilookup. handler — метод, принимающий массив элементов типа { text, value }, где text — список текстов задач, а value — список ID задач (см. пример использования)
`ep.change()`	`ИзменитьЗначение()`	Запускает обработчик change() для ДП
`ep.change(handler)`		Подписывает на изменение ДП
`ep.change(null)`		Отписывает все обработчики на изменение ДП
`ep.save()`		Сохраняет изменения ДП на сервере
`ep.save(handler)`		Подписывает на сохранение ДП
`ep.save(null)`		Отписывает все обработчики на сохранение ДП
`ep.update()`	`Обновить()`	Обновляет ДП с сервера
`ep.update(handler)`		Подписывает на обновление ДП с сервера
`ep.update(null)`		Отписывает все обработчики на обновление ДП с сервера
`(new ExtParam(1234)).val("123").save(handler).save().hide()`		Если логика не предусматривает иного, то повторно возвращает объект управления ДП
`SaveEPsWithIDs([1234, 1235])`		Сохраняет все ДП по массиву индексов. Срабатывают триггеры на save() для каждого из ДП
`ep.isHidden()`	`Скрыть()`	Принимает значение "true", если ДП нет на форме или он скрыт настройками категории
`ep.freeze()`	`Заблокировать()`	Делает ДП доступным только на чтение (принимает на вход значения "true" или "false")
`ep.adaptDesign()`		Устаревшее, не работает, начиная с версии 2.256. При установке значения "true" при скрытии/показе ДП верстка будет адаптироваться автоматически. Чтобы корректно скрыть элемент на форме, не оставляя пустого пространства, в новых версиях рекомендуется использовать свойство display в значении 'none'. Пример: `.querySelector('vh-ext-param-control-wrapper[ep-wrapper-id="ХХХ"]').style.display = 'none'` где ХХХ — ID ДП

ℹ️ Для ДП "Выпадающий список" и "Выпадающий список с редактированием" в режиме только для чтения событие, вызванное смарт-автоматизацией, запускается дважды. Чтобы отследить это в JS-вставке, можно проверять new ExtParam().val() -- первый раз оно возвращает старое значение ДП, а второй раз новое.

ℹ️ Если на карточке расположены два связанных ДП, доступных для редактирования, то при вызове обработчика change() для родительского ДП значение подчиненного ДП сбрасывается. Пример JS-вставки для работы со связанными ДП можно посмотреть здесь

ℹ️ Для версий ниже 2.256 требуется учесть собенности работы со сквозными ДП:

ДП типа "Сквозной" создается методом new ExtParam(ID сквозного ДП). ID сквозного ДП формируется как строковое соединение ID текущего ДП и ID финального ДП. Например, если в категории есть сквозной ДП с ID=5555, который смотрит на ДП в другой категории с ID=9999, то для сквозного ДП ID будет равным 55559999. Если такой ДП уже существует в задаче, обертка сработает некорректно.

Таблица совместимости методов и типов ДП в карточке задачи¶

Методы, не указанные в таблице совместимости, работают для всех ДП.

Тип ДП	ep.val()	ep.val("text")	ep.save()	ep.update()
Флажок (checkbox)	да	да ("да"/"on"/true/1)	да	да
Дата	да	да	да	да
Дата и время	да	да	да	да
Файл	нет	нет	нет	нет
Lookup	да (ID задачи)	да (ID задачи)	да	да
Деньги	да	да	да	да
Выбор нескольких задач из категории (multilookup)	да (JSON массив ID задач)	да (JSON массив ID задач)	да	да
Нумератор	да	нет	нет	нет
Число	да	да	да	да
Выпадающий список	да	да	да	да
Выбор нескольких задач из категории	да (ID задачи)	да (ID задачи)	да	да
Выбор пользователей	да (JSON массив)	нет	да	да
Таблица	да (html таблица)	нет	нет	нет
Текст	да	да (без шаблона номера телефона)	да	да
Большой текст с форматированием	да	да	да	да
Большой текст без форматирования	да	да	да	да
Сквозной	да	да	да	да
Дерево	нет	нет	нет	нет
URL	да	да	да	да

Объекты и методы для нового ДП "Таблица"

Таблица

object EpTable: {
   savedRowsCount: numeric,
   filteredRows: [ object Row ],
   multiWindow: object MultiWindow
}

Строка таблицы

object Row: {
   cells: [ object Cells ],
   id: number
}

Ячейка таблицы

object Cell: {
   columnId: numeric,
   columnValue: mixed,
   tooltip: function
}

Строки с учетом условий фильтра и пейджинга

filteredRows — строки, отобранные с учетом заданных условий фильтра (если фильтр включен), а также с учетом пейджинга (т.е. только на текущей странице, если пейджинг включен).

Множественный выбор

object MultiWindow: {
   filteredRows: [ object Row ]
}

Методы

Для таблицы:

onTableLoaded — загрузка/перезагрузка страницы, переключение страниц таблицы.
onTableRowAdded — добавление строки (передается объект строки).
onTableRowChanged — изменение значения ячейки.
onTableSaved — сохранение таблицы.

Для таблицы в режиме множественного выбора:

onTableMWLoaded — загрузка/перезагрузка страницы, переключение страниц таблицы.
onTableMWRowSelected — выбор строки (передается объект строки).
onTableMWRowChanged — изменение значения ячейки.
onTableMWClosed — закрытие окна множественного выбора.

Для ячейки:

tooltip() — подсказка, всплывающая при наведении мыши на ячейку.

ℹ️ Методы обновления ДП "Таблица" вызываются после отработки метода обновления карточки задачи (MTFMainLoadFinished).

Пример¶

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

function setTooltip (){
    var ept = window.firstForma.ep.table(11);     
    ept.filteredRows.forEach ( function( item, i, arr ) {
        item.cells.forEach ( function( item, i, carr ) {
            var tmp = 'TOOLTIP:' + i;
            item.tooltip ( tmp );
        });
    });
}
document.addEventListener('load', function(){ setTooltip (); });

где 11 — ID ДП "Таблица". Вместо 'TOOLTIP:' + i нужно подставить текст подсказки.

Методы для работы с пользователями

Изменение значения ДП

Для полной замены текущего значения ДП "Выбор пользователей" на новое значение в функцию ep.val() нужно передать JSON такого вида:

{"Users":[], "Groups":[], "OrgUnits":[]}

Например:

var ep123 = new ExtParam(123);
ep123.val('{"Users":[55,66], "Groups":[77], "OrgUnits":[]}');
ep123.save();

где 123 — ID ДП "Выбор пользователей".

Контроль изменений¶

При работе с ДП "Выбор пользователей" функция ep.val() возвращает JSON такого вида:

{"Users":{"Deleted":[],"Added":[],"Selected":[]},"Groups":{"Deleted":[],"Added":[],"Selected":[]},"OrgUnits":{"Deleted":[],"Added":[],"Selected":[]}}

Например:

// изменить

var ep123 = new ExtParam(123);
ep123.val('{"Users":[55,66], "Groups":[77], "OrgUnits":[]}');
ep123.save();

// посмотреть результат
console.log(ep123.val());

// получить ID пользователя, выбранного в ДП

var ep123 = new ExtParam(123);
obj = JSON.parse(ep123.val());
var userid = obj.Users.Selected[0];

где 123 — ID ДП "Выбор пользователей".

Текущий (сессионный) пользователь¶

Функция window.getSessionUserInfo() возвращает promise с ID текущего пользователя (userId), массив его групп (groups) и признак, является ли он администратором (isAdmin).

Например, чтобы получить ID текущего пользователя, можно использовать выражение вида

spaApi.getSessionUser().data.__zone_symbol__value.id

Методы для работы с кнопками перехода¶

Метод	Что делает
`var step = new TaskStepAPI(1234)`	Получает JS-объект для управления кнопкой перехода (в случае отсутствия кнопки перехода в JS консоль пишется соответствующее уведомление)
`step.hide()`	Скрывает кнопку
`step.show()`	Отображает кнопку
`step.click()`	Эмулирует клик по кнопке с выполнением всех обработчиков
`step.click(handler)`	Подписывает обработчик на клик
`step.click(null)`	Отписывает все обработчики по клику (за исключением стандартного)
`step.makeStep()`	Выполняет стандартное действие по клику
`step.cancelDefaultAction()`	Снимает стандартный обработчик с события клика по кнопке перехода
`step.restoreDefaultAction()`	Восстанавливает стандартный обработчик на событии клика по кнопке перехода

Методы для работы с порталами и виджетами¶

Для порталов flex

Подписка на событие загрузки виджета с ID = 123 оформляется следующим образом:

(window.firstForma.portal.block(123)).onLoaded(function(event){ });

В функцию подписки будет передан объект event, который содержит поля portal и block.

Объект portal относится к порталу в целом и имеет два свойства:

id (число) — идентификатор портала,
title (строка) — название портала.

Методы для портала не реализованы.

Объект block относится к виджетам на портале и имеет два свойства:

id (число) — идентификатор виджета,
title (строка) — название виджета.

Для порталов dashboard¶

Подписка на событие загрузки виджета с ID = 123 оформляется следующим образом:

(window.firstForma.portal.block(123)).onLoaded(function(event){ });

В функцию подписки будет передан объект event, который содержит объект data.

Получить идентификатор блока можно через event.data.blockId.

Информация о пользователе¶

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

Получить данные пользователя, который просматривает портал, можно с помощью функции getSessionUserInfo(). Функция возвращает ответ вызова метода /api/auth/info (Valhalla API версии 2.0).

В JS-вставках можно использовать переменную UserID, которая содержит ID пользователя.

Методы для виджетов¶

Метод	Что делает
`refresh()`	Обновляет виджет. Пример: `let widget = firstForma.portal.block(123); ... widget.refresh();`

Для виджетов Smart Html:

Метод Что делает

spaApi.loadApexCharts() Загружает библиотеку ApexCharts из SPA-бандла и возвращает Promise, который резолвится в конструктор ApexCharts. Использует ту же копию библиотеки, что и сам SPA, — без повторной загрузки с CDN.
Пример: spaApi.loadApexCharts().then(function(ApexCharts) { var chart = new ApexCharts(document.getElementById('my-chart'), options); chart.render(); });
Метод доступен только в JS Include, привязанных к SmartHtml-блоку портала. CDN-загрузка (loadApexCharts/ensureApexCharts) устарела.

spaCommand(command, data) Выполняет команду из параметра command; в параметре data — JSON с данными для команды.
Команда openInContentArea — открыть модальное окно. В data передаются content и context. Пример: const ref = spaCommand('openInContentArea', { content: 'iframe', context: { url: 'spa/user/profile/99' } }); ref.close();
Команда openNewsInContentArea — открыть карточку просмотра новости. В data передается taskid. Пример: const ref = spaCommand('openNewsInContentArea', { taskId: 123456 }); ref.close();

Для виджетов "Таблица" и "Поиск задач":

Метод	Что делает
`reload()`	Перезагружает виджет
`freeze()`	Делает виджет недоступным для работы (нельзя нажать на кнопку или кликнуть по ссылке)
`unfreeze()`	Делает виджет доступным для работы (можно нажать на кнопку или кликнуть по ссылке)

Методы для фильтров¶

Метод	Что делает
setFilters()	Устанавливает значение параметров фильтра. Пример: `let widget = firstForma.portal.block(123); widget.setFilters({param:999}); widget.refresh();`
filters()	Возвращает параметры фильтра в виде массива. Каждый параметр фильтра имеет методы get и set. Пример: `let widget = firstForma.portal.block(123); let param = widget.filters[0]; param.set(999); widget.refresh();`

Обращение к параметрам фильтра

Если для виджета настроен фильтр, а для наполнения виджета используется хранимая процедура, то из нее можно обращаться к параметрам фильтра через входящий параметр @XmlParam (см. пример).

Методы для работы с файлами¶

Из JS-вставок портала можно вызывать галерею для просмотра изображений:

Для вызова галереи используется функция window.firstForma.fileViewer(fileArray, fileIndex)

Параметр	Описание
fileArray	массив
url	url источник файла
fileType	тип файла (необязательный параметр) Возможные значения: audio, video, image, pdf, eml. Если тип не указан, то будет определяться автоматически по fileName и fileUrl. Если автоматически тип не определился, то принимается как image
name	название, которое будет отображаться при наведении курсора мыши (необязательный параметр)
mime	mime поле файла (необязательный параметр)
fileIndex	По умолчанию 0. Определяет, какой по порядку файл из массива отображать сейчас (необязательный параметр)

Примеры:

window.firstForma.fileViewer([{
url:'./GetAttachment.ashx?id=1234&versionId=1',
fileType:'video',
mime:'video/mp4'
}])

window.firstForma.fileViewer([{
url:'https://ru.1forma.ru/GetAttachment.ashx?id=569754',
fileType:'image', 
name:'Свежая выпечка'
},
{
url:'https://ru.1forma.ru/GetAttachment.ashx?id=569753',
fileType:'image', 
name:'Витрина'
}])

Полный пример настройки галереи на портале описан здесь.

Методы для работы с телефонией¶

Используются при настроенной интеграции с IP-телефонией.

Открыть окно вызова:

GetTopWindow().TCHeader.CallHistory.Open(1234)

где 1234 — короткий номер.

Если вызов используется в портальном блоке (например, по ссылке), то открыть окно вызова можно так:

window.parent.TCHeader.CallHistory.Open(1234)