Converter scripts explanation & examples

Posts: 785
Introduction
Converter scripts are scripts used to control the output of some databinding value and convert it into your desired format. There are many databindings available which return sensible values to display directly on a Label, but sometimes you may want to do some customization which goes beyond the data binding system. Converter scripts give you ultimate freedom to do this customization, at the cost of some complexity.

Instead of writing a very long post on the entire scripting system, this post focuses on some examples of how to use converter scripts. There are more uses for scripts but converter scripts are the most common and easiest to grasp.

The examples will use the C# language, though ATVO Theme Editor supports also VB.NET, Ruby, Python, Javascript and Lua.


Some examples when to use a converter script
Three common examples are:
  1. There is no direct databinding available for the property you want to display.
  2. The databinding is for a property that does not return text but something different (e.g. a "true/false" value or a complex object).
  3. The databinding returns text but you want to change it depending on some other condition(s).
For these cases a converter script can take the databinding value as input, and your script converts it into your desired text output.


How to create and apply a converter script
  1. Add a new Script to your theme. Select a sensible name and the desired language. The script will be created with a default template, which you will fill later.
  2. Find the Label on which you want to display the converted text.
  3. Make sure the correct Data Binding is selected, this will be the input to your script later. You can select multiple bindings as well but that is not explained here, please post for help if multiple inputs are required.
  4. In the Property grid under Data category, expand the Data Converter group.
  5. In the Script dropdown, select the script you created in step 1.
This Label is now using the selected script to convert its databinding value. Before the databinding is displayed, it is passed to your script and converted.


What to write in the script
The contents of the script depend entirely on your goal. Some examples are provided below. For now here is a brief explanation of the concept with the available inputs and the required output.

Converter scripts receive 4 inputs and must return 1 output value. One of the inputs (see below) is the raw databinding value that you want to convert. The remaining 3 inputs are additional values you can use to help your conversion, and are often not used. The output of your script should be the text you wish to display on the Label.

Inputs:
  • "item": the item in your theme that owns this script. Usually this is the Label on which you selected to use the converter script.
  • "value": the raw databinding value you are going to convert. This can be text but also other data types.
  • "parameter": an additional parameter value (text) you can supply next to where you select your script in the Data Converter.
  • "sim": a reference to the iRacing connection containing all telemetry and data available in "raw" format.


The default template explained
The default C# template looks like this:
using System;
using ATVO.ThemesSDK;
using ATVO.ThemeEditor.ThemeModels;
using ATVO.ThemeEditor.Scripting.DotNET;

namespace Scripts
{
public class test : IScript
{
public object Execute(ThemeContentItem item, object value, string parameter, ISimulation sim)
{
return value.ToString();
}
}
}


Ignore the first lines with "using" for now, these will be explained later. The major part to focus on is the section that starts with public object Execute. This is a function that takes the 4 inputs described above, and returns one single value (the text to display).

In the default template, it simply takes the raw databinding input ("value") and converts it to a string (in case it was not text format already). It basically does nothing, it is up to you to extend this script to make it return something more useful.



A simple example
Imagine you are databinding to the driver name and you wish to show only the first three letters of their name. This can be achieved with a simple converter script by using some common C# string manipulation (Substring selects a part of the string). In this example I first convert the databinding value to a string, then take only the first three letters and return those as the output:
using System;
using ATVO.ThemesSDK;
using ATVO.ThemeEditor.ThemeModels;
using ATVO.ThemeEditor.Scripting.DotNET;

namespace Scripts
{
public class test : IScript
{
public object Execute(ThemeContentItem item, object value, string parameter, ISimulation sim)
{
// Get databinding value as string:
string fullname = value.ToString();

// Take char 1 - 3
string firstpart = fullname.Substring(1, 3);

// Return that to display
return firstpart;
}
}
}



Converting more complex data types
The databinding system allows you to bind to certain "complex objects" which are like containers of information. An example is all information about the Driver (name, number, iRating, etc), or the Car (model, class, etc), or even the session result (start position, current position, current speed, etc). These cannot be displayed in a Label directly so you must use a converter script to access the desired property (or combination of properties) and display them.

As an example, suppose you wish to display the carnumber and name of a driver. Additionally, if the driver is in first position, you want to show the car name as well. This request combines several properties to display along with some logic that cannot fit in a single databinding, so a converter script must be used.

The required properties are: carnumber, driver name and driver results (position). These are available in what we call the entity session result binding, called "entitysessionresult_object". Before you can access the properties on it, you must tell the compiler the correct type of the databinding input, otherwise it cannot know what you are trying to do is correct. This is shown in the first part of the script:
using System;
using ATVO.ThemesSDK;
using ATVO.ThemeEditor.ThemeModels;
using ATVO.ThemeEditor.Scripting.DotNET;
using ATVO.ThemesSDK.Data.Results;

namespace Scripts
{
public class test : IScript
{
public object Execute(ThemeContentItem item, object value, string parameter, ISimulation sim)
{
// Bind to "entitysessionresult_object" value
// This puts the session result in the value as a type of IEntitySessionResult
// You must tell the compiler that this is the type you are expecting such
// that it knows what properties are available.

// Tell the compiler the value is of type IEntitySessionResult:
IEntitySessionResult result = (IEntitySessionResult) value;

// Combine carnumber and driver name
string number = result.Entity.Car.Number;
string name = result.Entity.CurrentDriver.Name;
string output = "[" + number + "] " + name; // Example output: [31] Nick Thissen

// Check if driver is in first place
if (result.Position == 1)
{
// If so, also add the car name
output = output + ", " + result.Entity.Car.Name; // Example: [31] Nick Thissen, Skip Barber
}

// Return the output
return output;
}
}
}



To be continued...
Edited (1 time)
Posts: 19
Can I send multiple databindings to a converter script? How do I handle them?

I want to do something like this: if databinding 1 is not zero, return databinding 1; else return databinding 2.
Posts: 785
Yes. I think you can just make the script accept the value as an object array rather than one object:
public object Execute(ThemeContentItem item, object[] value, string parameter, ISimulation sim)
{
var v1 = value[0];
var v2 = value[1];

//...
}


Or it also probably works if you just convert the object value to an object array:
public object Execute(ThemeContentItem item, object value, string parameter, ISimulation sim)
{
var values = (object[])value;
var v1 = values[0];
var v2 = values[1];

//...
}


I do think there is a requirement that you also return an object array with the same number of items as the input. So if you bind to 2 data bindings you need to return an object array of length 2, otherwise it will fail. Not sure why I added this restriction as it seems unnecessary. If you only need to return one of the data binding values, just return that one as the first value and the other (or null) as the second one, and in your Text property only print the first (macro "{0}").
Posts: 3
is there a way to script it to play a video like a commercial
Posts: 785
You can play a video with a simple action, no script needed. Just put a video in your theme and start/stop it with the Play Media actions to play it fullscreen. Or put it in a widget via Widget Video properties to place it somewhere in your theme.
converter converting example script Tutorial