Attributes

Framework control attributes defined in Description.json must be initialized within Source.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": false,
      "defaultValueInternal": false
   }
]

Initialization

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".

/**
* @description Setter function for 'data-tchmi-value' attribute.
* @param {Boolean} valueNew the new value or null 
* @returns {void}
*/
FrameworkControlJs1.prototype.setValue = function (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 + ".onFunctionResultChanged", ["getValue"]);

   // 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.

The function "tchmi_equal" should be used to check for a change in value. The JS comparison operator "===" can only check the base 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".

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

Process-Methode

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.

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