Funktionen zum Anpassen von ThingWorx Widgets
In diesem Abschnitt werden die Funktionen beschrieben, die für Widgets verfügbar sind.
Widget-Lebenszyklus im Mashup Builder
Ein Widget hat den folgenden Lebenszyklus im Mashup Builder. In jedem Lebenszyklusstatus ruft der Mashup Builder die folgenden Funktionen auf, die für Widgets verfügbar sind:
• Erkannt
Das Widget wird in index.html geladen und zur Widget-Symbolleiste oder -Palette hinzugefügt.
|
Funktion
|
Beschreibung
|
|---|---|
|
widgetProperties()
|
Informationen zu jedem Widget im Mashup abrufen Informationen wie Anzeigename und Beschreibung werden abgerufen.
|
|
widgetEvents()
|
Informationen zu den Ereignissen abrufen, die von jedem Widget angezeigt werden
|
|
widgetServices()
|
Informationen zu den Diensten abrufen, die von jedem Widget angezeigt werden
|
• Erstellt
Das Widget wird im Mashup-Fensterbereich hinzugefügt.
|
Funktion
|
Beschreibung
|
|---|---|
|
afterload()
|
Wird nach dem Laden des Objekts und dem Wiederherstellen von Eigenschaften aus der Datei, aber vor dem Rendern des Objekts aufgerufen
|
• Angehängt
Das Widget wird an das Workspace-DOM-Element angehängt.
|
Funktion
|
Beschreibung
|
|---|---|
|
renderHtml()
|
HTML-Fragment abrufen, das in das Mashup-DOM-Element eingefügt wird
|
|
afterRender()
|
Wird nach dem Einfügen des HTML-Fragments, das das Widget darstellt, in das Mashup-DOM-Element und nach dem Zuweisen einer nutzbaren Element-ID zum DOM-Element mit dem Widget-Inhalt abgerufen. Anschließend kann das DOM-Element bearbeitet werden.
|
• Aktualisiert
Das Widget wird im Fenster mit der Widget-Eigenschaft hinsichtlich seiner Größe geändert oder aktualisiert.
|
Funktion
|
Beschreibung
|
|---|---|
|
beforeSetProperty()
|
Wird aufgerufen, bevor eine Widget-Eigenschaft aktualisiert wird
|
|
afterSetProperty()
|
Wird aufgerufen, nachdem eine Widget-Eigenschaft aktualisiert wurde
|
• Zerstört
Das Widget wird aus dem Mashup gelöscht.
|
Funktion
|
Beschreibung
|
|---|---|
|
beforeDestroy()
|
Wird aufgerufen, bevor das DOM-Element des Widgets entfernt und das Widget von seinem Eltern-Widget getrennt und freigegeben wird. Sie sollten die Ressourcen, wie Plugins und Ereignishandler, freigeben, die während der Lebensdauer des Widgets erworben werden. Zum Unterstützen des erneuten Ladens des Widgets in einem mit Lazy Loading geladenen Container müssen Sie das Argument beforeDesctroy() der Funktion domOnly hinzufügen und das Widget nur dann löschen, wenn der Wert "false" ist. Wenn Sie das Argument domOnly nicht verwenden, wird das erneute Laden des Widget-Formulars nicht ordnungsgemäß ausgeführt. Weitere Informationen finden Sie unter Lazy Loading in Mashups verwenden.
|
Eigenschaftenbehälter
Der Eigenschaftenbehälter ist ein Satz von Name-Wert-Paaren. Jedes Paar ist ein einfacher Wertspeicher. ThingWorx verwendet Eigenschaftenbehälter als Struktur-Persistenzmechanismus für Mashups.
Mashup Builder-APIs für Widgets
Auf die folgenden APIs kann über ein Widget im Kontext des Mashup Builder 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) – Jeder Aufruf dieser Funktion ruft die Funktion afterSetProperty() auf, wenn afterSetProperty() im Widget definiert ist.
• this.updatedProperties() – Diese Funktion sollte aufgerufen werden, wenn Eigenschaften im Widget geändert werden. Nachdem die Funktion aufgerufen wurde, aktualisiert der Mashup Builder das Fenster mit Widget-Eigenschaften.
• this.getInfotableMetadataForProperty(propertyName) – Ruft die Infotable-Metadaten für eine Eigenschaft ab, die gebunden ist. Sie gibt "undefined" zurück, wenn die Eigenschaft nicht gebunden ist.
• this.resetPropertyToDefaultValue(propertyName) – Setzt die angegebene Eigenschaft auf den Standardwert zurück.
• this.removeBindingsFromPropertyAsTarget(propertyName) – Entfernt Zieldatenbindungen aus der angegebenen Eigenschaft.
• this.removeBindingsFromPropertyAsSource(propertyName) – Entfernt Quelldatenbindungen aus der angegebenen Eigenschaft.
• this.isPropertyBoundAsTarget(propertyName) – Prüft, ob die Eigenschaft als Ziel gebunden ist. Sie können die Funktion verwenden, um zu bestimmen, ob eine Eigenschaft festgelegt oder gebunden wurde. Das folgende Beispiel zeigt, wie die Funktion validate() im Widget "Blog" verwendet wird, um zu bestimmen, ob eine Eigenschaft gebunden ist:
this.validate = function () {
var result = [];
var blogNameConfigured = this.getProperty('Blog');
if (blogNameConfigured === '' ||
blogNameConfigured === undefined) {
if (!this.isPropertyBoundAsTarget('Blog')) {
result.push({ severity: 'warning',
message: 'Blog is not bound for {target-id}' });
}
}
return result;
}
var result = [];
var blogNameConfigured = this.getProperty('Blog');
if (blogNameConfigured === '' ||
blogNameConfigured === undefined) {
if (!this.isPropertyBoundAsTarget('Blog')) {
result.push({ severity: 'warning',
message: 'Blog is not bound for {target-id}' });
}
}
return result;
}
• this.isPropertyBoundAsSource(propertyName) – Prüft, ob die Eigenschaft als Quelle gebunden wurde. Sie können die Funktion verwenden, um zu bestimmen, ob eine Eigenschaft an ein Ziel gebunden wurde. Das folgende Beispiel zeigt, wie die Funktion validate() im Widget "Kontrollkästchen" verwendet wird, um zu bestimmen, ob eine Eigenschaft gebunden ist:
this.validate = function () {
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
var result = [];
if (!this.isPropertyBoundAsSource('State') &&
!this.isPropertyBoundAsTarget('State')) {
result.push({ severity: 'warning',
message: 'State for {target-id} is not bound' });
}
return result;
}
Callbacks von Mashup Builder zu Widget
Die folgenden Funktionen im Widget werden vom Mashup Builder aufgerufen, um das Verhalten eines Widgets zu ändern.
• widgetProperties() [erforderlich] – Gibt eine JSON-Struktur zurück, die die Eigenschaften des Widgets definiert.
Erforderliche Eigenschaften sind:
◦ Name – Name des Widgets, das in der Widget-Symbolleiste angezeigt wird.
Optionale Eigenschaften sind:
|
Eigenschaft
|
Beschreibung
|
|---|---|
|
Beschreibung
|
Beschreibung des Widgets, das als Tooltip verwendet wird
|
|
iconImage
|
Dateiname des Widget-Symbols oder -Bildes
|
|
category
|
Array von Zeichenfolgen, die die Kategorien angeben, unter denen das Widget verfügbar ist.
Beispiel: Allgemein, Diagramme, Daten, Container usw. Dies ermöglicht es dem Benutzer, die Widgets nach dem Kategorietyp zu filtern.
|
|
isResizable
|
Gibt an, ob die Größe des Widgets geändert werden kann.
|
|
defaultBindingTargetProperty
|
Name der Eigenschaft, die als Daten- oder Ereignisbindungsziel verwendet werden soll.
|
|
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 Entwicklung und zur Laufzeit.
Als Beispiel dient ein Widget, dessen Größe zur Laufzeit 10 x 10 Pixel mit einer Randgröße von 1 Pixel sein soll. Zur Entwurfszeit sollte die Größe des Widgets 8 x 8 Pixel betragen, um das 1 Pixel zu verarbeiten, das während der Entwurfszeit hinzugefügt wurde. Dadurch wird der Rand innerhalb des Widgets platziert und Breite/Höhe in den Widget-Eigenschaften ist korrekt.
|
|
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 false.
|
|
customEditor
|
Name des benutzerdefinierten Editordialogfensters, das verwendet wird, um die Widget-Konfiguration festzulegen und zu bearbeiten. Erstellen Sie in Ihrem Widget-Projekt ein Dialogfenster mit dem Namen TW.IDE.Dialogs.<name>.
|
|
customEditorMenuText
|
Der Text, der im Flyout-Menü des Widgets angezeigt wird. Es handelt sich auch um den Text, der als Tooltip für Widgets inThingWorx Composer angezeigt wird. Beispielsweise Rasterspalten konfigurieren.
|
|
allowPositioning
|
Prüft, ob das Widget in einem Fensterbereich platziert werden kann. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist true.
|
|
supportsLabel
|
Gibt an, ob das Widget die Beschriftungseigenschaft unterstützt. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist false.
Wenn diese Option auf true festgelegt ist, macht das Widget eine Beschriftungseigenschaft verfügbar. Diese Eigenschaft wird verwendet, um eine Textbeschriftung zu erstellen, die neben dem Widget inThingWorx Composer und zur Laufzeit angezeigt wird.
|
|
supportsAutoResize
|
Gibt an, ob das Widget die Größenänderung automatisch unterstützt. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist false.
Bei Einstellung auf true kann das Widget in reaktionsfähigen Containern wie Spalten, Zeilen, reaktionsfähigen Registerkarten und reaktionsfähigen Mashups platziert werden.
|
|
properties
|
Eine Sammlung von JSON-Objekten für das Widget, die die Eigenschaften des Widgets beschreiben. Diese können geändert werden, wenn das Widget einem Mashup hinzugefügt wird. Diese Eigenschaften werden im Eigenschaftsfenster des Mashup Builder mit dem Namen jedes Objekts angezeigt, das als Eigenschaftsname verwendet wird. Die entsprechenden Attribute steuern, wie der Eigenschaftswert festgelegt wird.
Beispiel:
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
Die folgenden Attribute können für jedes Eigenschaftsobjekt angegeben werden:
|
Attribut
|
Beschreibung
|
||||
|---|---|---|---|---|---|
|
Beschreibung
|
Beschreibung des Widgets, das für den Tooltip verwendet wird
|
||||
|
baseType
|
Basistyp des Widgets. Wenn der Basistyp-Wert FIELDNAME ist, wird im Fenster mit der Widget-Eigenschaft eine Liste der Felder angezeigt, die in der Infotable verfügbar sind. Die Felder sind an den Wert sourcePropertyName basierend auf der Basistyp-Beschränkung gebunden.
Die anderen speziellen Basistypen sind:
• STATEDEFINITION – Wählt eine Statusdefinition aus.
• STYLEDEFINITION – Wählt eine Stildefinition aus.
• RENDERERWITHSTATE – Zeigt ein Dialogfenster an, in dem Sie einen Daten-Renderer und eine Statusformatierung auswählen können.
• STATEFORMATTING – Zeigt ein Dialogfenster an, in dem Sie einen festen Stil oder einen statusbasierten Stil auswählen können.
• VOCABULARYNAME – Wählt das Vokabular der Daten-Tags zur Laufzeit aus.
|
||||
|
mustImplement
|
Wenn der Basistyp THINGNAME ist und Sie das Attribut mustImplement angeben, schränkt der Mashup Builder das Dialogfenster insofern ein, dass nur die Popups geöffnet werden, die den angegebenen EntityType und EntityName implementieren. Der Mashup Builder ruft die Funktion QueryImplementingThings auf, um zu validieren, ob der übergebene Wert den Typ EntityType aufweist, und prüft, ob EntityName implementiert ist.
Beispiel:
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
Wenn der Basistyp des Widgets als RENDERERWITHFORMAT festgelegt ist, gibt das Attribut an, welche Eigenschaft der Infotable für die Konfiguration verwendet wird.
|
||||
|
sourcePropertyName
|
Wenn der Basistyp des Widgets als FIELDNAME festgelegt ist, prüft das Attribut, welche Eigenschaft der Infotable für die Konfiguration verwendet wird.
|
||||
|
baseTypeRestriction
|
Wenn dieses Attribut angegeben ist, wird der Wert verwendet, um die in der Dropdown-Liste FIELDNAME verfügbaren Felder einzuschränken.
|
||||
|
tagType
|
Wenn der Basistyp als TAGS festgelegt ist, gibt das Attribut den Tag-Typ an. Die gültigen Werte sind DataTags, der Standardwert, oder ModelTags.
|
||||
|
defaultValue
|
Wird verwendet, um den Standardwert für eine Eigenschaft festzulegen. Der Standardwert ist "undefined".
|
||||
|
isbindingsource
|
Gibt an, ob die Eigenschaft eine Datenbindungsquelle ist. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist fasle.
|
||||
|
isBindingTarget
|
Gibt an, ob die Eigenschaft ein Datenbindungsziel ist. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist fasle.
|
||||
|
isEditable
|
Gibt an, ob die Eigenschaft in ThingWorx Composer bearbeitbar ist. Die gültigen Werte sind true, der Standardwert, und false.
|
||||
|
isVisible
|
Gibt an, ob die Eigenschaft im Eigenschaftsfenster sichtbar ist. Die gültigen Werte sind true und false. Der Standardwert der Eigenschaft ist true.
|
||||
|
isLocalizable
|
Gibt an, ob die Eigenschaft lokalisiert werden kann. Dieses Attribut ist erforderlich, wenn der Basistyp auf STRING festgelegt ist. Die gültigen Werte sind true und false.
|
||||
|
selectOptions
|
Ein Array mit Wert- oder Anzeigetextstrukturen.
Beispiel:
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer prüft, ob die Eigenschaft eine Datenbindungsquelle ist. Die gültigen Werte sind true und false.
Wenn der Attributwert auf true festgelegt, aber die Eigenschaft nicht gebunden ist, generiert ThingWorx Composer eine Liste von Elementen, die Sie ausführen müssen, um das Mashup zu speichern.
|
||||
|
warnIfNotBoundAsTarget
|
Composer prüft, ob die Eigenschaft ein Datenbindungsziel ist. Die gültigen Werte sind true und false.
Wenn der Attributwert auf true festgelegt, aber die Eigenschaft nicht gebunden ist, generiert ThingWorx Composer eine Liste von Elementen, die Sie ausführen müssen, um das Mashup zu speichern.
|
• afterLoad() [optional] – Die Funktion wird nach dem Laden des Objekts und dem Wiederherstellen von Eigenschaften aus der Datei, aber vor dem Rendern des Objekts auf der HTML-Seite aufgerufen.
• renderHtml() [erforderlich] – Die Funktion gibt das HTML-Fragment zurück, das ThingWorx Composer auf dem Bildschirm platziert. Der Inhaltscontainer des Widgets, wie div, sollte eine angegebene Widget-Inhaltsklasse enthalten. Danach wird das Container-Element an das DOM angehängt. Der Container ist unter Verwendung des jqElement zugänglich und seine DOM-Element-ID in jqElementId verfügbar.
• widgetEvents() [optional] – Eine Sammlung von Ereignissen; jedes Ereignis kann die folgende Eigenschaft haben:
◦ warnIfNotBound – Composer prüft, ob die Eigenschaft gebunden ist. Die gültigen Werte sind true und false.
Wenn der Attributwert auf true festgelegt, aber die Eigenschaft nicht gebunden ist, generiert ThingWorx Composer eine Liste von Elementen, die Sie ausführen müssen, um das Mashup zu speichern.
• widgetServices() [optional] – Eine Sammlung von Diensten; jeder Dienst kann die folgende Eigenschaft haben:
◦ warnIfNotBound – Composer prüft, ob die Eigenschaft gebunden ist. Die gültigen Werte sind true und false.
Wenn der Attributwert auf true festgelegt, aber die Eigenschaft nicht gebunden ist, generiert ThingWorx Composer eine Liste von Elementen, die Sie ausführen müssen, um das Mashup zu speichern.
• afterRender() [optional] – Die Funktion wird aufgerufen, nachdem das HTML-Fragment in das DOM eingefügt wurde.
• beforeDestroy() [optional] – Die Funktion wird aufgerufen, bevor das DOM-Element des Widgets entfernt und das Widget von seinem Eltern-Widget getrennt und freigegeben wird. Sie sollten die Ressourcen wie Plugins, Ereignis-Handler usw. freigeben, die während der gesamten Lebensdauer des Widgets erworben wurden.
• beforeSetProperty(name,value) [optional] [nur Mashup Builder – nicht zur Laufzeit] – Die Funktion wird aufgerufen, bevor eine Eigenschaft in ThingWorx Composer aktualisiert wird. Sie können Validierungen für den neuen Eigenschaftswert ausführen, bevor er festgeschrieben wird. Wenn die Validierung fehlschlägt, können Sie eine Meldungszeichenfolge zurückgeben, um den Benutzer über die ungültige Eingabe zu informieren. Der neue Eigenschaftswert wird nicht festgeschrieben. Wenn während der Validierung nichts zurückgegeben wird, wird der Wert als gültig angenommen.
• afterSetProperty(name,value) [optional] [nur Mashup Builder – nicht zur Laufzeit] – Die Funktion wird aufgerufen, nachdem eine Eigenschaft in ThingWorx Composer aktualisiert wurde. Wenn Sie den Wert als true angeben, wird das Widget wieder inThingWorx Composer gerendert, nachdem der Wert geändert wurde.
• afterAddBindingSource(bindingInfo) [optional] – Diese Funktion wird immer dann aufgerufen, wenn Daten an das Widget gebunden werden. Das einzige Feld in bindingInfo ist targetProperty, der Name der Eigenschaft. Es ist gebunden.
• validate() [optional] – Die Funktion wird aufgerufen, wenn ThingWorx Composer seine Aufgabenliste aktualisiert. Der Aufruf gibt ein Array von Ergebnisobjekten zurück:
◦ severity – Dies ist eine optionale Eigenschaft. Schweregrad des erkannten Problems.
◦ message – Dies ist eine erforderliche Eigenschaft. Der Meldungstext kann ein oder mehrere vordefinierte Token enthalten, z.B. {target-id}. Die Meldung wird durch einen Hyperlink ersetzt, mit dem der Benutzer navigieren und das spezifische Widget auswählen kann, das die Meldung generiert hat.
Beispiel:
this.validate = function () {
var result = [];
var srcUrl = this.getProperty('SourceURL');
if (srcUrl === '' || srcUrl === undefined) {
result.push({ severity: 'warning',
message: 'SourceURL is not defined for {target-id}'});
}
return result;
}
var result = [];
var srcUrl = this.getProperty('SourceURL');
if (srcUrl === '' || srcUrl === undefined) {
result.push({ severity: 'warning',
message: 'SourceURL is not defined for {target-id}'});
}
return result;
}