|
|---|
По сравнению с использованием SMART-выражений смарт-скрипты имеют ряд преимуществ:
•Смарт-скрипты выполняются на сервере, а не в СУБД, а значит
oпозволяют снизить нагрузку на СУБД;
oвыполняются быстрее чем SMART-выражения.
•Смарт-скрипты позволяют работать с контекстными данными, еще не записанными в БД.
•В отличие от SMART и SQL, Lua — это полноценный программный язык. В Lua-скриптах удобнее работать с циклами, массивами, файлами и пр.
•Смарт-скрипты имеют более высокую степень безопасности (например, защищены от SQL-инъекций).
В смарт-скриптах можно вызывать любые смарт-действия и хранимые процедуры, т.е. можно использовать накопленный "багаж" разработок в "Первой Форме".
Смарт-скрипты могут использоваться как вместо смарт-выражений, так и вместо смарт-фильтров (в последнем случае они должны возвращать значение true/false). Но обычно с помощью смарт-скриптов автоматизируют какие-то действия (создать задачу, заполнить таблицу и пр.). Если нужно просто вычислить и вернуть какое-то значение, чаще используют смарт-выражения.
Создание и редактирование смарт-скрипта
Вы можете создать смарт-скрипт по кнопке + или отредактировать — по кнопке 
из окна редактирования смарт-действия. Для создания и редактирования смарт-скрипта открывается специальный интерфейс в отдельной вкладке браузера.
По кнопке ? (1) откроется подсказка по работе с смарт-скриптом и вызову смарт-действий. В зависимости от контекста, в котором вызывается смарт-скрипт, в него передается разный набор контекстных параметров (2). Нажав кнопку Выполнить, вы можете протестировать Исходный код. Результаты выполнения будут отображаться внизу окна (3).
Интерфейс редактирования смарт-скрипта
Новый редактор смарт-скриптов
|
|---|
В системе доступен новый редактор смарт-скриптов (LUA), он позволяет протестировать созданный код на существующих задачах по кнопке Выполнить. Нажатие на кнопку Отменить сбрасывает изменения к последнему сохраненному виду.
В редакторе поддерживается возможность выполнить часть выделенного фрагмента кода.
Новый LUA-редактор
По кнопке 
в панели инструментов редактора откроется подсказка по работе с смарт-скриптом и вызову смарт-действий.
Окно Помощь по lua-скриптам
Репозиторий
В системе доступен репозиторий Lua-скриптов — он служит в качестве библиотеки, к которой можно обратиться при написании скрипта. Скрипт из репозитория можно импортировать в текущий скрипт и вызывать функции, которые в нем содержатся.
Перейти в репозиторий прямо из редактора по кнопке Репозиторий — в модальном окне откроется табличный список скриптов с описанием и ID скрипта. Нажатие по строке из списка откроет выбранный скрипт в новом окне.
У всех скриптов из репозитория активна опция Из репозитория/библиотеки.
Для подключения библиотеки необходимо использовать LUA-функцию include:
•include(id) — Подключение скрипта по его ID (Рекомендуется).
•include('Description') — Подключение скрипта по его описанию (Не рекомендуется).
Подключать через функцию include можно только скрипты из репозитория, использование обычных скриптов вызовет ошибку. Скрипты рекомендуется подключать только в начале исходного кода. В подключаемых скриптах не должно быть вычислений, только определения функций и глобальных переменных. Максимальная глубина рекурсии — 5. В системе запрещено удаление скриптов из библиотеки, которые используются в коде.
Репозиторий
Работа с LUA-скриптами
Для выполнения смарт-скрипта можно использовать смарт-действие Выполнить смарт-скрипт (раздел Прочее).
|
|---|
Все названия регистрозависимы!Отладка и тестирование
Для отладки и тестирования смарт-скрипта удобно использовать функции var_dump или print — они выводят результат выполнения исходного кода в область внизу страницы. Отличие между ними в том, что var_dump может принимать любые типы данных, а print — только строковые.
Вывод с помощью функции var_dump
Контекст и параметры событий
|
|---|
В зависимости от контекста, в котором вызывается смарт-скрипт, в него передается разный набор контекстных параметров.
•в параметр CONTEXT передаются задача Task, пользователь User или Email,
•в параметр EVENTPARAMS в виде массива передаются параметры события, для которого вызывается смарт-скрипт,
•в параметр SESSION_USER передаются данные о пользователе, от имени которого ведется работа в системе.
•параметр DB_TYPE позволяет получить тип используемой базы данных. Возможные варианты: MSSQL, PG.
•параметр SYSTEM_INFO позволяет получить системную информацию. Возвращает объект с полями version - версия приложения, app - имя приложения: TC или Uniform.
|
|---|
Параметры могут представлять собой структуру данных (Task — данные о задачи, User — данные о пользователе). В этом случае в коде можно обратиться к элементам этой структуры. Например, если в параметре CONTEXT передается задача, текст задачи можно получить так:
CONTEXT.Text
или
CONTEXT['Text']
или
CONTEXT["Text"]
Некоторые параметры из EVENTPARAMS передаются в скрипт как материализованный объект из БД. Например, EVENTPARAMS[InitiatorUserId] — это таблица объекта User. Для получения Id пользователя из нее необходимо писать: EVENTPARAMS[InitiatorUserId]["Id"], либо EVENTPARAMS[InitiatorUserId] — параметр распознает объект из БД и возьмет его Id.
Названия элементов структуры немного отличаются от названий полей соответствующих таблиц в БД. Чтобы посмотреть названия элементов структуры, при отладке используйте функцию var_dump:
Просмотр структуры при отладке смарт-скрипта
Если смарт-скрипт выполняется не в своем контексте, при его вызове пользователь увидит сообщение об ошибке:
Пример сообщения об ошибке при несовпадении контекста события
Ошибки, связанные с работой смарт-скриптов (LUA), отображаются в общем Логе ошибок и в Логе ошибок бизнес-логики.
Результат
Результат, который возвращает смарт-скрипт, должен быть записан в переменную RESULT.
Результат выполнения смарт-скрипта
Функции
Использование подсказки по функциям
С помощью подсказки, которая вызывается нажатием на значок ?, вы можете посмотреть функции, которые можно использовать в смарт-скриптах, и параметры, которые эти функции принимают.
На вкладке Основное есть список доступных функций и их параметров. Функции сгруппированы в классы, название класса используется как префикс функции.
Например, вам нужно выполнить смарт-действие из смарт-скрипта. На вкладке Основное вы можете увидеть, что для этого используется класс SMART и функция execute_action. Там же вы можете посмотреть, какие параметры нужно передать этой функции. Обязательные параметры отмечены символом *. При наведении указателя мыши в правом верхнем углу всплывает значок копирования, по нажатию на нему в текущее место в коде будет добавлен шаблон вызова этой функции:
 Параметры для вызова SMART:execute_action |
SMART:execute_action('AttachSignature', @contextId, @contextType, { |
|
|---|
На вкладке Смарт-действия есть список всех смарт-действий и их параметров. Для поиска нужного смарт-действия воспользуйтесь строкой поиска. При наведении указателя мыши на блок с описанием смарт-действия в правом верхнем углу всплывает значок копирования, по нажатию на нему в текущее место в коде будет добавлен шаблон вызова этого смарт-действия:
 Поиск описания параметров смарт-действия |
SMART:execute_action('SetPriority', @contextId, @contextType, { |
Вызов смарт-действия
Для вызова смарт-действия из смарт-скрипта используется функция SMART:execute_action.
Например, вызов смарт-действия для изменения приоритета в Lua-скрипте будет выглядеть так:
SMART:execute_action(
'SetPriority', -- смарт-действие
CONTEXT.Id, -- контекст вызова смарт-действия
'task', -- тип контекста
{ -- параметры конкретного смарт-действия
Task = EVENTPARAMS.TaskId.Id,
Priority = 1,
ChangingUser = EVENTPARAMS.InitiatorUserId.Id
}
);
В данном примере предполагается, что скрипт вызывается по нажатию на дополнительную кнопку. Поэтому в нем доступны контекстные параметры события "нажатие на кнопку": EVENTPARAMS.TaskId — задача, в которой выполняется действие, и EVENTPARAMS.InitiatorUserId — пользователь, нажавший кнопку.
Асинхронное выполнение
Смарт-действия могут быть вызваны из смарт-скрипта в асинхронном режиме.
Пример вызова:
SMART:execute_action(
'ExecuteSmartScript',
nil,
nil,
{
Script = @string
}, true)
При асинхронном вызове результат не возвращается из execute_action, что значительно ускоряет работу.
В смарте, вызванном через ExecuteSmartScript (в любом режиме), доступны EVENTPARAMS пакета, из которого он вызван.
В смарт-действии, вызванном из смарт-скрипта LUA в асинхронном режиме через ExecuteSmartScript доступны контекстные параметры (EVENTPARAMS) пакета, из которого он вызван.
Вызов SQL запроса
Для выполнения смарт-запроса из смарт-скрипта используются функции SQL:scalar, SQL:query и SQL:query_one.
Например, так можно получить значение ИНН контрагента, выбранного в текущей задаче (ДП "Контрагент" имеет ID=11, ДП "ИНН" имеет ID=22):
local customerInn = SQL:scalar([[
SELECT TOP 1 epv2.ExtParamValue
FROM ExtParamValues epv1
JOIN ExtParamValues epv2 ON epv2.TaskID = epv1.SelectedTaskId AND epv2.ExtParamId = 22
WHERE epv1.TaskID = @taskId AND epv1.ExtParamId = 11
]], {taskId = CONTEXT.Id});
RESULT = customerInn
Так можно выбрать все активные задачи, где заказчиком является определенный пользователь:
RESULT = SQL:query(
[[
SELECT TaskID FROM Tasks WHERE UserId = @UserId AND IsActive = 1
]],
{ UserId = EVENTPARAMS.InitiatorUserId.Id }
);
В данном примере предполагается, что скрипт вызывается по нажатию на дополнительную кнопку. Поэтому в нем доступны контекстные параметры события "нажатие на кнопку", в том числе EVENTPARAMS.InitiatorUserId — пользователь, нажавший кнопку.
SQL:query_one возвращает первую строку из результирующего запроса в виде Lua-таблицы, в отличии от SQL:query, которая возвращает весь набор как массив Lua-таблиц.
Пример использования функции SQL:query_one:
local Task = SQL:query_one("select top 5 TaskID, UserID from Tasks",{})
var_dump(Task)
var_dump(string.format("TaskID = %s UserID = %s",Task.TaskID,Task.UserID))
var_dump(string.format("№Задачи %s Идентификатор пользователя %s",Task["TaskID"],Task["UserID"]))
Вызов хранимой процедуры
Для вызова хранимой процедуры из смарт-скрипта также используется функция SQL:query.
Например, для вызова процедуры расчета бонусов из задачи вызывается хранимая процедура, в которую передается номер задачи:
SQL:query(
[[
exec [dbo].[calculate_bonus] @TaskId = @Id
]],
{ Id = CONTEXT.Id }
);
Вызов HTTP-запроса
Для выполнения HTTP-запроса из смарт-скрипта используется функция HTTP:send_http_request.
Например, так можно вызвать и обработать запрос, который получает курс валюты с сайта ЦБ:
local json_res = HTTP:send_http_request('get', 'https://www.cbr-xml-daily.ru/daily_json.js', {}, {}, '', {});
local content = json_res['HttpResponse']['ResponseContent']; -- выделяем строку с телом ответа
local json_content = UTILS:json_decode(content); -- преобразуем строку с телом ответа в JSON
RESULT = json_content['Valute']['EUR']['Value'];
См. аналогичный пример, реализованный с помощью SMART.
Комментирование
Комментарий начинается с двойного дефиса -- и продолжается до конца строки. Вы можете управлять комментированием с помощью горячих клавиш:
CTRL + K + C — закомментировать выделенные строки в коде.
CTRL + K + U — раскомментировать выделенные строки в коде.
Lua подерживает блочные комментарии, которые начинаются с --[[ и продолжаются до закрывающего ]]. Вы можете закомментировать таким образом блок кода с помощью горячих клавиш: CTRL + /
Полезные ссылки
