Component Scripts

Component Scripts run on specific events for a single component instance. You configure them in the component's Settings panel under Actions, then select the event type and open the Script tab.

Event Types

Event	When it fires
onCreate	When the component is first created and rendered
onChange	When the component's value changes (user interaction or data update)
onData	When new data arrives from the data source
onTick	On a recurring timer interval
onFocus	When the component receives focus
onDblClick	When the component is double-clicked
onHover	When the mouse enters the component

How to Add a Component Script

1. Select the component in your display
2. Open the Settings panel
3. Expand Actions
4. Click the event type (e.g., onCreate, onChange)
5. Navigate to the Script tab
6. Write your script
7. Click Apply

Execution Context

Inside a component script, this refers to the component instance.

Component Properties

Property	Type	Description	Available on
this.settings.value	any	Current component value	Calendar, Text Area, Value
this.settings.format.customlabel	string	Label text	Label
this.selected	object / object[]	Selected channel(s)	Dropdown, Multiselect, Table, Tree
this.channels	object[]	All bound channels	All
this.requestItems	object[]	All data from channels	All
this.requestItems[i].lastval.y	any	Last data point value	All
this.requestItems[i].lastval.x	string	Last data point timestamp	All
this.item.engineering	boolean	Whether in engineering mode	All
this.settings.visualProperties	object	Visual styling (bgcolor, border, opacity)	All
this.settings.varnam	string	Component variable name	All
this.enabled	boolean	Whether the component is enabled	All

Global Properties (accessible from component scripts)

Property	Type	Description
this.$GTCService.rangeStart.string	date/string	Global time control start time
this.$GTCService.rangeEnd.string	date/string	Global time control end time
this.$GTCService.realtime	boolean	Global time control realtime mode
this.$currentUser.roles	object[]	Current user's role objects (id, nam)
this.$currentUser.det.isPresentationMode	boolean	Presentation mode toggle
this.$stateView.lock	boolean	View lock mode
this.$appThemes.themes	object[]	Available themes
this.$themeService	object	Theme service (changeTheme method)
this.$viewContext	object	View context (SetOptions/GetOptions)

Navigation functions (GoTo, Popup, etc.) are blocked during onCreate and onData events but available in all other events.

Interaction Functions

These functions can be called on components retrieved via getComponent():

Function	Parameters	Description	Available on
Select()	channels: object/object[]	Select items from available options	Dropdown, Menubar, Multiselect, Table, Timeframe, Tree
Search()	channels: object/object[]	Filter component data by element, timeframe, or tag search	All
Expand()	channels: object/object[]	Filter by retrieving children items	Asset Group, Dropdown, Table, Tree
Highlight()	channels: object[]	Select rows or highlight time range (requires startmsec/endmsec)	Line Chart, Profile View, SQC Chart, Table
SetChannels()	channels: string[]	Assign channels to a component	All
AddChannels()	channels: string[]	Add channels without replacing existing	All
SetTime()	channels: object/object[]	Update time range (requires startmsec/endmsec)	Bar Chart, Line Chart, XY Chart
SetStartTime()	time: Date/number/string	Set the start time	Asset Group, Line Chart, XY Chart
SetEndTime()	time: Date/number/string	Set the end time	Asset Group, Line Chart, XY Chart
SetQueryParameters()	params: object	Replace all query parameters (for SQL-based tags)	All
AddQueryParameters()	params: object	Add/update specific query parameters	All
Snapshot()	(none)	Retrieve current data (refresh)	All
panTo()	channels: object/object[]	Pan map to a marker location (requires lat/lng) — note the lowercase name	Map
show()	(none)	Make a hidden element visible	All
hide()	(none)	Hide a visible element	All
SetOptions()	options: any	Write a value into the option list — used with viewContext to carry a selection between displays	Uses viewContext
GetOptions()	(none)	Read the current option list — the counterpart to SetOptions	Uses viewContext
OpenBranch()	node: object	Deep-link a Tree to a node: scroll to it and expand the path, keeping the full hierarchy in view	Tree

This covers the functions you'll script most often. For the complete set — every consumer function and which components support each — see the Interaction Reference and Navigation Functions catalogs.

Examples

Interaction: Tree drives Table selection

In a tree's onClick script:

const table = getComponent('table');
table.Select(this.selected);

Interaction: Table drives Line Chart channels

In a table's onClick script:

const lc = getComponent('linechart');
lc.SetChannels(this.selected);

Interaction: Timeframe highlights Line Chart

In a timeframe's onClick script:

const lc = getComponent('linechart');
lc.Highlight(this.selected);

Set Line Chart time range from Button

In a button's onClick script:

const lc = getComponent('linechart');
// Set time range to last 24 hours
lc.SetStartTime(new Date(Date.now() - 86400000));
lc.SetEndTime(new Date());

SQL Query Parameters

In a table's onCreate script with a dataset tag:

this.SetQueryParameters({ unit: "A" });

With a user query tag (dynamic SQL):

const name = 'John Doe';
this.SetQueryParameters({
    query: `select * from users where name = ${name}`
});

Role-Based UI: Enable Button by Role

In a button's onCreate script — disable the button unless the user has the Supervisor role:

this.enabled = this.$currentUser.roles.some(
    role => role.nam === 'Supervisor'
);

Use onCreate so the role check runs as soon as the display loads. You can verify roles in User Profile > Roles or the Administration Panel.

Set Global Time Control from Calendar

In a calendar's onClick script:

// Ensure GTC realtime is disabled first
this.$GTCService.rangeStart.string = this.settings.value;

Toggle Realtime Mode from Button

In a button's onClick script:

this.$GTCService.realtime = !this.$GTCService.realtime;

Switch Theme from Button

In a button's onClick script:

const theme = this.$appThemes.themes.find(
    x => x.nam === 'EXAMPLE THEME'
);
this.$themeService.changeTheme(theme);

Pass Context Between Views

In a map's onClick script — save selection for the next view:

this.$viewContext.SetOptions(this.selected);

In the target view's dropdown onCreate script — retrieve the saved context:

const options = this.$viewContext.GetOptions();
this.Select(options);

Refresh Data After Write-Back

In a button's onClick script:

const table = getComponent('table');
await someWriteBackFunction();
table.Snapshot();

Tips

• Use onCreate for initialization logic — role checks, default values, query parameters
• Use onChange for user interaction — filtering, navigation, cross-component updates
• **onChange**fires on both user input and programmatic changes — avoid infinite loops
• Use onTick sparingly — frequent timers impact performance
• Navigation is blocked in onCreate and**onData** — use other events for GoTo, Popup, etc.
• Always enforce critical security on the backend — role-based UI is a convenience layer, not a security boundary

What's Next?

• Global Scripts — view-level scripts with access to all components
• Scripting Guide — overview and available functions reference
• Interaction Functions — producer → consumer scripting reference
• Navigation Functions — view-navigation scripting reference
• Passing Context — carry a selection between displays

Related

• Global Scripts — view-level scripts with full component access
• Scripting Guide — the scripting overview and function reference
• Inspecting a Component — find the property names to use