The payloadhosting.js script acts as a bridge between a custom-built UI and the underlying VDF model, handling data exchange, automatic field bindings, and event-driven updates.

Initialization

• The PayloadHosting object is the core of the script.

• The vizrt.PayloadHosting.initialize() function connects the HTML document to the Template Builder host and fetches the current template payload.

• If a callback function is provided, it is executed once the payload is ready.

• The script automatically binds HTML elements to payload fields using element IDs with a field_ prefix , for instance <input id="field_headline>, has automatically a bi-directional connection to the fieldheadline.

Accessing the VDF Payload (Data)

• The VDF payload holds the actual data entered into the template (for example, headlines, images, and other content).

• The script allows reading and modifying payload values but does not modify the model structure.

• Key methods:

  • getFieldText(fieldPath): Retrieves a text value from the payload.

  • getFieldXml(fieldPath): Retrieves XML content from the payload.

  • setFieldText(fieldPath, value): Updates a field’s text value.

  • setFieldXml(fieldPath, xmlString): Updates XML content in a field.

• While the script reads field definitions from the model (for example, checking if a field exists or is a list), it does not modify the model schema.

• Example: isListField(fieldPath) checks if a field is a list, but does not create or change the list definition.

Event-Driven Updates

The script listens for changes in the payload and updates the UI dynamically.

• Event listeners can be registered using:

  vizrt.payloadhosting.addEventListener("payloadchange", callbackFunction);

• This allows custom UI components to react to external changes in real time.

Automatic and Manual Bindings

By default, payloadhosting.js automatically maps input elements (<input>, <textarea>, <select>) to payload fields.

This can be disabled if manual control is required:

Handling Lists and Complex Fields (Tables)

The script supports list fields, allowing users to manage repeating elements in a template.

• Methods for managing lists:

  • addListFieldItem(fieldPath): Adds an item to a list.

  • removeListFieldItem(fieldPath, index): Removes an item from a list.

  • getListFieldLength(fieldPath): Returns the number of items in a list.

• A fieldPath is a string that describes the location of a field in the payload.

  • Top-level field: "myList" (if myList is a list field).

  • Nested field: "container/myList" (if myList is inside container).

  • List item reference: "myList/#0" (first item in myList).

  • Field inside a list item: "myList/#2/name" (the name field inside the third item of myList).

• Lists in payloadhosting.js can effectively be used as tables because each list item can contain multiple sub-fields, similar to rows and columns in a table.

  • Each list item is a row.

  • Each sub-field inside a list item is a column.

Invoking Native Field Editors

The payloadhosting.editField(fieldPath, editRequestParameters?) method allows a custom HTML UI to trigger the built-in Template Builder editor for a specific field in the payload. This is especially useful for editing complex data types, such as images, videos, or formatted text, using Template Builder’s native editor instead of standard HTML inputs.

Syntax:

Parameters:

• fieldPath (string, required): The path to the field in the payload that should be edited.

• editRequestParameters (optional): An object that provides additional options for the edit request, such as predefined values, constraints, or configurations for the editor.

Communication with the Host

The payloadhosting.js script communicates with the host application (Template Builder and Viz Pilot Edge) using the postMessage() API. Messages are exchanged between the custom UI and the host to update and retrieve data.

• Sending messages to the host: When changes occur in the payload, payloadhosting.js sends updates to the host using:

  this._host.postMessage({ type: "data_changed", changes: [...] }, getHostOrigin());

• Receiving messages from the host: The script listens for messages, such as new payload data, using an event listener:

  window.addEventListener("message", (event) => {

  if (event.data.type === "set_payload") {

  console.log("New payload received:", event.data.xml);

  }

  });

• Types of Messages

  • set_payload: The host sends updated payload data to the custom UI.

  • data_changed: The UI notifies the host of modifications made to the payload.

  • request_model_info: The UI requests the model schema from the host.

  • provide_model_info: The host provides the requested model schema.

Security and Data Validation

The payloadhosting.js script includes multiple security measures to ensure safe data handling and prevent unauthorized modifications:

• Safe Media Handling

  • It ensures URLs for media assets (for example, images and videos) are correctly formatted and not externally manipulated.

  • The function isSafeMediaType(type) checks whether a given media type is permitted.

• Field Access Control

  • The script restricts modifications to registered fields only.

  • Any attempt to update a non-existent or unauthorized field results in an error.

  • Functions like fieldExists(fieldPath) ensure a field exists before attempting modifications.

• Cross-Origin Communication Restrictions

  • The script ensures messages are only exchanged with the expected host origin using getHostOrigin().

  • Unauthorized sources attempting to send messages are ignored.

• Preventing Invalid Data

  • Input values are validated before being stored in the payload.

  • XML content for structured fields is parsed and checked before insertion using setFieldValueAsParsedXml().