Вспомогательные функции HTML

Прямой вызов функций Ninox из HTML/JavaScript

Ninext упрощает создание интерфейсов HTML, связанных с Ninox: он позволяет вызывать функции Ninox прямо из кода HTML или JavaScript. Функция html в Ninox и так позволяет легко порождать компоненты HTML внутри формулы, но взаимодействие с логикой Ninox остаётся непростым без более сложных решений.

Возьмём, к примеру, поле ввода, которое должно запускать поведение, связанное с Ninox. Обычный подход — воспользоваться REST API, чтобы отправить данные на сервер, который затем обновит локальное отображение. Способ рабочий, но у него несколько недостатков:

• Техническая сложность: для вызовов API нужно хорошо разбираться в HTTP-запросах на JavaScript.
• Ограниченная интерактивность: изменения затрагивают только данные на сервере, без возможности немедленно обновить интерфейс локально.

С Ninext интеграция получается плавнее: ваши компоненты HTML/JavaScript связываются с функциями Ninox напрямую. Это повышает интерактивность приложений без обычных ограничений вызовов API.

callNinoxFunction

Функция callNinoxFunction позволяет вызвать скрипт Ninox из кода JavaScript. Такая связка даёт большую свободу во взаимодействии с Ninox, в частности позволяет:

• передавать значение поля ввода;
• выполнять действия по событиям onclick, onfocus, onblur, ontimer и т. п.;
• обрабатывать асинхронные операции с помощью функций обратного вызова.

Формат и параметры

ninext.callNinoxFunction(functionName, htmlElement, ...args, [callback])

Параметр	Описание
functionName	Имя вызываемой функции Ninox.
htmlElement	Может быть идентификатором элемента HTML (например, "myId") либо самим элементом (например, this или document.getElementById("myId")).
...args	Дополнительные параметры, передаваемые функции Ninox.
callback	(Необязательно) Функция для асинхронной обработки результата. Если она задана, её вызовут с аргументами (error, result).

Возвращаемое значение

Синхронный режим (без обратного вызова)

Функция возвращает объект JSON одной из следующих форм:

При успехе:

{
    result: <value>    // The value returned by the Ninox function
}

При ошибке:

{
    error: <string>    // Error message describing what went wrong
}

Асинхронный режим (с обратным вызовом)

Когда последним аргументом передана функция обратного вызова, она получает два параметра:

callback(error, result)

Параметр	Описание
error	Объект Error, если что-то пошло не так, либо undefined при успехе.
result	Значение, возвращённое функцией Ninox, либо null, если произошла ошибка.

Как это работает

Основная мысль — выполнять скрипты Ninox в контексте страницы HTML. Происходит это так:

1. Объявление функции Ninox
   В формуле Ninox объявите функцию (например, myOnblur), которая обработает параметры, переданные из JavaScript. Эта функция изолирована от остального скрипта и выполняется в контексте текущей записи (то есть при this в понимании Ninox).
2. Создание интерфейса HTML
   Встройте в формулу компонент HTML (например, поле ввода). В атрибуте события (скажем, onblur) вызовите callNinoxFunction, передав нужные параметры.
3. Наступление события
   Когда событие HTML происходит, callNinoxFunction вызывает указанную функцию Ninox, изолирует её и выполняет с заданным контекстом и параметрами (например, со значением поля ввода).

Этот механизм воспроизводит поведение обычного триггера, но при этом позволяет передать в вызов функции Ninox один или несколько собственных параметров.

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

Простой пример: поле ввода с onblur

1. Объявление функции Ninox

Добавьте в формулу Ninox такую функцию:

function myOnblur(inputValue : text) do
    alert("Input of record " + this.Id + " is " + inputValue)
end;

Она показывает предупреждение с идентификатором текущей записи и переданным значением.

2. Встраивание поля ввода HTML

Затем вставьте следующий код HTML, чтобы вывести поле ввода и задать событие onblur:

function myOnblur(inputValue : text) do
    alert("Input of record " + this.Id + " is " + inputValue)
end;

html("
    <input
        class='nx-input nx-input--editing'
        style='width: 100%; height: 100%;'
        onblur=""ninext.callNinoxFunction('myOnblur', this, this.value)""
    />
")

Как это работает:

• когда пользователь уходит из поля ввода (событие onblur),
• вызывается функция ninext.callNinoxFunction с аргументами:
  • 'myOnblur' — имя выполняемой функции Ninox,
  • this — сам элемент HTML,
  • this.value — текущее значение поля ввода.

Так скрипт Ninox myOnblur выполняется в контексте текущей записи, словно его запустил сам Ninox, и при этом получает значение поля ввода параметром.

Примеры синхронного использования

// Basic call - checking the result
const response = ninext.callNinoxFunction('myFunction', this, 'param1');
if (response.error) {
    console.error('Error:', response.error);
} else {
    console.log('Result:', response.result);
}

// Direct access to result (when you're confident there's no error)
alert(ninext.callNinoxFunction('getValue', this).result);

// With error handling
const res = ninext.callNinoxFunction('calculateTotal', 'myButtonId', 100, 0.2);
if (res.error) {
    alert('Calculation failed: ' + res.error);
} else {
    document.getElementById('total').textContent = res.result;
}

Примеры асинхронного использования (с обратным вызовом)

// Basic callback usage
ninext.callNinoxFunction('myFunction', this, 'param1', function(error, result) {
    if (error) {
        console.error('Error:', error.message);
    } else {
        console.log('Result:', result);
    }
});

// Update UI after async operation
ninext.callNinoxFunction('loadData', 'myContainer', recordId, function(error, result) {
    if (error) {
        alert('Failed to load data: ' + error.message);
        return;
    }
    document.getElementById('output').innerHTML = result;
});

// Using arrow function syntax
ninext.callNinoxFunction('calculateTotal', this, 100, 0.2, (error, result) => {
    if (!error) {
        document.getElementById('total').textContent = result;
    }
});

Когда применять обратные вызовы?

Пользуйтесь ими, когда:

• функция Ninox выполняет асинхронные операции (вызовы API, сложные вычисления);
• интерфейс нужно обновить после завершения функции;
• нужно выстроить несколько операций одну за другой.

Главное

• Контекст:
  функция Ninox выполняется так, что this обозначает текущую запись, — контекст выполнения остаётся согласованным.
• Гибкость:
  с помощью ...args можно передать сколько угодно параметров и приспособить поведение функции Ninox к нуждам вашего приложения.
• Обработка ошибок:
  и синхронный, и асинхронный режимы понятно сообщают об ошибках, что облегчает отладку.
• Разнообразие применений:
  этот механизм особенно полезен для сложного взаимодействия между интерфейсом на HTML/JavaScript и бизнес-логикой, описанной в Ninox.