calcapp-iframe.js

Overview

The calcapp-iframe.js JavaScript library enables host pages to interact with embedded Calcapp apps. Use the library to:

• Extract field values and other app data programmatically.
• Monitor app height changes and automatically resize iframe containers.
• Access user information from private apps.
• Check visibility states of fields and buttons.

Target audience

This library is designed for developers with JavaScript experience who need to integrate Calcapp apps into existing web applications. Most Calcapp authors won’t need this library, as Calcapp’s primary appeal is requiring only formula knowledge rather than traditional programming skills.

If you’re a programmer looking to integrate Calcapp apps with your company’s services, or if you know JavaScript and want to create more sophisticated integrations, this library provides the tools you need.

Getting started

Loading the library

Load the library from one of these URLs:

• https://connect.calcapp.net/calcapp-iframe.js (development version with extensive developer documentation).
• https://connect.calcapp.net/calcapp-iframe.min.js (minified production version).

Important: Don’t self-host the library. We may update it as Calcapp evolves. Add the defer attribute to prevent the script from blocking page load:

<script src="https://connect.calcapp.net/calcapp-iframe.min.js"
        defer>
</script>

Browser compatibility

The library uses modern JavaScript features and requires a current web browser. We don’t support Internet Explorer.

Library initialization

The library sets window.calcappIframe as the main entry point. Use this object to retrieve values from embedded apps and manage iframe dimensions.

Quick example

To print the value of field named Field1, part of a screen named MainScreen, to your JavaScript console:

// Using async/await (recommended)
try {
  const value = await calcappIframe.getValue("MainScreen", "Field1");
  console.log("Value: ", value);
} catch (error) {
  console.error("Error: ", error);
}

// Using promises
calcappIframe.getValue("MainScreen", "Field1")
  .then(value => console.log("Value: ", value))
  .catch(error => console.error("Error: ", error));

API reference

The calcappIframe object provides these functions:

• calcappIframe.getValue() — Get a single value.
• calcappIframe.getValues() — Get multiple values.
• calcappIframe.subscribeToNewHeight() — Monitor height changes.
• calcappIframe.manageHeight() — Automatically manage iframe height.

calcappIframe.getValue

Retrieves a single value from an embedded Calcapp app.

try {
  const value = await calcappIframe.getValue("MainScreen", "Field1");
  console.log("Value: ", value);
} catch (error) {
  console.error("Error: ", error);
}

Use getValues to retrieve multiple values efficiently.

Understanding Calcapp’s data structure

Apps store data in properties that belong to variables or calculations:

Variables include fields, text boxes, groups, buttons and navigators. Fields have a default property (their value) plus additional properties:

• visible — Whether the field is visible.
• label — The label of the field.
• initialValue — The value displayed initially for the field.
• formattedValue — The field value formatted as a string.
• backgroundColor — The background color of the field.

Number fields, text fields, switch fields and date and time fields support additional properties specific to their types. Similarly, navigators, text boxes and groups support their distinctive properties.

Calculations include all screens, which have properties like:

• primaryColor — Color used for navigation bar background, button labels and more (if not overridden).
• fieldValueColor — Color used for field values.
• nextScreenAvailable — Whether the user should be allowed to navigate forward to the next screen.

Top-level calculation (usually named App) includes properties like:

• zoomLevel — Value determining the visual size of the app.
• userEmailAddress — Email address of the user signed into a private app.
• operatingSystem — Operating system used on the device running the app.

All properties are documented in our properties reference.

Important: Property names must start with a lowercase letter when used with this library. Use visible, not Visible.

Data type mapping

Calcapp data types map to JavaScript as follows:

• Numbers → JavaScript numbers.
• Text → JavaScript strings.
• Logical values → JavaScript booleans.
• Blank values → null.
• Runtime errors → Objects with error: true.

Promise-based API

All functions return JavaScript Promise objects because communication with embedded apps is asynchronous. Apps run in iframe elements and the only way for a page embedding such apps to communicate with them is through message passing. Values cannot be returned directly (synchronously) and are only available at some unspecified point in the future.

The returned promise is resolved when the value becomes available, at which point your code can run. Handle success and errors like this:

try {
  const value = await calcappIframe.getValue("SomeScreen", "SomeField");
  console.log("Value: ", value);
} catch (error) {
  console.error("Error: ", error);
}

Examples

Get a field value:

try {
  const value = await calcappIframe.getValue("MainScreen", "Field1");
  console.log("Value: ", value);
} catch (error) {
  console.error("Error: ", error);
}

Check field visibility:

try {
  const isVisible = await calcappIframe.getValue("MainScreen",
                                                 "Field1",
                                                 "visible");
  console.log("Field visible: ", isVisible);
} catch (error) {
  console.error("Error: ", error);
}

Target specific app (when multiple apps are embedded):

If there are multiple apps embedded in a single page, you must identify which app to target. You can pass:

• The iframe element hosting the app directly as the fourth parameter.
• The alias of the app (such as abc123).
• The numeric position of the iframe element hosting the app (in depth-first traversal order).

Example using an app alias:

try {
  const value = await calcappIframe.getValue("MainScreen",
                                             "Field1",
                                             null,
                                             "abc123");
  console.log("Value: ", value);
} catch (error) {
  console.error("Error: ", error);
}

Get user email from private app:

try {
  const email = await calcappIframe.getValue("App", null, "userEmailAddress");
  console.log("User email: ", email);
} catch (error) {
  console.error("Error: ", error);
}

Parameters

calcappIframe.getValue(calculationName,
                       variableName,
                       propertyName,
                       app)

calcappIframe.getValues

Retrieves multiple values from an embedded Calcapp app in a single call. This is much more efficient than calling getValue multiple times.

try {
  const values = await calcappIframe.getValues([{
    calculationName: "MainScreen",
    variableName: "Field1"
  }, {
    calculationName: "MainScreen",
    variableName: "Field1",
    propertyName: "visible"
  }]);
  console.log("Field value: ", values[0]);
  console.log("Field visible: ", values[1]);
} catch (error) {
  console.error("Error: ", error);
}

This library communicates through message passing with the app hosted by an iframe element. As such, retrieving multiple values through this function is far more efficient than repeatedly invoking the getValue function.

Each array element specifies a value to retrieve using the same parameters as getValue. See the getValue documentation for details on Calcapp’s data structure.

Parameters

calcappIframe.getValues(soughtValues, app)

calcappIframe.subscribeToNewHeight

Subscribes to height change events from an embedded Calcapp app. Returns a function that, when called, cancels the subscription.

Height changes occur when:

• The app loads.
• Users navigate to different screens.
• Field visibility changes based on user input.

For automatic iframe resizing, use manageHeight instead.

Example

const unsubscribe = calcappIframe.subscribeToNewHeight((newHeight,
                                                        iframe) => {
  console.log("New height: ", newHeight);
});

// Later, to stop listening:
unsubscribe();

Parameters

        calcappIframe.subscribeToNewHeight(listener, app)

calcappIframe.manageHeight

Automatically adjusts the iframe height to match the embedded app’s height. Returns a function that stops the automatic management when called.

The app typically changes its height in response to the user navigating to a new screen or entering a value in a field such that a different field is made visible.

This function uses a mutation observer to automatically stop watching the height of an app when the iframe element hosting it is removed.

Options

Configure behavior with an options object:

• minimumHeight — Minimum iframe height in pixels.
• maximumHeight — Maximum iframe height in pixels.
• extraHeight — Extra pixels to add (default: 16).

About extraHeight: Embedded apps and host pages communicate asynchronously. When the height of an app changes using an animation, this library animates the iframe element to match the app height. When the app becomes larger, the iframe element may lag behind the embedded app and momentarily not be large enough to fully contain it. As a result, a scrollbar may appear, only to disappear a split second later when the iframe element is properly sized.

To prevent this, iframe elements should be a number of pixels taller than the app. The extraHeight property adds these pixels to the app’s height. The default value is 16 pixels, which is appropriate for most apps. For a perfectly snug fit, set this value to zero.

Declarative usage

Add attributes to the iframe element for automatic setup:

<iframe src="..."
        calcapp-managed-height
        calcapp-managed-height-minimum="200"
        calcapp-managed-height-maximum="800"
        calcapp-managed-height-extra="20"></iframe>

Use these attributes for the corresponding options:

• calcapp-managed-height-minimum for the minimumHeight option.
• calcapp-managed-height-maximum for the maximumHeight option.
• calcapp-managed-height-extra for the extraHeight option.

Use data- prefixes if needed: data-calcapp-managed-height, etc.

Note: When used declaratively, this function is called by this library in response to the DOMContentLoaded event firing on the window object. As such, declarative usage only works for iframe elements present when the page is initially loaded.

Example

const stopManaging = calcappIframe.manageHeight("abc123", {
  minimumHeight: 200,
  maximumHeight: 400,
  extraHeight: 50
});

// Later, to stop automatic height management:
stopManaging();

Parameters

calcappIframe.manageHeight(app, options)