Skip navigation

Skip to main content

On September 25th, 2024, we released v2 of the Apps SDK. To learn what’s new and how to upgrade, see Migration FAQ and Migration guide.
API reference
API reference

initAppElement

API reference for the initAppElement method.
This version of the API is in beta. Beta APIs are unstable and may change without warning. You can't release public apps using this API until it's stable.

Parameters

appElementConfigAppElementClientConfiguration<A>
REQUIRED

Options for creating an app element client.

Properties of appElementConfig
renderAppElementRenderer<A>
REQUIRED

Registers a callback that renders an app element based on the data it receives.

Parameters

appElementDataA
REQUIRED

The data the callback must use to render the app element.

Returns

An array of one or more elements to render as output of an app element.

AppElementRendererOutput

Returns

A client that provides methods for creating and managing the lifecycle of an app element.

addOrUpdateElementfunction

If an app element is selected, the element's data is overwritten and the element is re-rendered. Otherwise, the provided data is used to create a new app element.

Parameters

appElementDataA
REQUIRED

The data to attach to the app element. Existing data will be overwritten.

placementPlacement
OPTIONAL

The position, dimensions, and rotation of the app element.

Properties of placement
topnumber
REQUIRED

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber
REQUIRED

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
widthnumber
REQUIRED

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

Returns

Promise<void>

addElementfunction

Adds a new app element to the design.

Parameters

optsAppElementOptions<A>
REQUIRED

The data and placement of the app element.

Properties of opts
dataA
REQUIRED

The data to attach to the app element.

placementPlacement
OPTIONAL

The position, dimensions, and rotation of the app element.

Properties of placement
topnumber
REQUIRED

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber
REQUIRED

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
widthnumber
REQUIRED

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

Returns

Promise<void>

registerOnElementChangefunction

A callback that runs when:

  • the app element is created
  • the app element's data is updated
  • the user selects an existing app element

Parameters

handlerAppElementChangeHandler<A>
REQUIRED

The callback to run when the app element changes.

Parameters

appElementobject | undefined
REQUIRED

Information about the app element that was changed.

Properties of appElement
dataA
REQUIRED

The app element data in its most recent state.

versionnumber
REQUIRED

The version number of the app.

updatefunction
REQUIRED

Function to update the app element data.

Parameters

optsAppElementOptions<A>
REQUIRED

Used to add or update an app element to the design. The update function is provided in the AppElementChangeHandler callback (registerOnElementChange).

Properties of opts
dataA
REQUIRED

The data to attach to the app element.

placementPlacement
OPTIONAL

The position, dimensions, and rotation of the app element.

Properties of placement
topnumber
REQUIRED

The distance from the top edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
leftnumber
REQUIRED

The distance from the left edge of the container, in pixels.

  • The pixels are relative to their container.
  • Minimum: -32768
  • Maximum: 32767
widthnumber
REQUIRED

A width, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
heightnumber
REQUIRED

A height, in pixels.

  • The pixels are relative to their container.
  • Minimum: 0
  • Maximum: 32767
rotationnumber
OPTIONAL

A rotation, in degrees.

  • Minimum: -180
  • Maximum: 180

Returns

Promise<void>

Returns

void

Returns

void