Laufzeitfunktionen zum Anpassen von ThingWorx Widgets
In diesem Abschnitt werden die Funktionen beschrieben, die für Widgets zur Laufzeit verfügbar sind.
Widget-Lebenszyklus zur Laufzeit
• Wenn ein Widget zum ersten Mal erstellt wird, werden zur Laufzeit durch Aufrufen der runtimeProperties()-Funktion alle deklarierten Eigenschaften abgerufen.
Weitere Informationen finden Sie im Abschnitt Callbacks von Laufzeit zu Widget.
• Die Eigenschaftswerte, die in der Mashup-Definition gespeichert sind, werden in das Objekt geladen, ohne eine Funktion aufzurufen.
• Nachdem das Widget geladen wurde, aber bevor es auf dem Bildschirm gerendert wird, ruft die Laufzeit die renderHtml()-Funktion auf. In dieser Funktion geben Sie die HTML für das Objekt zurück. Die Laufzeit rendert die von der Funktion zurückgegebene HTML an der entsprechenden Stelle im DOM.
• Nachdem die HTML dem DOM hinzugefügt wurde, wird die afterRender()-Funktion aufgerufen. Bei Bedarf können Sie jQuery-Bindungen durchführen. An diesem Punkt können Sie die tatsächlichen DOM-Elemente referenzieren. Verwenden Sie beispielsweise den folgenden Code, um die DOM-Elemente zu referenzieren:
// note that this is a jQuery object
var widgetElement = this.domElement;
var widgetElement = this.domElement;
 |
Die Laufzeit ändert die ID des DOM-Elements. Es wird empfohlen, immer das jQuery-Objekt this.domElementId zu verwenden, um die ID des DOM-Elements abzurufen.
|
• Wenn Sie ein Ereignis definiert haben, das gebunden werden kann, können Sie das Ereignis auslösen, wie im folgenden Beispiel gezeigt:
var widgetElement = this.domElement;
// change ‘Clicked’ to be your event name
// you defined in your runtimeProperties
widgetElement.triggerHandler('Clicked');
// change ‘Clicked’ to be your event name
// you defined in your runtimeProperties
widgetElement.triggerHandler('Clicked');
• Wenn Sie über Eigenschaften verfügen, die als Datenziele gebunden sind, wird die updateProperty()-Funktion aufgerufen. Sie sollten das DOM direkt aktualisieren, wenn sich die geänderte Eigenschaft auf das DOM auswirkt. Wenn die Daten gebunden sind, ändert sich in den meisten Fällen das DOM.
• Wenn Sie über Eigenschaften verfügen, die als Datenquellen definiert und gebunden sind, können Sie die getProperty_{propertyName}()-Funktion aufrufen. Wenn Sie diese Funktion nicht definieren, wird der Wert zur Laufzeit aus dem Eigenschaftenbehälter abgerufen.
Laufzeit-APIs für Widgets
Auf die folgenden APIs kann über ein Widget im Kontext der Laufzeit zugegriffen werden:
• this.jqElementId – Dies ist die DOM-Element-ID des Objekts, nachdem das Widget auf der HTML-Seite gerendert wurde.
• this.jqElement – Dies ist das jQuery-Element.
• this.getProperty(name) – Ruft den Namen der Eigenschaft ab.
• this.setProperty(name,value) – Legt den Namen und den Wert der Eigenschaft fest.
• this.updateSelection(propertyName,selectedRowIndices) – Ruft diese Funktion auf, wenn das Widget die Eigenschaft in den ausgewählten Zeilen ändert. Diese Zeilen haben Daten, die an sie gebunden sind. Wenn Sie beispielsweise in einem Callback ein Ereignis wie onSelectStateChanged() definiert haben, rufen Sie die this.updateSelection(propertyName,selectedRowIndices)-API auf. Das System aktualisiert alle Widgets, die von den ausgewählten Zeilen abhängen.
Callbacks von Laufzeit zu Widget
Die folgenden Funktionen im Widget werden zur Laufzeit aufgerufen:
• runtimeProperties() [optional] – Gibt eine JSON-Struktur zurück, die die Eigenschaften des Widgets definiert
Optionale Eigenschaften sind:
|
Eigenschaft
|
Beschreibung
|
|---|---|
|
isContainer
|
Gibt an, ob eine Instanz des Widgets ein Container für andere Widget-Instanzen sein kann. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist fasle.
|
|
needsDataLoadingAndError
|
Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist fasle. Legen Sie die Eigenschaft auf true fest, wenn das Widget die standardmäßige Opazität von 25 % anzeigen soll, wenn keine Daten empfangen werden. Das Widget wird rot, wenn beim Abrufen der Daten ein Fehler auftritt.
|
|
borderWidth
|
Wenn das Widget einen Rand aufweist, legen Sie diese Eigenschaft auf die Breite des Rands fest. Die Eigenschaft unterstützt Sie bei einem pixelgenauen Entwurf während der Entwicklung und zur Laufzeit.
|
|
supportsAutoResize
|
Gibt an, ob das Widget die Größenänderung automatisch unterstützt. Die gültigen Werte sind true und false.
|
|
propertyAttributes
|
Wenn Sie über lokalisierbare STRING-Eigenschaften verfügen, listen Sie sie in dieser Eigenschaft auf.
Wenn beispielsweise TooltipLabel1 lokalisierbar ist, gilt Folgendes:
this.runtimeProperties = function () {
return { 'needsDataLoadingAndError': true, 'propertyAttributes': { 'TooltipLabel1': {'isLocalizable': true} } } }; |
• renderHtml() [erforderlich] – Die Funktion gibt das HTML-Fragment zurück, das zur Laufzeit auf dem Bildschirm platziert wird. Der Inhaltscontainer des Widgets, beispielsweise div, sollte eine angegebene Widget-Inhaltsklasse enthalten. Nachdem die Klasse angegeben wurde, wird das Container-Element an das DOM angehängt. Der Container ist unter Verwendung des jqElement und seine DOM-Element-ID in jqElementId verfügbar.
• afterRender() [optional] – Diese Funktion wird aufgerufen, nachdem das HTML-Fragment des Widgets in das DOM eingefügt wurde. Verwenden Sie this.domElementId, um die DOM-Element-ID abzurufen. Verwenden Sie das this.jqElement-Element, um das jQuery-DOM-Element abzurufen.
• beforeDestroy() [optional, aber sehr empfehlenswert] – Rufen Sie diese Funktion auf, wenn das Widget vom Bildschirm entfernt wird. Diese Funktion ermöglicht Ihnen Folgendes:
◦ Bindungen aufheben
◦ Jeden Datensatz mit .data() löschen
◦ Bibliotheken oder Plugins von Drittanbietern löschen, ihre Destruktoren aufrufen usw.
◦ Arbeitsspeicher freigeben, den Sie zugewiesen haben oder zurückhalten, indem Sie alle Ihre Variables auf null festlegen
◦ Sie müssen die DOM-Elemente innerhalb des Widgets nicht löschen, sie werden zur Laufzeit gelöscht.
◦ Löschen Sie das DOM nur, indem Sie das Argument DOMOnly zur Funktion hinzufügen.
|
|
Fügen Sie das Argument DOMOnly der Funktion hinzu, um Lazy Loading mit dem Widget zu verwenden.
|
• resize(width,height) [optional – nur nützlich, wenn Sie "supportsAutoResize: wahr" angeben] – Diese Funktion wird aufgerufen, wenn die Größe Ihres Widgets verändert wird.
Einige Widgets müssen dies nicht verarbeiten. Beispielswiese, wenn die Elemente des Widgets und des CSS automatisch skaliert werden.
Die meisten Widgets erfordern jedoch eine Verarbeitung, wenn sich die Widget-Größe ändert.
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) – Diese Funktion wird aufgerufen, wenn die ausgewählten Zeilen durch die Datenquellen geändert werden, die an sie mit der angegebenen Eigenschaft gebunden sind. selectedRows ist ein Array der tatsächlichen Daten und selectedRowIndices ein Array der Indizes der ausgewählten Zeilen.
|
|
Sie müssen diese Funktionalität definieren, um die vollständige selectedRows-Ereignisfunktionalität abzurufen, ohne das Widget "Liste" oder "Raster" binden zu müssen.
|
• serviceInvoked(serviceName) – Die Funktion wird aufgerufen, wenn ein von Ihnen definierter Dienst ausgelöst wird.
• updateProperty(updatePropertyInfo) – updatePropertyInfo ist ein Objekt mit der folgenden JSON-Struktur:
{
DataShape: metadata for the rows returned
ActualDataRows: actual Data Rows
SourceProperty: SourceProperty
TargetProperty: TargetProperty
RawSinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
SinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
converted to the defined baseType of the
target property [not implemented yet],
SelectedRowIndices: an array of selected row indices
IsBoundToSelectedRows: a Boolean letting you know if this
is bound to SelectedRows
}
DataShape: metadata for the rows returned
ActualDataRows: actual Data Rows
SourceProperty: SourceProperty
TargetProperty: TargetProperty
RawSinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
SinglePropertyValue: value of SourceProperty
in the first row of ActualDataRows
converted to the defined baseType of the
target property [not implemented yet],
SelectedRowIndices: an array of selected row indices
IsBoundToSelectedRows: a Boolean letting you know if this
is bound to SelectedRows
}
Für jede Datenbindung wird updateProperty() Ihres Widgets aufgerufen, wenn die Quelldaten geändert werden. Sie sollten updatePropertyInfo.TargetProperty prüfen, um zu bestimmen, welcher Aspekt des Widgets aktualisiert werden soll.
Es folgt ein Beispiel für ein Widget:
this.updateProperty = function (updatePropertyInfo) {
// get the img inside our widget in the DOM
var widgetElement = this.jqElement.find('img');
// if we're bound to a field in selected rows
// and there are no selected rows, we'd overwrite the
// default value if we didn't check here
if (updatePropertyInfo.RawSinglePropertyValue !==
undefined) {
// see which TargetProperty is updated
if (updatePropertyInfo.TargetProperty === 'sourceurl') {
// SourceUrl updated - update the <img src=
this.setProperty('sourceurl',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("src",
updatePropertyInfo.SinglePropertyValue);
} else if (updatePropertyInfo.TargetProperty ===
'alternatetext') {
// AlternateText updated - update the <img alt=
this.setProperty('alternatetext',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("alt",
updatePropertyInfo.SinglePropertyValue);
}
}
};
// get the img inside our widget in the DOM
var widgetElement = this.jqElement.find('img');
// if we're bound to a field in selected rows
// and there are no selected rows, we'd overwrite the
// default value if we didn't check here
if (updatePropertyInfo.RawSinglePropertyValue !==
undefined) {
// see which TargetProperty is updated
if (updatePropertyInfo.TargetProperty === 'sourceurl') {
// SourceUrl updated - update the <img src=
this.setProperty('sourceurl',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("src",
updatePropertyInfo.SinglePropertyValue);
} else if (updatePropertyInfo.TargetProperty ===
'alternatetext') {
// AlternateText updated - update the <img alt=
this.setProperty('alternatetext',
updatePropertyInfo.SinglePropertyValue);
widgetElement.attr("alt",
updatePropertyInfo.SinglePropertyValue);
}
}
};
Legen Sie eine lokale Kopie der Eigenschaft im Widget-Objekt fest. Dadurch wird sichergestellt, dass das Laufzeitsystem die Eigenschaft aus dem Eigenschaftenbehälter abrufen kann.
Alternativ können Sie eine benutzerdefinierte getProperty_{propertyName}-Methode bereitstellen und den Wert auf andere Weise speichern.
• getProperty_{propertyName}() – Wenn zur Laufzeit der Eigenschaftswert erforderlich ist, prüft sie, ob das Widget eine Funktion implementiert, um den Wert dieser Eigenschaft zu überschreiben und abzurufen. Dies wird verwendet, wenn die Daten von Ihrem Widget zur Laufzeit verfügbar sind, um Parameter für einen Service-Aufruf zu füllen.