Widget Code Structure

Widgets are implemented as anonymous classes that extend the HTMLElement class. The preferred approach is to extend SwimlaneElement, which itself extends LitElement and provides additional functionality for building rich, interactive record and report widgets in Turbine.

Swimlane publishes documentation and example code for its CDN-hosted widgets in the Swimlane Platform Custom Widgets library. Each widget page describes what the widget does and how to configure it. For example, see AI SOC Case Timeline. Use these pages as a reference when you customize a CDN-hosted widget.

Swimlane hosts some widgets on a content delivery network (CDN), so you can add them to a layout without copying their source code. Paste an import statement into the widget editor, extend the imported class, and override settings in setConfig().

// Widget documentation: https://swimlane.github.io/custom-widgets/cdn/ai-soc-case-timeline/ import CaseTimeline from 'https://widgets.swimlane.app/ai-soc-case-timeline/1/index.js'; export default class extends CaseTimeline { constructor() { super(); this.setConfig({ // override widget configuration parameters here }); } }

The version in the import URL controls which updates the widget receives:

/index.js (no version) – You receive every new version automatically.

/1/index.js – You receive new features and bug fixes within version 1.

/1.0/index.js – You receive bug fixes only.

/1.0.0/index.js – You receive no updates.

Each widget page in the Swimlane Platform Custom Widgets library describes the settings you can override.

Here is an example of the default widget with annotation added:

/** * Import `SwimlaneElement` class. * The `css`, `html`, and `svg` methods are also imported from `swimlane-element`. */ import { SwimlaneElement, css, html, svg } from '@swimlane/swimlane-element@2';/** * The `recordFrameTemplate` is a template helper function. See templates below. */ import { recordFrameTemplate } from '@swimlane/swimlane-element@2/lib/templates.js';/** * A Swimlane widget is implemented as an anonymous class which extends the `SwimlaneElement` class. */ export default class extends SwimlaneElement { /** * The `styles()` getter is a static class getter. It defines styles common to all widget instances. * This method does not have access to instance-specific properties like `record` or `report`. */ static get styles() { return [super.styles, css` .frame::after { content: "Record Output"; } `]; } /** * The `render()` method is an instance method scheduled by `LitElement` lifecycle events. * It must return a `lit-html` template. This method has access to `this.record` and `this.report`. */ render() { return recordFrameTemplate(html` <pre>${JSON.stringify(this.record, undefined, 2)}</pre> `); } }

Properties

SwimlaneElement defines the following properties:

this.record – Available to record widgets. An object containing key-value pairs for each field on the record.

this.report – Available to report widgets. An object with:

data: parsed result rows

rawData: unprocessed backend response

query: the report query

this.contextData – Available to all widgets. Contains contextual information:

application

currentUser

origin

token

Documentation on how LitElement handles properties and attributes can be found here.

Lifecycle

In addition to standard HTMLElement and LitElement lifecycle methods, SwimlaneElement includes:

resizedCallback() – Called when the widget is resized. By default, it calls requestUpdate() to trigger re-rendering.

Documentation of LitElement lifecycle methods and properties can be found here.

Events

Swimlane widgets can emit platform events using the following methods:

this.updateRecordValue(key, value): Updates a specific record field by key.

this.addComment(comment): Adds a comment to the record. This method returns a Promise, allowing follow-up actions to be chained: this.triggerButton(); }).catch(error => { console.error("Failed to add comment:", error); });

this.triggerButton(buttonId): Triggers a playbook button by its ID.

this.triggerSave(): Saves the current record. This method also returns a Promise, enabling safe sequencing of actions: this.triggerSave().then(() => { this.triggerButton(); }).catch(error => { console.error("Save failed:", error); });

Avoid using setTimeout() to delay follow-up actions. Use Promises to ensure actions happen after the save or comment completes successfully.

You can also perform multiple asynchronous actions in parallel using Promise.all():

Promise.all([ this.triggerSave(), this.addComment("Escalated to Tier 2") ]).then(() => { this.triggerButton(); });

Documentation on how to handle events in LitElement can be found here.

Value Emission Patterns

For single value fields (text/numeric/date fields, etc.) or single-select field types, simply emit the new value:

// value can be a string or number type this.updateRecordValue('field-key', 'new value');

For text and numeric list field types, emit an array of new values. If duplicate values exist, their ids get reused:

// value is an array of strings for text list, and numbers for numeric list this.updateRecordValue('field-key', ['First item', 'Third item']);

For multi-select field types (selects, radio buttons, checkboxes), emit an array of new values. Every element in the value must exist in the contextData:

// value is an array of strings this.updateRecordValue('field-key', ['First item', 'Third item']);// All values must be present in contextData. // For example: this.updateRecordValue('field-key', ["Fourth item"]) // ❌ ERROR

To add a comment, emit the new comment as a string:

this.addComment('comments-key', 'Hello World!');

Widget Code Structure

Widget Library and Examples

Use a CDN-Hosted Widget

Default Widget Example

Properties

Lifecycle

Events

Value Emission Patterns