[ Previous: Abstracting complexity ] [ Up: Introductory Tutorials ] [ Next: Making choices ]

Introduction

Often when building a Workspace workflow, it is necessary to perform a calculation in order to modify a data value. For example, you may want to halve a number, calculate an average or modify a string with a regular expression. Workspace provides a very simple operation which allows these types of calculations to be done by directly entering a formula or script.

By the end of this tutorial, you will:

Know how and when to create a RunQtScript operation
Understand the basics of QtScript

Just in case you get stuck, two sample workflows sample workflow 1 and sample workflow 2 have been provided for you.

The RunQtScript operation

The purpose of our very simple script is to take two numbers and raise one to the power of the other. The first thing we need to do is create a new workflow with a RunQtScript operation in it:

From the File menu, select "New Workspace" to create a new workflow.
From the Operation Catalogue, drag a RunQtScript operation onto the canvas. Display the RunQtScript operation's input and output ports and you will see one input (in addition to the input and output Dependencies): – Script: The script that this operation will use when it is run.

Creating the RunQtScript operation

Now, you may note that none of these inputs have numeric data types, yet we need two numbers in order for our script to work! The QtScript operation allows us to dynamically add inputs and outputs for our needs. To do this:

Click on the operation's "extra customisations" indicator to bring up the dialog we want.

Opening the Properties dialog
On the Inputs side, click the Add button twice. This will create two new rows in the inputs list.
Double click each input row to rename it. The inputs should be named "a" and "exp".

Creating the script operation inputs
On the Outputs side, click the Add button once.
Double click the new output to rename it, entering the text "value".

Creating the script operation output
Click the OK button to accept the changes.
Display the RunQtScript operation's input and output again, and this time note that there are now two new inputs and one new output, each corresponding to the items we just added.

The updated RunQtScript operation
Next, click on the RunQtScript operation to select it and you will see in the Operation Editor that we can enter the value of the Script, a and exp inputs. The data type of the new inputs is QVariant. QVariant is a special data type which can be any primitive data type, such as an integer, a decimal or a string. In some cases, even more complex objects with their own properties can be converted to QVariant. This means that almost any datatype from the workflow can be connected to one of these variables without having to explicitly configure any conversion.

RunQtScript Operation Editor

Let's enter our script as: value = Math.pow(a, exp);
At this point we can enter some values in the Operation editor for a and exp, enter 10 and 2 respectively.

Note: The semicolon is not actually required if you only have one-line in the script. It's displayed here to help you remember that for multi-line scripts, you're going to need to put semi-colons at the end of each line. The script itself must be written in, as you might expect, Qt Script.

Without going into too much detail, QtScript is an implementation of the ECMAScript standard (Javascript is the well-known implementation). For the programmers out there, this means that anything that can be done in Javascript can be done with a RunQtScript operation,
Now add a QLineEdit to display the operation's output called value. To do this right click on the output and select "Display with QLineEdit" from the menu.

Display value with a QLineEdit widget
Create a WorkspaceOutput attached to the output calledvalue.
Now run your workflow and the results should look something like this.

Executing a simple script

The RunQtScript, QVariant and Data type conversation

The output of our operation is a QVariant (as are two of the inputs). In almost all situations you can safely ignore this fact as a QVariant can hold many different types and can be safely converted to many different types. However, we are now going to take a small aside now and demonstrate a couple of concepts related to QVariants and data type conversions.

In the Operation Catalogue, find the operation called LogText and add it to the canvas. Connect the value output of the RunQtScript to the Text to Log input of the Log Text operation. And create a WorkspaceOutput. Your workflow should look like this:

Adding the LogText operation
The first item to notice is that the line connecting the RunQtScript and LogText operations is blue. The blue connection colour indicates that a type conversion is happening here, the QVariant output is being converted to a QString.
In the Operation Catalogue, find the operation called Variable and add it to the canvas. Connect the value output of the RunQtScript to the Variable input of the Variable operation. Add another LogText operation to the canvas and connect the Variable output to the LogText's Text to log input. And create a WorkspaceOutput. Your workflow should look like this:

Adding the Variable and second Log Text operation

Again please note that the lines connecting the:
- RunQtScript to the LogText operation is blue,
- RunQtScript to the Variable operation is blue and
- Variable to Log Text (1) is blue. The reason for the third blue line is that by default the output of a Variable is an integer.
Note
There are a times when you will want to use a Variable in your workflow, for example:
- Making sure the same value is set on multiple operation inputs
- Explicitly showing an important data value
- Explicitly converting one data type to another
By default the output of a Variable is an int
Now you can run your workflow, it will run successfully and you will see output such as this:

The value is displayed twice.

Of course you can change the type of a Variable, open the Variable's properties page and on the Data tab you can change the output to another type, for example QString:

Open Properties page.

You can observe that the blue line between the Variable and LogText has changed to black

Variable is now a QString

This concludes the first part of the scripting tutorial in which we managed to:

Create a RunQtScript operation
Write some basic QtScript code
Print text to the log
Learn about QVariant and converting data types

A complete sample workflow for this part of the tutorial can be found here

A more advanced RunQtScript operation

The previous example is very limited - before moving on to the next tutorial we would like to quickly demonstrate some more functionality to hopefully fuel your imagination, specifically we want to show how to:

Define your own functions inside a QtScript operation
Access QtScript datatypes
Use QtScript functionality such as regular expressions
Write to the Log window

Now the following example is highly contrived, both to demonstrate all these capabilities and also to save space. Hence there is no validation or error checking, so please do not take this as an example of good coding practice and I am sure we could have many debates about coding style too.

Our example QtScript is going to do a few things:

Read a person's name as a string in the format: firstname familyname
Write the execution start time to the Log window
Modify the name to be in the format familyname, firstname using a regular expression
Write the details of the transformation to the Log window
Pass the new name value on to the next operation in the workflow via an output

So the first steps are:

Create a new workflow from the file menu
Add a RunQtScript operation to the canvas
Add an input to this operation called name
Add an output to this operation called result

The Operation's property dialog should look something like this:

Add result output

Now, enter the following code in the "Script" input for the operation:

function familynameFirst(x) 
{
  var re = /(\w+)\s(\w+)/;
  var y = x.replace(re, "$2, $1");
  return y;
}

print(Date().toString() + "\n");

var output = "Converted: \"";
output += name;
output += "\" to \""
result = familynameFirst(name);
result = result.toUpperCase();
output += result;
output += "\"\n";
print(output);

As we said previously, we could debate the coding style/etc. of this example but the point here is really to show the following functionality:

Definition of a function, i.e. familynameFirst
Accessing QtScript functionality such as regular expressions
Accessing QtScript Datatypes such as Date (and accessing a member such as toString()
Declaring variables of QtScript datatypes using var
Calling our user defined function and passing inputs/parameters
Writing to the Log windows with print()
Assigning values to our output parameters

Finally, we need to do a few more steps:

Enter a name in the format firstname familyname (or any two words really) into the name input of the RunQtScript operation, we used Joe Bloggs in our example
Use a LogText operation to log the result output of the RunQtScript operation
Add a WorkspaceOutput to the LogText output dependency

Now run your workflow and you should see something like this:

Take some time to play around with the RunQtScript operation and see what kinds of refinements you can make. For more information on the RunQtScript operation, see the RunQtScript operation documentation. For a language reference, take a look at the ECMAScript Reference.

Tutorial Summary

For more detailed information about scripting in Workspace, check out the following pages:

Next Steps

The next tutorials in this series are: