NExS Docs

JavaScript API Reference

The NExS Embedded API provides JavaScript access to NExS apps embedded on your web page. Use it to read cell values, set inputs, control views, and respond to events.

The NEXS Object

When you embed a NExS app, a global NEXS object is created automatically. All API calls go through this object.

Important: The API is not available until the app initializes. Always use the nexsappinit event:

document.addEventListener("nexsappinit", function(e) {
  // API is now available
  console.log(NEXS.app(0).view(0).cell("B5").data);
});

Selecting Apps

NEXS.app(reference)

Select an embedded app by index or name.

// By index (zero-based)
NEXS.app(0)           // First app on the page
NEXS.app(1)           // Second app on the page

// By name
NEXS.app("My App")    // App named "My App"

Selecting Views

NEXS.app().view(reference)

Select a view within an app by index or name.

NEXS.app(0).view(0)              // First view of first app
NEXS.app(0).view("Dashboard")    // View named "Dashboard"
NEXS.app("My App").view(1)       // Second view of "My App"

Reading Cell Values

NEXS.app().view().cell(reference)

Get a cell’s contents. Returns a cell object.

// By cell address
NEXS.app(0).view(0).cell("B5")

// By named cell
NEXS.app(0).view(0).cell("TotalCost")

Cell Object Properties

{
  data: 64800,           // Raw value (number or string)
  datatype: "numeric",   // "numeric", "string", or "error"
  text: "$64,800",       // Formatted display value
  editable: false        // Whether the cell is an input
}

Example:

const cell = NEXS.app(0).view(0).cell("B5");
console.log(cell.data);      // 64800
console.log(cell.text);      // "$64,800"
console.log(cell.editable);  // false

Writing to Input Cells

NEXS.app().view().setInputs(array)

Set one or more input cell values and trigger recalculation.

// Set single cell
NEXS.app(0).view(0).setInputs(["B5", 100]);

// Set multiple cells
NEXS.app(0).view(0).setInputs([
  "B5", 100,
  "B6", 200,
  "C3", "Premium"
]);

NEXS.app().view().setInput(cell, value)

Convenience method for setting a single cell.

NEXS.app(0).view(0).setInput("B5", 100);

NEXS.app().view().queueInputs(array)

Queue input changes without triggering recalculation. Use with recalc() for efficiency when setting many values across views.

NEXS.app(0).view(0).queueInputs(["B5", 100]);
NEXS.app(0).view(1).queueInputs(["C3", 200]);
NEXS.app(0).recalc();  // Now recalculate once

NEXS.app().recalc()

Send all queued inputs to the server and recalculate.

NEXS.app(0).recalc();

Controlling Views

NEXS.app().setView(reference)

Switch the displayed view.

// By index
NEXS.app(0).setView(1);

// By name
NEXS.app(0).setView("Results");

// Get current view index
const currentView = NEXS.app(0).setView();

Shorthand Syntax

For simple pages with one app and one view, use shorthand:

Full SyntaxShorthand
NEXS.app(0).view(0).cell("B5")NEXS.cell("B5")
NEXS.app(0).view(0).setInputs([...])NEXS.setInputs([...])
NEXS.app(0).view(1)NEXS.view(1)
NEXS.app(0).setView(1)NEXS.setView(1)

The shorthand always references app(0) and, for cell operations, view(0).

Extended Cell Reference Syntax

Access cells using a string address:

[appRef]viewRef!cellRef

Components:

  • appRef — App name or index (optional, defaults to 0)
  • viewRef — View name or index (optional, defaults to 0)
  • cellRef — Cell address (e.g., “B7”) or named cell

Examples:

NEXS.cell("B7")                      // First view, first app
NEXS.cell("Dashboard!B7")            // "Dashboard" view, first app
NEXS.cell("[My App]Dashboard!B7")    // "Dashboard" view of "My App"
NEXS.cell("[1]2!B7")                 // View index 2 of app index 1
NEXS.cell("Input_1")                 // Named cell "Input_1"

All of these are equivalent if “My App” is the first app, “Dashboard” is its first view, and B7 is named “Input_1”:

NEXS.cell("[My App]Dashboard!B7")
NEXS.cell("[My App]Dashboard!Input_1")
NEXS.cell("[0]Dashboard!Input_1")
NEXS.cell("[0]0!Input_1")
NEXS.cell("[0]B7")
NEXS.cell("B7")
NEXS.cell("Dashboard!B7")
NEXS.cell("Dashboard!Input_1")
NEXS.cell("Input_1")

Hidden Views

Hidden (invisible) views don’t appear in the UI but can be accessed via API. Use them for:

  • Configuration values set programmatically
  • Intermediate calculations you need to read
  • Custom UIs where NExS handles only calculations
// Read from hidden view
const config = NEXS.app(0).view("My Hidden View").cell("A1").data;

// Write to hidden view
NEXS.app(0).view("My Hidden View").setInputs(["A1", 42]);

Complete Example

<!DOCTYPE html>
<html>
<head>
  <title>NExS API Example</title>
</head>
<body>
  <h1>Price Calculator</h1>

  <div>
    Quantity: <input type="number" id="qty" value="1">
    <button onclick="calculate()">Calculate</button>
  </div>

  <div>
    Total: <span id="total"></span>
  </div>

  <!-- Hidden NExS app (required for the NEXS object and events) -->
  <div style="display:none;">
    <script class="nexs"
      src="https://static.nexs.com/js/nexs_embed.js"
      data-nexs-app-url="https://platform.nexs.com/app/YOUR-APP-ID">
    </script>
  </div>

  <script>
    // Wait for app initialization
    document.addEventListener("nexsappinit", function(e) {
      // Read initial total
      updateDisplay();
    });

    // Listen for updates
    document.addEventListener("nexsappupdated", function(e) {
      updateDisplay();
    });

    function calculate() {
      const qty = document.getElementById("qty").value;
      NEXS.setInput("B3", qty);
    }

    function updateDisplay() {
      const total = NEXS.cell("B10").text;
      document.getElementById("total").textContent = total;
    }
  </script>
</body>
</html>