HTML component custom API

Overview

Every HTML code component on a page exposes a JavaScript API via window.FpsHtml_API. This lets you programmatically control any HTML component from custom scripts — update content, show/hide, re-run embedded scripts, or call backend endpoints — all without a page reload.

Setup: Component ID

For the API to work, the component must have a Component ID set in its settings (comp_ID field). Without it the component won't register itself in window.FpsHtml_API.

Set a short, unique string like hero-block or promo-banner.

Accessing the API

The API is registered after the component mounts. Use the helper below to wait for it:

function waitForHtmlAPI(compId, callback, timeout) {
  timeout = timeout || 5000;
  var start = Date.now();
  var check = function() {
    if (window.FpsHtml_API && window.FpsHtml_API[compId]) {
      callback(window.FpsHtml_API[compId]);
    } else if (Date.now() - start < timeout) {
      setTimeout(check, 100);
    } else {
      console.error('FpsHtml_API: component "' + compId + '" not found after ' + timeout + 'ms');
    }
  };
  check();
}

Then use it:

waitForHtmlAPI('my-block', function(api) {
  api.setHtml('<p>Hello from API!</p>');
});

API Reference

getHtml()

Returns the current HTML string of the component.

var html = api.getHtml();
console.log(html); // '<p>Hello from API!</p>'

---

setHtml(newHtml)

Replaces the component's HTML content.

api.setHtml('<h2>Updated content</h2><p>Fresh text here.</p>');

---

rerender()

Forces the component to re-execute all embedded <script> tags. Useful when you need scripts inside the HTML to run again without changing the content.

api.rerender();

---

show()

Shows the component if it was hidden via api.hide().

api.show();

---

hide()

Hides the component programmatically. Does not affect the isHidden setting — just toggles visibility at runtime.

api.hide();

---

getData()

Returns the full data object the component was initialized with (including html, comp_ID, isHidden, etc.).

var data = api.getData();
console.log(data.comp_ID); // 'my-block'

---

getElement()

Returns the root DOM element wrapping the component. Useful for direct DOM manipulation.

var el = api.getElement();
el.style.opacity = '0.5';

---

callEndpoint(endpoint, method, body, params, callback)

Makes an authenticated request to a backend endpoint. Works the same as window.callEndpoint() but scoped to this component's context.

Parameters:

Parameter	Type	Description
endpoint	string	API endpoint name (e.g. 'getItems')
method	string	HTTP method: 'GET', 'POST'
body	object|FormData	Request body (ignored for GET)
params	object	URL query parameters
callback	function	(status, data) => {} — status is 'ok' or 'error'

api.callEndpoint('getStats', 'GET', null, { period: '30d' }, function(status, data) {
  if (status === 'ok') {
    api.setHtml('<p>Total: ' + data[0].total + '</p>');
  }
});

Examples

Load data and render HTML on page load

waitForHtmlAPI('stats-widget', function(api) {
  api.callEndpoint('getDashboardStats', 'GET', null, {}, function(status, data) {
    if (status === 'ok') {
      var item = data[0] || {};
      api.setHtml(
        '<div class="stats">' +
          '<span>Users: ' + item.users + '</span>' +
          '<span>Orders: ' + item.orders + '</span>' +
        '</div>'
      );
    } else {
      api.hide();
    }
  });
});

---

Control visibility from another HTML component

// This script lives inside a different HTML component on the same page
document.getElementById('toggle-btn').addEventListener('click', function() {
  var api = window.FpsHtml_API && window.FpsHtml_API['promo-banner'];
  if (api) {
    api.hide();
  }
});

---

Update content on a button click

waitForHtmlAPI('result-block', function(api) {
  document.getElementById('load-btn').addEventListener('click', function() {
    api.setHtml('<p>Loading...</p>');

    api.callEndpoint('fetchResult', 'POST', { id: '123' }, {}, function(status, data) {
      if (status === 'ok') {
        api.setHtml('<p>' + data[0].text + '</p>');
      } else {
        api.setHtml('<p>Error loading data.</p>');
      }
    });
  });
});

---

Re-run scripts after socket update

If you have scripts inside the HTML component that should re-execute when data refreshes via WebSocket, call rerender() after updating content:

waitForHtmlAPI('chart-block', function(api) {
  api.callEndpoint('getChartData', 'GET', null, {}, function(status, data) {
    if (status === 'ok') {
      api.setHtml('<canvas id="myChart"></canvas><script>/* init chart with ' + JSON.stringify(data) + ' */<\/script>');
      api.rerender();
    }
  });
});

Notes

• The API is registered after component mount. Always use waitForHtmlAPI (or a similar polling approach) rather than accessing window.FpsHtml_API directly.

• hide() / show() is runtime-only. The isHidden setting in the component config is a separate mechanism and takes precedence at initial render.

• If the component is removed from the page, its entry in window.FpsHtml_API is automatically deleted.

• All requests via api.callEndpoint() are authenticated the same way as window.callEndpoint(). See CUSTOM_BROWSER_API.md for details.