A Beginner's Guide to Dataflows

Introduction

The Olympe platform is based on the concept of Data Flow which is somewhat similar to cells in a spreadsheet. When one cell is modified all cells that are depending on the value in that cell are automatically recalculated, which triggers more updates if other cells depend on those freshly updated cells and so on and so forth until nothing needs recalculating any more. Data flows take that concept and abstract it to be in the form of a graph of nodes instead of a grid of cells. Nodes hold a value and can have a processing function with one or more entry values. These entry values can come from other nodes.

CODE data flow API is available in here.

Getting the code

To try by yourself and complete the exercises, you'll need to clone the tutorial project.

git clone ssh://git@gitlab.caas.olympe.cloud:30001/training/tutorial_df.git
cd tutorial_df
git checkout Step-0
npm install
gulp

You can test your setup by loading following page: http://localhost:8888

Example 1 - Displaying the time as a data flow

The first step is to display the current time. Using getNow() function from the Time Manager and format method should help you.

Note: A typical date format is "ddd DD MMM YYYY HH:mm:ss".

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-1
gulp

If gulp is running you can just reload following page to test your code: http://localhost:8888

/**
 * @override
 */
render(dimension) {
    const mainLayout = new olympe.ui.std.AbsoluteLayout(dimension);
    const { Label } = olympe.ui.std;

    const label = new Label(dimension);
    label.setText(/* INSERT SOME CODE HERE */);
    label.setFontSize(32);
    label.setTextHorizontalAlign(olympe.ui.common.HorizontalAlign.CENTER);
    label.setTextVerticalAlign(olympe.ui.common.VerticalAlign.MIDDLE);
    mainLayout.appendChild(label, 'label');

    return mainLayout;
}

The code above generates following data flow:

Example 2 - Let's complicate things

Now we are going to add an extra data flow: the display format of the time. This can be done by reading the value of a text field.

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-2
gulp

In the code below, you'll need to use the content of the text field when formatting the date.

render(dimension) {
    const mainLayout = new olympe.ui.std.AbsoluteLayout(dimension);
    const { Vector2 } = olympe.df;
    const { Label, TextField } = olympe.ui.std;

    const textField = new TextField(new Vector2(300, 30))
        .setPosition(new Vector2(10, 10))
        .setText('ddd DD MMM YYYY HH:mm:ss');
    const label = new Label()
        .setText(this.timeManager.getNow().format(/* INSERT SOME CODE HERE */))
        .setFontSize(32)
        .setTextHorizontalAlign(olympe.ui.common.HorizontalAlign.CENTER)
        .setTextVerticalAlign(olympe.ui.common.VerticalAlign.MIDDLE)
        .setPosition(new Vector2(10, 80));

    mainLayout.appendChild(textField, 'textField');
    mainLayout.appendChild(label, 'label');

    return mainLayout;
}

The code above generates following data flow:

Example 3 - Getting mouse position as a data flow

Mouse position is also provided as a data flow in Olympe. Let's include it in our example. In this exercise, you'll need to get the position of the mouse (you should look at methods available on the mainLayout object).

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-3
gulp

render(dimension) {
    const mainLayout = new olympe.ui.std.AbsoluteLayout(dimension);
    const mousePos = /* INSERT SOME CODE HERE */;
    const { Vector2 } = olympe.df;
    const { Label, TextField } = olympe.ui.std;

    const textField = new TextField(new Vector2(300, 30))
        .setPosition(new Vector2(10, 10))
        .setText('ddd DD MMM YYYY HH:mm:ss');
    const label = new Label()
        .setText(this.timeManager.getNow().format(textField.getText()))
        .setFontSize(32)
        .setTextHorizontalAlign(olympe.ui.common.HorizontalAlign.CENTER)
        .setTextVerticalAlign(olympe.ui.common.VerticalAlign.MIDDLE)
        .setPosition(/* INSERT SOME CODE HERE */);

    mainLayout.appendChild(textField, 'textField');
    mainLayout.appendChild(label, 'label');

    return mainLayout;
}

The code above generates following data flow:

Example 4 - Math operation

This example illustrates how chaining mathemical operations in order to convert fahreneit into celsius. The goal is to implement following formula using data flows: Tc = (Tf - 32) * 5/9

You'll need to transform the result of the text field into a number and then apply mathematical operations.

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-4
gulp

render(dimension) {
    // ...
    const label = new Label()
        .setText(/* INSERT SOME CODE HERE */)
    //...
}

The code above generates following data flow:

Example 5 - Transforming a flow

This example shows how data flows can be transformed to generate a new flow. The goal is to create a data flow which returns a color based on the celsius temperature data flow (blue if colder than 10, yellow if colder than 25, and red otherwise).

To perform this, you can use olympe.df.transformFlows function which takes in parameter:

• an array of data flows to use
• a function which receives the resolved data flows in parameter and return the value of the new data flow
• the type of the new data flow

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-5
gulp

render(dimension) {
    // ...
    const tempInC = textField.getText().toONumber().minus(32).mul(5 / 9));
    const color = olympe.df.transformFlows(
        [/* INSERT SOME CODE HERE */],
        t => {
            /* INSERT SOME CODE HERE */
        },
        olympe.df.Color
    );
    label.setText(tempInC.toOString());
    label.setTextColor(color);
    //...
}

The code above generates following data flow:

Example 6 - Creating a flow

This example shows how a new data flow can be created. The goal is to create your own version of Time Manager getNow data flow. To to this, you need to use olympe.df.newFlowSource function which generates a new data flow. Any data flow has a method to update its value.

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-6
gulp

render(dimension) {
    // ...
    const time = olympe.df.newFlowSource(olympe.df.OString);
    setInterval(
        () => {
            const now = new olympe.df.ODateTime(moment());
            const s = olympe.df.oString(`${now.getHours()}:${now.getMinutes()}:${now.getSeconds()}`);

            /* INSERT SOME CODE HERE */
        },
        1000
    );

    const mainLayout = new olympe.ui.std.AbsoluteLayout(dimension);
    const { Label } = olympe.ui.std;

    const label = new Label(dimension);
    label.setText(time.getFlow());
    //...
}

Example 7 - Currency converter

This example shows how easy it is to create a real time currency converter which updates any field when one is changed. To perform this, you'll need to get the text of another text field, transform it into a number, apply the change rate. toFixed method should help you transforming your number to display it in a clean way.

Before starting, please clone step branch. The solution is available in branch Step-X-Solution:

git checkout Step-7
gulp

render(dimension) {
    // ...
    const CAD_TO_CHF = 0.811;
    const CHF_TO_EUR = 0.818;
    const EUR_TO_USD = 1.375;
    const USD_TO_GBP = 0.599;
    const GBP_TO_CAD = 1.829;
    
    CHFTextField.setText(/* INSERT SOME CODE HERE. TRANSFORM FROM CAD. */);
    EURTextField.setText(/* INSERT SOME CODE HERE. TRANSFORM FROM CHF. */);
    USDTextField.setText(/* INSERT SOME CODE HERE. TRANSFORM FROM EUR. */);
    GBPTextField.setText(/* INSERT SOME CODE HERE. TRANSFORM FROM USD. */);
    CADTextField.setText(/* INSERT SOME CODE HERE. TRANSFORM FROM GBP. */);
    // ...
}

Reading more about data flows

For more informations about Olympe data flows, please read Tutorial Introduction