Attributes

Framework control attributes defined in Description.json must be initialized within Control.js, and the corresponding setter, getter and process methods must be implemented. The setter and getter methods provide central access to the attribute.
The following examples refer to the following attribute, which is defined in Description.json under "attributes":

"attributes": [
   {
      "name": "data-tchmi-value",
      "propertyName": "Value",
      "propertySetterName": "setValue",
      "propertyGetterName": "getValue",
      "displayName": "Value",
      "visible": true,
      "themeable": "Standard",
      "displayPriority": 10,
      "type": "tchmi:general#/definitions/Boolean",
      "category": "Value",
      "description": "",
      "readOnly": false,
      "bindable": true,
      "heritable": true,
      "defaultValue": null,
      "defaultValueInternal": false
   }
]

Initialization (TypeScript)

The declaration of the attributes is implemented as a separate line in TypeScript. Note that the data type must be defined for these attributes. Attributes are set late in the life cycle, so they should have undefined as a possible additional data type. The keyword protected specifies that only derived controls may access these variables, but not foreign controls.

protected __value: boolean | undefined;

Initialization (JavaScript)

The attributes are initialized in the constructor of the framework control. Initialization is not required here (variables without keywords are automatically initialized in JavaScript when used), but is recommended for better clarity.

this.__value = undefined;

Member variables and functions that cannot be accessed from outside are prefixed with "__".

Setter method

The setter method of an attribute is only required for attributes that are not set to "readOnly" (all attributes that can be set via Engineering). Like the definition, the setter method must be named in the "propertySetterName".

TypeScript:

/**
* @description Setter function for 'data-tchmi-value' attribute.
* @param valueNew the new value or null 
*/
public setValue(valueNew: boolean | null): void {
   // convert the value with the value converter
   let convertedValue = TcHmi.ValueConverter.toBoolean(valueNew);

   // check if the converted value is valid
   if (convertedValue === null) {
      // if we have no value to set we have to fall back to the defaultValueInternal from description.json
      convertedValue = this.getAttributeDefaultValueInternal('Value') as boolean;
   }

   if (tchmi_equal(convertedValue, this.__value)) {
      // skip processing when the value has not changed
      return;
   }

   // remember the new value
   this.__value = convertedValue;

   // inform the system that the function has a changed result.
   TcHmi.EventProvider.raise(this.__id + '.onPropertyChanged', { propertyName: 'Value' });

   // call process function to process the new value
   this.__processValue();
}

JavaScript:

/**
* @description Setter function for 'data-tchmi-value' attribute.
* @param {boolean} valueNew the new value or null 
* @returns {void}
*/
setValue(valueNew) {
   // convert the value with the value converter
   var convertedValue = TcHmi.ValueConverter.toBoolean(valueNew);

   // check if the converted value is valid
   if (convertedValue === null) {
      // if we have no value to set we have to fall back to the defaultValueInternal from description.json
      convertedValue = this.getAttributeDefaultValueInternal('Value');
   }

   if (tchmi_equal(convertedValue, this.__value)) {
      // skip processing when the value has not changed
      return;
   }

   // remember the new value
   this.__value = convertedValue;

   // inform the system that the function has a changed result.
   TcHmi.EventProvider.raise(this.__id + '.onPropertyChanged', { propertyName: 'Value' });

   // call process function to process the new value
   this.__processValue();
}

Within the setter method, the parameter that was passed is first converted into the expected data type by Engineering using the framework API function "ValueConverter". If an invalid value is passed to the ValueConverter or if the conversion of the value fails, the function returns "null". In this case the DefaultValueInternal from Description.json is used. The system then checks whether a value change to the last stored value of the attribute on the member variable has taken place. If no value change has taken place, the setter is exited. If a value change has taken place, the value of the member variable for the attribute is overwritten and the system is notified that a value change has taken place. Finally, the Process method is called for the value in which the response to the value change takes place.

If the attribute contains an object (i.e. no base data type such as string, Boolean, number), it can optionally contain symbol expressions.

A detailed description of the adjustments for this case can be found in the article Handling of symbol expressions in objects.

The function "tchmi_equal" should be used to check for a change in value. The JS comparison operator "===" can only check the basic JavaScript data types but not complex JSON objects.

Getter method

The getter method of an attribute returns the current value of the attribute and is required for each attribute. Like the definition, the getter method must be named in the "propertyGetterName".

TypeScript:

/**
* @description Getter function for 'data-tchmi-value' attribute.
*/
public getValue () {
   return this.__value;
}

JavaScript:

/**
* @description Getter function for 'data-tchmi-value' attribute.
* @returns {boolean}
*/
getValue () {
   return this.__value;
}

Process method

The Process method is always called when the attribute value has been changed. The response to the value changes is to be implemented in the process method. For example, depending on a Boolean value elements can be switched visible or invisible, or a list can be created dynamically based on a transferred JSON object.

TypeScript:

/**
* @description Processor function for 'data-tchmi-value' attribute.
*/
protected __processValue() {
   // process actions with Value
   // ...
}

JavaScript:

/**
* @description Processor function for 'data-tchmi-value' attribute.
* @returns {void}
*/
__processValue() {
   // process actions with Value
   // ...
}