================= Справочник jsAPI ================= jsAPI ------ Объект *jsAPI* служит инструментом взаимодействия клинтской части приложения с сервером и фронтендом *pghs*, направлен на упрощение разработки фронтенда, предоставляет готовые инструменты работы с *DOM*, обёртки для стандартных javascript-функций и многое другое. *jsAPI* установлен по умолчанию и уже находится в глобальной области видимости *pghs* (*window*). Для просмотра всех методов и объектов достаточно вызвать объект *jsAPI* из отладчика (*jsAPI*, *console.log(jsAPI)*, *console.dir(jsAPI)*) Обновлено: 28.04.2023 Страница * submit() * process() * reload() * reloadWindow() * redirect() * getCurrentPage() * notification Модальное окно * modal * confirmModal() Регион * refresh() * сhangeTab() * component() Элемент формы (item) * setItem() * getItem() * updateItem() * hideItem() * showItem() * refreshList() Работа с DOM * dom.hide() * dom.show() * dom.focus() * dom.blur() * dom.setAttribute() Специальные * debug * logout() * clearLocalStorage() jsAPI: changeTab() ~~~~~~~~~~~~~~~~~~~ Переключает активный таб в регионе с типом "Tabs" Синтаксис """""""""" :: jsAPI.changeTab(id, tab); Параметры """""""""" id \ :sup:`String` id региона с типом "Tabs" tab \ :sup:`Integer` Порядковый номер вкладки (начиная с 1) *Примечание* Annotation Пример :: jsAPI.changeTab('MY_TABS', 2); jsAPI: clearLocalStorage() ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Удаляет все записи в localStorage приложения. Является обёрткой нативного метода `window.localStorage.clear();` Синтаксис """""""""" :: jsAPI.clearLocalStorage(); Параметры """""""""" Данная функция не принимает аргументов. Пример """"""" :: jsAPI.clearLocalStorage(); jsAPI: component() ~~~~~~~~~~~~~~~~~~~ jsAPI.component - интерфейс для работы с данными регионов в рамках заданного контекста Синтаксис """""""""" :: jsAPI.component(id).method(); Параметры """""""""" id \ :sup:`String` - id региона Методы """"""" refresh() :: jsAPI.component(id).refresh(); *Пример*: :: jsAPI.component('REPORT').refresh(); Реализован для следующих регионов: * `Calendar` * `Report` Обновляет регион с учётом указанных параметров (items). Например, с указанием имени поля для типа региона "календарь": :: { "items": [ "P50_FIO" ] } значение поля P50_FIO добавится в тело запроса /callAction помимо основных параметров Тело запроса: :: { "action": "CALENDAR", "data": { "page": 50, "id": "CLNDR", "items": { "G01": "20230428030000", "G02": "20230429030000", "P50_FIO": "Иванов Иван Иванович" } } } jsAPI: confirmModal() ~~~~~~~~~~~~~~~~~~~~~~ Отображает окно для подтверждения какого-либо действия. Синтаксис """""""""" :: jsAPI.confirmModal(options, callbacks); Параметры """""""""" options \ :sup:`Object` Содержит параметры: * title \ :sup:`String` - Заголовок окна; * text \ :sup:`String` - Текст, отобажаемый в диалоговом окне; *callbacks* Принимает функции: * onAccept \ :sup:`Function` - Выполняется при нажатии кнопки "Да" * onDecline \ :sup:`Function` - Выполняется при нажатии кнопки "Нет" и стандартном закрытии *Примечание* Данный метод является частным случаем вызова *jsAPI.modal.open*: :: jsAPI.modal.open({ title: 'Заголовок', text: 'Текст', width: 420, buttons: [{ text: 'Да', action: 'accept', class: 'btn-primary' }, { text: 'Нет', action: 'decline', class: 'btn-secondary' }, ] }, { onClose: function (e) { // Выполнится при закрытии }, onDecline: function (e) { // Выполнится при нажатии кнопки "Нет" и стандартном закрытии модального окна }, onAccept: function (e) { // Выполнится при нажатии кнопки "Да } }) Пример """"""" :: jsAPI.confirmModal({ title: 'Вы уверены?', text: 'При закрытии данные не сохранятся', }, { onDecline: function (e) { // Выполнится при нажатии кнопки "Нет" и стандартном закрытии модального окна }, onAccept: function (e) { // Выполнится при нажатии кнопки "Да } }) jsAPI: debug ~~~~~~~~~~~~~ Включение и отключение различных уровней отображения отладочной информации. Включает методы *enable* и *disable*. Активировать debug """"""""""""""""""" :: jsAPI.debug.enable(type); Деактивировать debug """"""""""""""""""""" :: jsAPI.debug.disable(type); Параметры """""""""" type \ :sup:`String` Имя уровня отладки. Доступные уровни отладки """"""""""""""""""""""""" * `CRITICAL` * `ERROR` * `WARNING` * `INFO` * `DEBUG` Примеры """""""" Активировать отладку с типом CRITICAL: :: jsAPI.debug.enable("CRITICAL"); Деативировать отладку с типом CRITICAL: :: jsAPI.debug.disable("CRITICAL"); jsAPI: dom.blur() ~~~~~~~~~~~~~~~~~ Удаляет фокус клавиатуры с текущего элемента. Обёртка для нативного метода `document.activeElement.blur()` Синтаксис """""""""" :: jsAPI.dom.blur(); Параметры """""""""" Данная функция не принимает аргументов. Примеры """""""" :: jsAPI.dom.blur(); jsAPI: dom.focus() ~~~~~~~~~~~~~~~~~~~ Устанавливает фокус на указанный элемент, если он может быть сфокусирован. Обёртка для нативного метода `el.focus()` Синтаксис """""""""" :: jsAPI.dom.focus(selector); Параметры """""""""" selector \ :sup:`String` Селектор элемента Примеры """""""" :: jsAPI.dom.focus('#P1000_MY_ITEM'); jsAPI: dom.hide() ~~~~~~~~~~~~~~~~~~ Прячет элемент с указанным css селектором путём добавления css класса js-api-hidden Синтаксис """""""""" :: jsAPI.dom.hide(selector); Параметры """""""""" selector \ :sup:`String` Селектор элемента Примеры """""""" Example 1: :: jsAPI.hide('#P1000_MY_ITEM'); jsAPI: dom.setAttribute() ~~~~~~~~~~~~~~~~~~~~~~~~~~ Добавляет и изменяет атрибуты у элемента с указанным селектором Синтаксис """""""""" :: jsAPI.dom.setAttribute(selector, attrs); Параметры """""""""" selector \ :sup:`String` Селектор элемента attrs \ :sup:`Object` Атрибуты Примеры """""""" :: jsAPI.setAttribute('#P1000_MY_ITEM',{ disabled: true, 'data-custom-attr': 'My custom value' }); jsAPI: dom.show() ~~~~~~~~~~~~~~~~~~ Отображает элемент с указанным css селектором путём удаления css класса js-api-hidden Синтаксис """""""""" :: jsAPI.dom.show(selector); Параметры """""""""" selector \ :sup:`String` Селектор элемента Примеры """""""" Example 1: :: jsAPI.show('#P1000_MY_ITEM'); jsAPI: getCurrentPage() ~~~~~~~~~~~~~~~~~~~~~~~~ Отдаёт информацию о текущей странице в виде: :: { "pageId": "1000", "ELEMENT_STATES": { ... }, "CLIENT_VALIDATION": { ... }, "VALIDATION": { ... }, "items": { ... }, "page": { ... } } Синтаксис """""""""" :: jsAPI.getCurrentPage(); Параметры """""""""" Данная функция не принимает аргументов. Примеры """""""" Получить id страницы: :: jsAPI.getCurrentPage().pageId; Получить значения item-а: :: jsAPI.getCurrentPage().items['P1000_MY_ITEM']; jsAPI: getItem() ~~~~~~~~~~~~~~~~~ Возвращает значение элемента формы Синтаксис """""""""" :: jsAPI.getItem(id); Параметры """""""""" id \ :sup:`String` - id элемента формы. НЕ является селектором (указывать без '#') Пример """"""" :: jsAPI.getItem('P1000_ITEM'); jsAPI: hideItem() ~~~~~~~~~~~~~~~~~~ Удаляет элемент формы (item) из DOM и привязанную к нему колонку Синтаксис """""""""" :: jsAPI.hideItem(id); Параметры """""""""" id \ :sup:`String` - id элемента формы. НЕ является селектором (указывать без '#') Пример """"""" :: jsAPI.hideItem('P1000_ITEM'); jsAPI: logout() ~~~~~~~~~~~~~~~~ Совершает выход из приложения (логаут), вызывая метод {API_URL}/logout Синтаксис """""""""" :: jsAPI.logout(); Параметры """""""""" Данная функция не принимает аргументов. Пример """"""" :: jsAPI.logout(); jsAPI: modal ~~~~~~~~~~~~~ jsAPI.modal - модуль для управления модальными окнами приложения. Методы """"""" :: jsAPI.modal.open(options, callbacks); Параметры """""""""" options \ :sup:`Object` Опции отображения диалогового окна Содержит параметры: * title \ :sup:`String` - Заголовок окна * page \ :sup:`String` - URL - страницы, которая будет отображаться в диалоговом окне * width \ :sup:`Number` - Ширина окна * text \ :sup:`String` - Текст, отображаемый в контентной части диалогового окна * buttons \ :sup:`Array` - Кнопки, отображаемые в нижней части диалогового окна * selector \ :sup:`String` - Селектор элемента для привязки к динамическому действию (Dynamic Action, DA) callbacks \ :sup:`Object` Принимает функции: * onClose \ :sup:`Function` - Выполняется при закрытии окна `jsAPI.modal.close();`, `jsAPI.modal.accept();` * onAccept \ :sup:`Function` - Выполняется при закрытии окна с ипользовании метода `jsAPI.modal.accept();` * onDecline \ :sup:`Function` - Выполняется при закрытии окна с ипользовании метода `jsAPI.modal.close();` :: jsAPI.modal.close(); Закрывает модальное окно, вызывает *onClose*, *onDecline* в *jsAPI.modal.open* :: jsAPI.modal.accept(); Закрывает модальное окно, вызывает *onAccept*, в *jsAPI.modal.open* Примеры """""""" Вызов confirm модала :: jsAPI.modal.open({ title: 'Заголовок', text: 'Текст', width: 420, buttons: [{ text: 'Да', action: 'accept', class: 'btn-primary' }, { text: 'Нет', action: 'decline', class: 'btn-secondary' }, ] }, { onClose: function (e) { // Выполнится при закрытии }, onDecline: function (e) { // Выполнится при нажатии кнопки "Нет" и стандартном закрытии модального окна }, onAccept: function (e) { // Выполнится при нажатии кнопки "Да } }) Стандартный вызов страницы в модальном окне :: jsAPI.modal.open({ page: `/1000/`, title: 'Заголовок', }); Открытие страницы в модале с указанием GET параметров и селектором для привязки к динамическому действию :: jsAPI.modal.open({ page: `/1000/?P2000_ITEM=${jsAPI.getItem("P2000_ITEM")}&clear=1000`, title: 'Заголовок', selector: '#DA_ELEMENT_ID' }); Открытие страницы в модале с указанием GET параметров, селектором для привязки к динамическому действию и коллбэками :: jsAPI.modal.open({ page: `/1000/?P2000_ITEM=${jsAPI.getItem("P2000_ITEM")}&clear=1000`, title: 'Заголовок', selector: '#DA_ELEMENT_ID' }, { onClose: function (e) { console.log(e); // Выполнится при jsAPI.modal.close(), jsAPI.modal.accept() }, onAccept: function (e) { console.log(e); // Выполнится при jsAPI.modal.accept() }, onDecline: function (e) { console.log(e); // Выполнится при jsAPI.modal.close() } }); jsAPI: notification ~~~~~~~~~~~~~~~~~~~~ Включает методы *success*, *error* и *warning* которые выводят стандартную нотификацию приложения. Уведомление об успешном действии """"""""""""""""""""""""""""""""" :: jsAPI.notification.success(message);//Выводит уведомление об успешном действии Уведомление об ошибке """""""""""""""""""""" :: jsAPI.notification.error(message);//Выводит уведомление об ошибке Предупреждение (warning) """"""""""""""""""""""""" :: jsAPI.notification.warning(message);//Выводит предупреждение (warning) Параметры """""""""" message \ :sup:`String`, \ :sup:`Array` Одно сообщение если аргумент указан в виде строки, или массив сообщений если аргумент указан в виде массива строк (выводятся последовательно друг за другом) Примеры """""""" Сообщение об успешном действии: :: jsAPI.notification.success('Успешное действие'); Сообщения об успешных действиях: :: jsAPI.notification.success(['Успешное действие', 'Успешное действие 2']); Сообщение об ошибке: :: jsAPI.notification.error('Ошибка'); Сообщения об ошибках: :: jsAPI.notification.error(['Ошибка', 'Ошибка 2']); Предупреждение (warning) :: jsAPI.notification.warning('Внимание!');//Выводит предупреждение (warning) Предупреждения (warnings) :: jsAPI.notification.warning(['Предупреждение', 'Предупреждение 2']);//Выводит предупреждения (warnings) jsAPI: process() ~~~~~~~~~~~~~~~~~ Метод jsAPI.process выполняет xhr запрос {API_URL}/callAction со следующими параметрами: :: { action: "PROCESS", data: { page: pageID, request: requestName, items: items } } *pageID* (*data.page*) ID текущей страницы. Определяется автоматически. *requestName* (*data.request*) Имя запроса. Определяется аргументом *requestName* *items* (*data.items*) Значения *items*. Определяется аргументом *items* Синтаксис """""""""" :: jsAPI.process(requestName, items, callbacks); Параметры """""""""" *requestName* \ :sup:`String` Имя запроса items \ :sup:`Object` Значения items, отправляемые в теле запроса {API_URL}/callAction. Допускается использовать пустой объект {} если не требутся отправки значений. callbacks \ :sup:`Object` Принимает функции: onSuccess \ :sup:`Function`, onError \ :sup:`Function`. Примеры """""""" Вызов без дополнительных параметров: :: jsAPI.process("MY_PROCESS"); Вызов с items: :: jsAPI.process("MY_PROCESS", { P1000_MY_ITEM_1: 'Value 1', P1000_MY_ITEM_2: 'Value 2', }); Вызов с items и обработчиком успешного ответа: :: jsAPI.process("MY_PROCESS", { P1000_MY_ITEM_1: 'Value 1', P1000_MY_ITEM_2: 'Value 2', }, { onSuccess: function (res) { console.log(res); } }); Вызов с items, обработчиками успешного ответа и ошибки: :: jsAPI.process("MY_PROCESS", { P1000_MY_ITEM_1: 'Value 1', P1000_MY_ITEM_2: 'Value 2', }, { onSuccess: function (res) { console.log(res); }, onError: function (err) { console.error(err); } }); jsAPI: redirect() ~~~~~~~~~~~~~~~~~~ Осуществляет переход на указанную страницу приложения Синтаксис """""""""" :: jsAPI.redirect(path, callbacks); Параметры """""""""" path \ :sup:`String` Относительный путь до страницы *callbacks* Принимает функцию: onSuccess \ :sup:`Function` *Примечание* Данный метод использует внутренний роутинг приложения и не является аналогом window.location.href. Изменение роута не предполагает перезагрузку страницы Примеры """""""" Стандартный вызов: :: jsAPI.redirect('/content/5000?clear=5000'); Вызов с обработчиком: :: jsAPI.redirect('/content/5000?clear=5000', { onSuccess: function (data) { console.log(data) } }); jsAPI: refresh() ~~~~~~~~~~~~~~~~~ Метод jsAPI.refresh предназначен для обновления данных в регионах. Выполняет xhr запрос {API_URL}/callAction со следующими параметрами: :: { action: "REFRESH", data: { data: data } } Синтаксис """""""""" :: jsAPI.refresh(data, callbacks); Параметры """""""""" *data* \ :sup:`Object` Данные для отправки в теле запроса *callbacks* \ :sup:`Object` Принимает функции: *onSuccess* \ :sup:`Function`, *onError* \ :sup:`Function`. *Примечание* Для обновления региона необходимо указать его id в параметре data: :: data: { { id: 'MY_REGION_ID' } } Примеры """""""" Стандартный вызов: :: jsAPI.refresh({ id: "PARAMS", page: "1000", items: { P1000_ID: '1' } }); Стандартный вызов с обработчиками: :: jsAPI.refresh({ id: "PARAMS", page: "1000", items: { P1000_ID: '1' } }, { onSuccess: function (data) { console.log(data); }, onError: function (err) { console.error(err); } }); jsAPI: refreshList() ~~~~~~~~~~~~~~~~~~~~~ Метод jsAPI.refreshList предназначен для обновления списков привязанных к элементам форм. Таких как Select List, Multiselect, Autocomplete. Выполняет xhr запрос {API_URL}/callAction со следующими параметрами: :: { action: "REFRESH_LIST", data: { data: data } } Синтаксис """""""""" :: jsAPI.refreshList(data, callback); Параметры """""""""" *data* \ :sup:`Object` Данные для отправки в теле запроса *callbacks* \ :sup:`Object` Принимает функции: *onSuccess* \ :sup:`Function`, *onError* \ :sup:`Function`. *Примечание* Для обновления элемента формы необходимо указать его id в параметре data: :: data: { { id: 'P1000_SELECT' } } Примеры """""""" Стандартный вызов :: jsAPI.refreshList({ id: "P1000_SELECT", page: "1000", items: { "P1000_PARAM": 'New P1000_PARAM val' } }) Стандартный вызов с обработчиками: :: jsAPI.refreshList({ id: "P1000_SELECT", page: "1000", items: { "P1000_PARAM": 'New P1000_PARAM val' } }, { onSuccess: function (data) { console.log(data); }, onError: function (err) { console.error(err); } }); jsAPI: reload() ~~~~~~~~~~~~~~~~ Осуществляет ререндеринг страницы после успешного ответа метода {API_URL}/showPage?page=id Синтаксис """""""""" :: jsAPI.reload(); Параметры """""""""" Данная функция не принимает аргументов. *Примечание* **не является аналогом window.loacation.reload()**. Метод вызывает ререндеринг страницы после успешного ответа метода {API_URL}/showPage, как это делается при смене роута. Примеры """""""" :: jsAPI.reload(); jsAPI: reloadWindow() ~~~~~~~~~~~~~~~~~~~~~~ Обёртка для нативного метода `window.location.reload()` Перезагружает приложение на текущей странице. Синтаксис """""""""" :: jsAPI.reloadWindow(); Параметры """""""""" Данная функция не принимает аргументов. Примеры """""""" :: jsAPI.reloadWindow(); jsAPI: setItem() ~~~~~~~~~~~~~~~~~ Изменяет значение элемента формы Синтаксис """""""""" :: jsAPI.setItem(id, value); Параметры """""""""" id \ :sup:`String` - id элемента формы. НЕ является селектором (указывать без '#'). value \ :sup:`String` - Значение Примеры """""""" Присвоить новое значение :: jsAPI.setItem('P1000_ITEM', 'Новое значение'); Очистить :: jsAPI.setItem('P1000_ITEM', ''); jsAPI: showItem() ~~~~~~~~~~~~~~~~~~ Возвращает удалённый при помощи *jsAPI.hideItem(id)* элемент формы (item) в DOM и привязанную к нему колонку Синтаксис """""""""" :: jsAPI.showItem(id); Параметры """""""""" id \ :sup:`String` - id элемента формы. НЕ является селектором (указывать без '#') Пример """"""" :: jsAPI.showItem('P1000_ITEM'); jsAPI: submit() ~~~~~~~~~~~~~~~~ Осуществляет сабмит страницы методом {API_URL}/processPage Синтаксис """""""""" :: jsAPI.submit(items, callbacks); Параметры """""""""" *items* \ :sup:`Object` Дополнительные значения items, отправляемые в теле запроса {API_URL}/processPage, помимо основных items страницы. Допускается использовать пустой объект {} если не требутся отправки кастомных значений. *callbacks* \ :sup:`Object` Принимает функции *onSuccess* \ :sup:`Function`, *onError* \ :sup:`Function`. *Примечание* При кастомном обрабортчике onSuccess не будет запущена перезагрузка страницы (переопределение поведения по умолчанию), если требуется перезагрузка страницы и дополнительная логика в кастомном обработчике, используется метод jsAPI.reload() внутри onSuccess Примеры """""""" Стандартный вызов: :: jsAPI.submit(); Вызов с дополнительными значениями items и обработчиком успешной отправки и ошибки: :: jsAPI.submit( { MY_CUSTOM_ITEM: "CUSTOM VALUE", }, { onSuccess: function (res) { console.log("При кастомном обрабортчике не будет перезагрузки страницы"); }, onError: function (err) { console.error(err); //Обработчик ошибки сервиса {API_URL}/processPage }, } ); Вызов без дополнительных значений items и с обработчиком успешной отправки: :: jsAPI.submit( {}, { onSuccess: function (res) { //Здесь может быть любой код jsAPI.reload(); //И после него выполнится перезагрузка страницы }, } ); jsAPI: updateItem() ~~~~~~~~~~~~~~~~~~~~ Обновляет параметры элемента формы на уровне страницы ({API_URL}/showPage) Синтаксис """""""""" :: jsAPI.updateItem(id, parameters); Параметры """""""""" id \ :sup:`String` - id элемента формы. НЕ является селектором (указывать без '#') *parameters* \ :sup:`Object` Содержит параметры: label \ :sup:`String` - Плейсхолдер (лейбл элемента) required \ :sup:`Boolean` - Обязательность заполнения col \ :sup:`Integer` - Ширина колонки в форме (от 1 до 12) mask \ :sup:`String` - Маска поля (работает только с TEXT) maxlength \ :sup:`Integer` - Макс. кол-во символов (работает только с TEXT) Пример """"""" :: jsAPI.updateItem('P1_LOGIN', { "label": "Новый лейбл", "required": false, "col": 6, "mask": '999', "maxlength": 3 });