Data For Building Blocks

There are several ways in which data may be passed to a building block, all of which serve different purposes:

  • Pins are used to pass data explicitly via an object flow into a block.
  • Instance parameters are parameterizations that apply for a specific building block instance, and are implemented as constant values.
  • Properties are values that can be indirectly passed to a building block via a central, static map with key / value pairs.

The differences among those three mechanisms are summarized in the following figure.

Pins Instance Parameters Properties
Constant value no yes changeable
Has default value n/a yes no
Scope local to block instance local to block instance shared with all block instances within an application
When values are set n/a block's instantiation before the values are used
Typical usage dynamic data data specific to a block instance configuration data of an application

Data Flows Through Pins

Here is an example of an object of type Email flowing via input pin send.

Double clicking the pin send will reveal the related Java class Email which contains, among others, the receiver address and email content. The values of these two fields are typically dynamic.

Instance Parameters

Instance parameters are parameters of a building block to which values can be assigned for each building block instance. These values are constant for this building block instance, but different instances of the same building block type may have different values.

All block types except application, shallow, and singleton blocks can have instance parameters.

The figure below shows an example of instance parameters.

  • There are two instances of block LED in the Red LEDs block.
  • Block LED has an instance parameter led of type int (notice the P symbol on the upper left of each block instance).
  • The parameter led of the upper block instance has value 0, the bottom one has value 1.

In this example, there are two LEDs. Both are red. But, they are accessible through different GPIO pins. The GPIO pins are represented as instance parameter.

Creating Instance Parameters

Instance parameters are specified in the Instance Paramters section on the Overview page.

Use the Add, Remove and Edit buttons to modify the list.

An instance parameter is specified with a name, a type, a default value, and a short description. All except description are mandatory. Supported types are Boolean, int, String.

Each instance parameter has a corresponding Java final variable (constant). The value of the variable is set when the block is instantiated. You should not change this variable and constructor manually.

Setting Instance Parameters

To set a value of an instance parameter in a block instance, do a right-click on the block instance and select Parameters and Generics….

You can change the value on the opened dialog.

If parameters are not edited, default values apply.

Note that parameter instances cannot be set with values declared in the surrounding block or application, the actual values have to be provided with the specific block instance.

Properties

Properties are mainly intended to pass configuration data into a building block that is specific to a certain application instance. This means properties of a building block are shared among all block instances that run in the same application instance.

Declaring Properties

To declare a property, create a constant in the Java class for a building block that has the name of the property with a unique key.

You can get the values of properties by using getProperty(String key) that has return type Object and is available in every block. Here is an example.

Setting Properties

Setting properties usually happens outside of the building block that declared the properties.

Before a building block uses its properties, they must be set by another part of the application. Usually, all properties used by the blocks of an application are set directly at application startup. To set a property, use the Java method setProperty(String key, Object value) of the building block base class. Use the reference to the key constant as key, and pay attention to set the expected type as value.