Attribute

Framework Control Attribute, die in der Description.json definiert werden, müssen innerhalb der Control.js/ts 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": null,
      "defaultValueInternal": false
   }
]

Initialisierung (TypeScript)

Die Deklaration von den Attributen erfolgt bei TypeScript als separate Zeile. Hier ist zu beachten, dass für diese Attribute der Datentyp festgelegt werden muss. Attribute werden im Lebenszyklus spät gesetzt, daher sollten diese zusätzlich undefined als möglichen Datentyp erhalten. Das Schlüsselword protected gibt hier an, dass auf diese Variablen nur abgeleitete Controls, nicht jedoch fremde Controls zugreifen dürfen.

protected __value: boolean | undefined;

Initialisierung (JavaScript)

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.

TypeScript:

/**
* 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:

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

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.

Hält das Attribut ein Objekt (also kein Basisdatentyp wie string, boolean, number) so kann dieses optional auch Symbolausdrücke enthalten.

Eine genaue Beschreibung der Anpassungen für diesen Fall ist im Artikel Handling von Symbolausdrücken in Objekten nachzulesen.

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.

TypeScript:

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

JavaScript:

/**
* Getter function for 'data-tchmi-value' attribute.
* @returns {boolean}
*/
getValue () {
   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.

TypeScript:

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

JavaScript:

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