Attribute

Framework Control Attribute, die in der Description.json definiert werden, müssen innerhalb der Source.js initialisiert und die dazugehörigen Setter-, Getter- und Process-Methoden implementiert werden. Die Setter- und Getter-Methoden bieten einen zentralen Zugriff auf das Attribut.
Die nachfolgenden Beispiele beziehen sich auf das folgende Attribut, welches in der Description.json unter „attributes“ definiert wird:

"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
   }
]

Initialisierung

Die Initialisierung von den Attributen erfolgt in dem Konstruktor des Framework Controls. Die Initialisierung an dieser Stelle ist nicht erforderlich (Variablen ohne Schlüsselwort werden in JavaScript bei der Benutzung automatisch initialisiert), wird aber zur besseren Übersichtlichkeit empfohlen.

this.__value = undefined;

Member-Variablen und Funktionen, auf die von außen kein Zugriff besteht, werden mit dem Präfix „__“ versehen.

Setter-Methode

Die Setter-Methode eines Attributes wird nur bei Attributen benötigt, die nicht auf „readOnly“ gesetzt sind (alle Attribute, die über das Engineering gesetzt werden können). Die Setter-Methode muss wie die Definition in dem „propertySetterName“ benannt werden.

/**
* @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();
};

Innerhalb der Setter-Methode wird zunächst der übergebene Parameter vom Engineering mit Hilfe der Framework-API-Funktion „ValueConverter“ in den zu erwarteten Datentyp konvertiert. Wird dem ValueConverter ein ungültiger Wert übergeben oder schlägt die Konvertierung des Wertes fehl, liefert die Funktion „null“ zurück. In diesem Fall wird der DefaultValueInternal aus der Description.json verwendet. Anschließend wird überprüft, ob eine Wertänderung zu dem letzten gespeicherten Wert des Attributes auf der Member-Variablen stattgefunden hat. Wenn keine Wertänderung stattgefunden hat, wird der Setter verlassen. Hat eine Wertänderung stattgefunden, wird der Wert der Member-Variablen für das Attribut überschrieben und das System informiert, dass eine Wertänderung stattgefunden hat. Abschließend wird die Process-Methode für den Wert aufgerufen, in der auf die Wertänderung reagiert wird.

Die Überprüfung auf eine Wertänderung sollte mit der Funktion „tchmi_equal“ erfolgen. Der JS-Vergleichsoperator „===“ kann nur die JavaScript Basisdatentypen prüfen und keine komplexen JSON-Objekte.

Getter-Methode

Die Getter-Methode eines Attributes liefert den aktuellen Wert des Attributes zurück und wird für jedes Attribut benötigt. Die Getter-Methode muss wie die Definition in dem „propertyGetterName“ benannt werden.

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

Process-Methode

Die Process-Methode wird immer aufgerufen, sobald eine Veränderung des Attributwertes stattgefunden hat. In der Process-Methode soll die Reaktion auf die Wertänderungen implementiert werden. So können z. B. in Abhängigkeit eines booleschen Wertes Elemente sichtbar bzw. unsichtbar geschaltet oder auf Basis eines übergebenen JSON-Objektes dynamisch eine Liste aufgebaut werden.

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