Сценарии в виджетах

Виджеты — это один из базовых элементов построения интерфейса. Виджеты могут быть созданы и доступны в рамках Раздела, Приложения или общими для всей всей компании. Подробнее о виджетах можно узнать здесь.

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

По назначению исполнения сценарии в виджетах делятся на:

Клиентские — исполняются в браузере клиента, ограничены правами пользователя, под которым запускаются;

Серверные — исполняются на сервере с правами администратора, но имеют ограничение по количеству выполняемых функций в минуту.

Доступ к данным. Роли виджетов.

В сценариях виджетов мы имеем доступ к глобальным константам и данным, набор которых может отличаться в зависимости от роли виджета, в том числе «Context».

Общие виджеты.

Общими виджетами называются виджеты, созданные в Администрировании системы, разделе Интерфейсы и доступные из всех разделов компании. При этом общий виджет имеет только собственный контекст, который содержит свойства, добавленные на вкладке «Контекст» в конструкторе данного виджета, а также системные свойства, код которых начинается с двойного подчеркивания. Доступ в сценариях таким свойствам осуществляется с помощью константы «Context».

    Context.data.string_1 = 'string value';

Виджеты уровня раздела и приложения.

Виджеты могут быть созданы в интерфейсах Раздела, тогда они будут считаться виджетами уровня Раздела и доступны другим виджетам этого раздела. А также могут быть созданы на уровне отдельного приложения, то есть в интерфейсах данного приложения - тогда они будут доступны для других виджетов этого приложения, а также для виджетов данного раздела. Но свойства контекста при этом доступны для каждого виджета только свои, независимо от уровня.

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

Виджеты форм

Для приложений и бизнес процессов могут быть созданы пользовательские формы. Для каждой пользовательской формы автоматически создается самостоятельный виджет, который закрепляется за этой формой. Виджеты форм тоже имеют основной контекст «Context», но содержит он свойства того объекта, формой которого является данный виджет. Например если виджет является формой приложения, то в контексте ему доступны свойства данного приложения. Тоже самое для форм процессов — в их виджетах доступны свойства контекста добавленные самому бизнес процессу.

Но помимо этого виджеты форм имеют еще View-контекст, доступный в сценариях по константе «ViewContext». View-контест в данном случае содержить свойства добавленные непосредственно в самом виджете формы. Отсюда следует, что виджеты форм одного приложения/процесса объединены общим контекстом свойств этого приложения/процесса, но View-контекст у каждого виджета свой.

    const itemName = Context.data.__name;
    ViewContext.data.string_1 = `Название ${ itemName }}`;

Функции

Сценарии в виджетах представляют из себя набор функций. При загрузке виджета сценарии загружаются, транслируется (преобразуется) в JavaScript, формируется контекст. Непосредственно запуск (исполнение) осуществляется отдельных функций.

Системные функции

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

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

Пример использования:

function async onInit (): Promise<void> {
    Context.data.counter = 0;
    setStartValues();
}

Необходимость отображенияcanRender — функция запускается перед рендером виджета и определяет, будет ли отображен виджет. Функция должна возвращать значение типа boolean. Если функция вернет false, то рендер виджета будет отменен.

Пример использования:

function async canRender (): Promise<void> {
    return !!Context.data.app;
}

Пользовательские функции

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

function async onInit (): Promise<void> {
    const result = getValues();
    ...
}

function getValues (): Promise<any> {
    return {
        property_1: Context.data.prop1,
        property_2: `some string`,
    };
}

Вызов серверной функции из клиентского сценария

Если необходимо вызвать выполнение серверной функции не напрямую, а при выполнении клиентской, то можно ее вызвать используя константу «Server».

Серверная функция:

async function DoSomeWork() : Promise<void> {
    // Тут обычная логика серверного сценария.
    // Можно также использовать внешние вызовы через await
    let response = await fetch('https://my-service.mycompany.com/getmydata?token=' + Context.data.secureToken);
    Context.data.mySecureData = await response.text();
}

Клиентская функция:

async function onButtonClick() : Promise<void> {
    ViewContext.data.blockUI = true;
    await Server.rpc.DoSomeWork();
    ViewContext.data.blockUI = false;
}

Вызов функции дочерними виджетами

Помимо перечисленных, удобным вариантом вызова функций является вызов вложенными виджетам. Например, добавив виджет «Кнопка», в настройках, установив Тип действия «Сценарий» мы увидим свойство Событие при нажатии и возможность выбрать функцию.

Здесь мы можем выбрать тип функции Клиент/Сервер, а затем выбрать нужную из предлагаемого списка.

У разных виджетов такие свойства могут быть разные - например у виджета Вкладки есть «Событие при переключении вкладки». Но обычно они все представляют из себя выбор типа и названия функции, и чаще всего находятся на вкладке «События» настроек виджета.

Кроме этого у всех виджетов есть системные события: Событие при наведении курсора и Событие при перемещении курсора за границы. Они обычно находятся на вкладке «Системные» настроек виджета.

Вызов из виджета «Код»

Для вызова клиентского скрипта из виджета код, можно использовать конструкцию <%= Scripts %>.ИМЯ_ФУНКЦИИ():

    <button onclick="<%= Scripts%>.OpenPopup()">open popup</button>

Используя вызов функции из сценариев в атрибуте элемента, например onclick, мы можем передать только строку, но не какой-либо объект целиком. Например:

    <button onclick="<%= Scripts%>.check('<%= someObject.__id %>')">Выполнить</button>

Вызов функции в файле виджета

Для виджетов есть возможность загружать файлы. Если загрузить в виджет файл с js кодом, то можно вызвать функцию из файла. Для этого надо в виджете Код подключить js-файл из файлов виджета. Например:

    <script type="text/javascript" src="<%= UI.widget.filePath %>/test2.js"></script>
    <button type="button" onclick="onClickAction()">Кнопка</button>