Script Transform
Script Transforms are special functions that are applied only on an existing binding. They take the result of a binding (or transform) as an input and produce a single output. This will allow you to manipulate a binding result using whatever python code you want.
When a script transform is first created it generates a template script with a few assumed input Arguments (see below). From this template you can write your own script and reference an incoming value as well as a few other parameters. It is assumed the custom script will end with a Return comment that is a single output value, dataset, document, or other type of data.
Arguments:
- self: A reference to the component this binding is configured on.
- value: The incoming value from the binding or the previous transform.
- quality: The quality code of the incoming value.
- timestamp: The timestamp of the incoming value as a java.util.Date
Return:
- Any single value of any data type. As with all other transforms, the type of data that is returned will overwrite the data type of the property that is being bound.
Using Complex Properties in Your Transform​
Any time you reference a complex component property (like an array or object), it will contain a Qualified Value(s). This means they have a quality code and timestamp attached to each piece of data. Using your script to access it will result in a Qualified Value but you can access the actual value manually using the .value() function. This means that fetching a complex property like an array must be looped through and converted manually if you want a basic array. For ease, the output of any binding or transform will automatically be stripped of quality and timestamp so you can use the value argument directly.
Example 1: Using the results of an array Property Binding in your script transform: You can reference the property value directly by calling the value parameter that is passed in.
Example 2: Fetching an additional array Property inside your Script Transform: You must manually convert the array property to a simple array.
Example Scripts​
A lot of the components in Perspective expect arrays or JSON structured data in order to display data, but several binding types return single values or datasets. In order to transform one into the other, you can add a Transform to the binding and fill in a script to change the data format. Here are a few examples of code that can be added to a Script Transform.
Don't forget to tab in correctly if you are copying scripts from this page. The Script Transform is a function (starts with "def") and every line of the code below should be tabbed in one from the edge.
These examples are not necessary with Tag History or Query binding types. For both of these, there is a dropdown setting at the bottom of the binding page that allows you to select the return type of DOCUMENT.
Dataset to Array of Objects​
This is a script to take a dataset and transform it into a json array. All header names will be included in the resulting structure. This type of array is expected on many Perspective components like the Table component.
# convert the incoming value data
pyData = system.dataset.toPyDataSet(value)
# get the header names
header = pyData.getColumnNames()
# create a blank list so we can append later
newList = []
# step through the rows
for row in pyData:
# create a new blank dictionary for each row of the data
newDict = {}
# use an index to step through each column of the data
for i in range(len(row)):
# set name/value pairs
newDict[ header[i] ] = row[i]
# append the dictionary to list
newList.append(newDict)
# return the results
return newList
Dataset to Array with Renamed Columns​
This is another script to take a dataset and transform it into a json array. In this example, you create the header names to be included in the resulting structure. This type of array is expected on many perspective components like the XY chart, Dropdown, etc.
# set the header names. For the XY chart, these must match the values in the series property.
header = ["Column 1", "Column 2"]
# convert the incoming value data
pyData = system.dataset.toPyDataSet(value)
# create a blank list so we can append later
newList = []
# step through the rows
for row in pyData:
# create a new blank dictionary for each row of the data
newDict = {}
# use an index to step through each column of the data
for i in range(len(row)):
# set name/value pairs
newDict[ header[i] ] = row[i]
# append the dictionary to list
newList.append(newDict)
# return the results
return newList
Sparkline Chart​
The data expected in a Sparkline chart is a bit different than other charts. Instead of having values paired with a timestamp, it just takes an array of values to draw in order. This is a script to take a Tag History binding, apply the Script Transform, and output only the values in an array. Make sure the Value Format dropdown is set to Dataset.
# convert the incoming value data
pyData = system.dataset.toPyDataSet(value)
# create a blank list so we can append later
newList = []
# step through the rows
for row in pyData:
# append the dictionary to list
if row[1] is not None:
newList.append(row[1])
# return the results
return newList