Вспомогательные функции 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: из атрибута события HTML, из блока Native JS… Такая связка даёт большую свободу во взаимодействии с Ninox, в частности позволяет:

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

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

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

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

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

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

При успехе:

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

При ошибке:

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

Результат попадает в него, только если функция Ninox выполнилась без ожидания. Если ей приходится ждать (запись ещё загружается, идёт асинхронная обработка), объект возвращается раньше, чем она закончит, — без результата. В сомнительных случаях передавайте функцию обратного вызова.

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

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

callback(error, result)

error заполняется, когда вызов не удалось выполнить: функция, элемент или запись не найдены, код не компилируется.

Вызов функции из глобального кода

Если вторым аргументом передан null, Ninext вызывает функцию из глобального кода базы. Она выполняется без записи-контекста. Если в глобальном коде есть такая функция:

function greet(name : text) do
    alert("Hello " + name)
end;

то JavaScript вызывает её так:

ninext.callNinoxFunction('greet', null, 'Sofia');

Это также способ вызвать функцию глобального кода из блока Native JS, который не видит её напрямую.

Указание функции ссылкой

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

A13 — полный идентификатор записи: идентификатор таблицы, за которым следует номер записи. Триггеры таблицы обозначаются своим внутренним именем: afterCreate, afterUpdate или onClick. Поле обозначается своим идентификатором или именем, записанным без кавычек. Имя, содержащее скобки или другие знаки препинания, приводит к сбою вызова (исключение JavaScript): в таком случае указывайте поле по идентификатору.

Аргументы

Аргументы передаются из JavaScript в Ninox так:

Значения объекта могут содержать кавычки, переводы строк и диакритические знаки (начиная с версии 3.2.0). Не передавайте в качестве аргумента ни null, ни undefined: вызов тогда выбрасывает исключение JavaScript.

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

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

1. Объявление функции Ninox
   В формуле Ninox объявите функцию (например, myOnblur), которая обработает параметры, переданные из JavaScript. Ninext извлекает из формулы только эту функцию: она не видит ни переменных, ни других функций, объявленных в другом месте формулы. Она выполняется в контексте текущей записи (то есть при 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);
    } 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);
        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 к нуждам вашего приложения.
• Обработка ошибок:
  error сообщает о вызове, который не удалось выполнить: функция, элемент или запись не найдены, код не компилируется. Это текст, который выводится как есть. Для функции, которой может понадобиться ожидание, передавайте функцию обратного вызова.
• Разнообразие применений:
  этот механизм особенно полезен для сложного взаимодействия между интерфейсом на HTML/JavaScript и бизнес-логикой, описанной в Ninox.