HTML helping functions

Access Ninox Functions Directly from HTML/JavaScript

Ninext makes it easier to create HTML interfaces integrated with Ninox by allowing direct calls to Ninox functions from HTML or JavaScript code. While Ninox’s html function enables easy generation of HTML components within a formula, interacting with Ninox logic remains complex without resorting to more complex solutions.

Take, for example, an input field that needs to trigger behavior linked to Ninox. The traditional approach involves using the REST API to send data to the server, which then updates the local display. While effective, this method has several drawbacks:

• Technical complexity: Implementing API calls requires a solid understanding of HTTP requests in JavaScript.
• Limited interactivity: Changes only affect server-side data, without the ability to trigger immediate local updates in the interface.

With Ninext, you get a smoother integration, enabling direct linking of your HTML/JavaScript components to Ninox functions. This enhances the interactivity of your applications without the usual constraints of API calls.

callNinoxFunction

The callNinoxFunction function allows you to call a Ninox script from JavaScript code: an HTML event attribute, a Native JS block… This integration provides great flexibility for interacting with Ninox, particularly for:

• Sending the value of an input field,
• Executing actions during events such as onclick, onfocus or onblur, or when a timer expires (setTimeout),
• Handling asynchronous operations with callbacks.

Format and Parameters

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

Return Value

Synchronous mode (without callback)

The function immediately returns a JSON object with one of the following structures:

On success:

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

On error:

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

The result only appears in it if the Ninox function ran without waiting. If it has to wait (a record still to be loaded, an asynchronous operation), the object is returned before it has finished, without a result. When in doubt, pass a callback.

Asynchronous mode (with callback)

When a callback function is provided as the last argument, the callback receives two parameters:

callback(error, result)

error is set when the call could not be made: function, element or record not found, code that does not compile.

Calling a function of the global code

With null as the second argument, Ninext calls a function of the database's global code. It runs without a context record. With this function in the global code:

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

the JavaScript calls it like this:

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

It is also the way to call a function of the global code from a Native JS block, which does not see it directly.

Designating the function by a reference

The second argument can also be a text that designates a record. Ninext first looks for an HTML element with this ID, then reads the reference: the function then runs in the context of that record (this).

A13 is the record's full ID: the table's ID followed by the record's number. Table triggers bear their internal name: afterCreate, afterUpdate or onClick. The field is designated by its ID or by its name, written without quotes. A name that contains parentheses or other punctuation marks makes the call fail (JavaScript exception): in that case, designate the field by its ID.

The arguments

Arguments pass from JavaScript to Ninox as follows:

The values of an object may contain quotes, line breaks and accented characters (from version 3.2.0 onwards). Do not pass null or undefined as an argument: the call then throws a JavaScript exception.

How It Works

The main idea is to execute Ninox scripts within the context of an HTML page. Here’s how it works:

1. Defining the Ninox Function
   In your Ninox formula, define a function (e.g., myOnblur) that will handle the parameters passed from JavaScript. Ninext extracts only this function from the formula: it sees neither the variables nor the other functions declared elsewhere in the formula. It executes within the context of the current record (equivalent to this in Ninox).
2. Creating the HTML Interface
   Embed an HTML component (e.g., an input field) within the formula. In the event attribute (such as onblur), use callNinoxFunction to call the corresponding Ninox function, passing the necessary parameters.
3. Triggering the Event
   When the HTML event fires, callNinoxFunction calls the specified Ninox function, isolates it, and executes it with the given context and parameters (e.g., the input field’s value).

This mechanism simulates the behavior of a native trigger while allowing one or more custom parameters to be passed to the Ninox function execution.

Usage Examples

Basic Example: Input Field with onblur

1. Defining the Ninox Function

In your Ninox formula, add the following function:

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

This function displays an alert showing the current record’s ID and the passed value.

2. Integrating the HTML Input Field

Next, insert the following HTML code to display an input field and define the onblur event:

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)""
    />
")

How it works:

• When a user leaves the input field (onblur event),
• The function ninext.callNinoxFunction is called with:
  • 'myOnblur': the name of the Ninox function to execute,
  • this: the HTML element itself,
  • this.value: the current value of the input field.

This ensures that the Ninox script myOnblur runs in the context of the current record, as if it were triggered natively by Ninox, while also receiving the input field’s value as a parameter.

Synchronous Usage Examples

// 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;
}

Asynchronous Usage Examples (with callback)

// 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;
    }
});

When to Use Callbacks?

Use the callback pattern when:

• The Ninox function performs asynchronous operations (API calls, complex calculations),
• You need to update the UI after the function completes,
• You want to chain multiple operations sequentially.

Key Points

• Contextualization:
  The Ninox function executes with this representing the current record, or the record designated by the reference, ensuring consistency in the execution context. A function of the global code runs without a record.
• Flexibility:
  You can add as many parameters as needed using ...args, allowing the Ninox function’s behavior to be adapted to your application’s specific needs.
• Error Handling:
  error reports a call that could not be made: function, element or record not found, code that does not compile. It is a text, to be displayed as is. For a function that may have to wait, pass a callback.
• Multiple Uses:
  This mechanism is particularly useful for integrating complex interactions between the HTML/JavaScript user interface and the business logic defined in Ninox.