Report post

Are you sure you want to report the post shown below? This will send an email to the ATVO administrators. Please include a short reason for reporting.

Users reporting for no reason may be locked out.

Post

Posted by Nick Thissen
on
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...