Security, Privacy, AI and CSR information for all Piano products now lives in one place. Explore our Compliance Center.
Subscriptions
English French
English French

Working with the tp.pianoWidgets Object

LIGHTWEIGHT TEMPLATES

Find, close, and measure the Lightweight Templates on your page from your own JavaScript.

The tp.pianoWidgets object lets you list the Lightweight Templates rendered on a page, remove them, and read render timing, so you can close a template from a RunJS card, an event handler, or any other custom JavaScript, and check how fast it rendered. Lightweight Templates are managed as individual widget instances, so you identify the widget first and then act on it.

Methods

tp.pianoWidgets.getWidgets()

Returns all Lightweight widgets currently rendered on the page.

Parameters

None.

Returns

Type

Description

Map

The rendered widgets, keyed by elementInstanceId. Each value is a widget object (see Widget objects below).

The Map can hold more than one widget, so choose the entry you need before you act on it. See Close a specific widget below.

Example

JavaScript
// List the instance IDs of all rendered widgets
const widgets = tp.pianoWidgets.getWidgets();
const ids = Array.from(widgets.keys());
console.log(ids);

tp.pianoWidgets.deleteWidget(elementInstanceId)

Removes a widget by its instance ID.

Parameters

Parameter

Type

Required

Description

elementInstanceId

string

Yes

The instance ID of the widget to remove. This is the key of the Map that getWidgets() returns.

Example

JavaScript
// Remove one widget by its instance ID
tp.pianoWidgets.deleteWidget("39db861f-773e-418c-9976-17a23e69afe0");

To remove every Lightweight widget on the page:

JavaScript
Array.from(tp.pianoWidgets.getWidgets().keys()).forEach(function (elementInstanceId) {
  tp.pianoWidgets.deleteWidget(elementInstanceId);
});

tp.pianoWidgets.getTelemetry()

Returns render timing data for the templates rendered on the page.

Telemetry is off by default. To turn it on, add ?pn_telemetry=true to the URL of the page and reload it. Without the parameter, getTelemetry() returns an empty array. For the on-page timing box and the other ways to read the results, see Telemetry.

Parameters

None.

Returns

Timing data that includes renderTime, the time from the start to the end of rendering a template.

Example

JavaScript
// Load the page with ?pn_telemetry=true, then run:
var telemetry = tp.pianoWidgets.getTelemetry();
console.log(telemetry);

Widget objects

Each key in the Map from getWidgets() is the elementInstanceId of a rendered widget, and each value is the widget object. For example, with one widget on the page:

JavaScript
Map(1) {
  "39db861f-773e-418c-9976-17a23e69afe0" => {
    applicationId: "[your-application-id]",
    elementId: "1f6fd202-9262-4bc4-9ae8-bb73d4cf0930",
    elementInstanceId: "39db861f-773e-418c-9976-17a23e69afe0",
    container: { selector: ".piano-widget-container" }
    // plus the methods listed in the table below
  }
}

Property

Type

Description

elementInstanceId

string

The ID of one rendered copy of that element on the page. Every widget has its own, and it is the key in the Map and the value deleteWidget() expects.

applicationId

string

Your Piano application ID (AID).

elementId

string

The ID of the template (element) that the widget renders. Widgets rendered from the same template share it.

container

object

The container the widget renders into.

container.selector

string

The CSS selector of that container.

destroy()

function

Removes this widget. It does the same as deleteWidget(), and is useful when you already hold a reference to the widget.

dispatchSignal, listen, listenOnce, listenerList, removeListener

function

Methods for sending and subscribing to widget signals.

Example:

JavaScript
// Remove every widget by calling destroy() on it
Array.from(tp.pianoWidgets.getWidgets().values()).forEach(function (widget) {
  widget.destroy();
});

Close a specific widget

If several widgets are on the page, find the one you want first, then remove it. To list the widgets on the page, log each widget's IDs:

JavaScript
tp.pianoWidgets.getWidgets().forEach(function (widget, elementInstanceId) {
  console.log("elementId:", widget.elementId, "| elementInstanceId:", elementInstanceId);
});

Copy the elementId of the widget you want to close, and use it in place of [your-element-id], including the square brackets. If no widget has that ID, the code does nothing.

JavaScript
const targetElementId = "[your-element-id]";

tp.pianoWidgets.getWidgets().forEach(function (widget, elementInstanceId) {
  if (widget.elementId === targetElementId) {
    tp.pianoWidgets.deleteWidget(elementInstanceId);
  }
});

To remove one specific widget, you can also pass its elementInstanceId to deleteWidget() directly.

Last updated: