Funzioni disponibili per la personalizzazione dei widget ThingWorx
Questa sezione illustra le funzioni disponibili per i widget.
Ciclo di vita dei widget in Mashup Builder
Di seguito è illustrato il ciclo di vita di un widget in Mashup Builder. In ogni stato del ciclo di vita, Mashup Builder chiama le funzioni disponibili per i widget descritte di seguito.
• Individuazione
Il widget viene caricato in index.html e aggiunto alla tavolozza o alla barra degli strumenti dei widget.
|
Funzione
|
Descrizione
|
|---|---|
|
widgetProperties()
|
Ottiene informazioni su ogni widget nel mashup. Vengono recuperate informazioni come nome visualizzato e descrizione.
|
|
widgetEvents()
|
Ottiene informazioni sugli eventi esposti da ogni widget.
|
|
widgetServices()
|
Ottiene informazioni sui servizi esposti da ogni widget.
|
• Creazione
Il widget viene aggiunto nel pannello del mashup.
|
Funzione
|
Descrizione
|
|---|---|
|
afterload()
|
Viene chiamata dopo il caricamento dell'oggetto e il ripristino delle proprietà dal file, ma prima del rendering dell'oggetto.
|
• Aggiunta
Il widget viene aggiunto all'elemento DOM del workspace.
|
Funzione
|
Descrizione
|
|---|---|
|
renderHtml()
|
Ottiene il frammento HTML inserito nell'elemento DOM del mashup.
|
|
afterRender()
|
Viene chiamata dopo l'inserimento del frammento HTML che rappresenta il widget nell'elemento DOM del mashup e l'assegnazione di un ID elemento utilizzabile all'elemento DOM in cui si trova il contenuto del widget. Dopo questa operazione, l'elemento DOM è pronto per essere manipolato.
|
• Aggiornamento
Il widget viene ridimensionato o aggiornato nella finestra delle proprietà del widget.
|
Funzione
|
Descrizione
|
|---|---|
|
beforeSetProperty()
|
Viene chiamata prima dell'aggiornamento di una proprietà del widget.
|
|
afterSetProperty()
|
Viene chiamata dopo l'aggiornamento di una proprietà del widget.
|
• Eliminazione
Il widget viene eliminato dal mashup.
|
Funzione
|
Descrizione
|
|---|---|
|
beforeDestroy()
|
Viene chiamata prima della rimozione dell'elemento DOM del widget e prima dello scollegamento del widget dal widget padre e dell'annullamento dell'assegnazione. È consigliabile liberare le risorse acquisite durante il ciclo di vita del widget, quali plug-in e gestori eventi.
|
Contenitore delle proprietà
Un contenitore delle proprietà è un insieme di coppie nome-valore. Ogni coppia è un archivio valori semplice. ThingWorx utilizza i contenitori delle proprietà come meccanismo di persistenza della struttura per i mashup.
API di Mashup Builder disponibili per i widget
Un widget nel contesto di Mashup Builder può accedere alle API seguenti:
• this.jqElementId - ID elemento DOM dell'oggetto dopo il rendering del widget nella pagina HTML.
• this.jqElement - Elemento jQuery.
• this.getProperty(name) - Recupera il nome della proprietà.
• this.setProperty(name,value) - Ogni chiamata a questa funzione chiama afterSetProperty(), se la funzione afterSetProperty() è definita nel widget.
• this.updatedProperties() - Questa funzione deve essere chiamata in caso di modifica delle proprietà nel widget. Dopo la chiamata della funzione, Mashup Builder aggiorna la finestra delle proprietà del widget.
• this.getInfotableMetadataForProperty(propertyName) - Ottiene i metadati della infotable per una proprietà associata. Se la proprietà non è associata, restituisce undefined.
• this.resetPropertyToDefaultValue(propertyName) - Reimposta la proprietà specificata sul valore di default.
• this.removeBindingsFromPropertyAsTarget(propertyName) - Rimuove le associazioni dati di destinazione dalla proprietà specificata.
• this.removeBindingsFromPropertyAsSource(propertyName) - Rimuove le associazioni dati di origine dalla proprietà specificata.
• this.isPropertyBoundAsTarget(propertyName) - Controlla se la proprietà è associata come destinazione. È possibile utilizzare la funzione per determinare se una proprietà è stata impostata o associata. L'esempio seguente mostra come è possibile utilizzare la funzione validate() nel widget Blog per determinare se una proprietà è associata:
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) - Controlla se la proprietà è stata associata come origine. È possibile utilizzare la funzione per determinare se una proprietà è stata associata a una destinazione. L'esempio seguente mostra come è possibile utilizzare la funzione validate() nel widget Casella di controllo per determinare se una proprietà è associata:
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;
}
Callback da Mashup Builder al widget
Le funzioni sul widget descritte di seguito vengono chiamate da Mashup Builder per modificare il comportamento di un widget.
• widgetProperties() [obbligatoria] - Restituisce una struttura JSON che definisce le proprietà del widget.
Proprietà obbligatorie:
◦ name - Nome del widget visualizzato nella barra degli strumenti dei widget.
Proprietà facoltative:
|
Proprietà
|
Descrizione
|
|---|---|
|
description
|
Descrizione del widget, utilizzata come descrizione comando.
|
|
iconImage
|
Nome file dell'icona o dell'immagine del widget.
|
|
category
|
Insieme di stringhe che specificano le categorie in cui il widget è disponibile.
Ad esempio, Comuni, Grafici, Dati, Contenitori e così via. L'utente può così filtrare i widget in base al tipo di categoria.
|
|
isResizable
|
Specifica se il widget può essere ridimensionato.
|
|
defaultBindingTargetProperty
|
Nome della proprietà da utilizzare come destinazione delle associazioni dati o eventi.
|
|
borderWidth
|
Se il widget dispone di un bordo, impostare questa proprietà sulla larghezza del bordo. La proprietà consente di definire un progetto con precisione al pixel durante lo sviluppo e in fase di esecuzione.
Si consideri, ad esempio, un widget le cui dimensioni in fase di esecuzione devono essere 10X10 pixel con un bordo di 1 pixel. In fase di progettazione, le dimensioni del widget devono essere 8X8 pixel per gestire l'aggiunta di 1 pixel in questa fase. In questo modo, il bordo si trova all'interno del widget e la larghezza e l'altezza nelle proprietà del widget sono precise.
|
|
isContainer
|
Specifica se un'istanza del widget può essere un contenitore per altre istanze. I valori validi sono true e false. Il valore di default della proprietà è false.
|
|
customEditor
|
Nome della finestra di dialogo personalizzata dell'editor da utilizzare per impostare e modificare la configurazione del widget. Nel progetto del widget creare una finestra di dialogo denominata TW.IDE.Dialogs.<name>.
|
|
customEditorMenuText
|
Testo visualizzato nel menu mobile del widget, nonché come descrizione comando per il widget inThingWorx Composer. Ad esempio, Configura colonne griglia.
|
|
allowPositioning
|
Controlla se il widget può essere posizionato in un pannello. I valori validi sono true e false. Il valore di default della proprietà è true.
|
|
supportsLabel
|
Specifica se il widget supporta la proprietà Etichetta. I valori validi sono true e false. Il valore di default della proprietà è false.
Se è impostata su true, il widget espone una proprietà Etichetta. Questa proprietà viene utilizzata per creare un'etichetta di testo visualizzata accanto al widget in ThingWorx Composer e in fase di esecuzione.
|
|
supportsAutoResize
|
Specifica se il widget supporta automaticamente il ridimensionamento. I valori validi sono true e false. Il valore di default della proprietà è false.
Se è impostata su true, il widget può essere posizionato in contenitori dinamici, quali colonne, righe e mashup e schede dinamici.
|
|
properties
|
Raccolta di oggetti JSON per il widget che descrivono le proprietà del widget che possono essere modificate quando il widget viene aggiunto a un mashup. Queste proprietà vengono visualizzate nella finestra delle proprietà di Mashup Builder con il nome di ciascun oggetto utilizzato come nome della proprietà. Gli attributi corrispondenti controllano come viene impostato il valore della proprietà.
Ad esempio:
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
Per ogni oggetto proprietà è possibile specificare gli attributi seguenti:
|
Attributo
|
Descrizione
|
||||
|---|---|---|---|---|---|
|
description
|
Descrizione del widget utilizzata come descrizione comando.
|
||||
|
baseType
|
Tipo di base del widget. Se il valore del tipo di base è FIELDNAME, nella finestra delle proprietà del widget viene visualizza un elenco dei campi disponibili nella infotable. I campi vengono associati al valore di sourcePropertyName in base alla limitazione del tipo di base.
Gli altri tipi di base speciali sono i seguenti:
• STATEDEFINITION - Seleziona una definizione di stato.
• STYLEDEFINITION - Seleziona una definizione di stile.
• RENDERERWITHSTATE - Visualizza una finestra di dialogo che consente di selezionare un renderer di dati e la formattazione dello stato.
• STATEFORMATTING - Visualizza una finestra di dialogo che consente di selezionare uno stile fisso o uno stile basato sullo stato.
• VOCABULARYNAME - Seleziona il vocabolario di tag dati in fase di esecuzione.
|
||||
|
mustImplement
|
Se il tipo di base è THINGNAME e si specifica l'attributo mustImplement, Mashup Builder limita la finestra di dialogo in modo che vengano aperte solo le finestre popup che implementano il tipo e il nome di entità specificati. Mashup Builder chiama la funzione QueryImplementingThings per verificare se il valore trasmesso è del tipo EntityType e controlla l'implementazione di EntityName.
Ad esempio:
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
Se il tipo di base del widget è impostato su RENDERERWITHFORMAT, l'attributo specifica la proprietà della infotable utilizzata per la configurazione.
|
||||
|
sourcePropertyName
|
Se il tipo di base del widget è impostato su FIELDNAME, l'attributo controlla la proprietà della infotable utilizzata per la configurazione.
|
||||
|
baseTypeRestriction
|
Se si specifica questo attributo, il valore viene utilizzato per limitare i campi disponibili nell'elenco a discesa per FIELDNAME.
|
||||
|
tagType
|
Se il tipo di base è impostato su TAGS, l'attributo specifica il tipo di tag. I valori validi sono DataTags, che è il valore di default, e ModelTags.
|
||||
|
defaultValue
|
Viene utilizzato per impostare il valore di default per una proprietà. Il valore di default è undefined.
|
||||
|
isBindingSource
|
Specifica se la proprietà è l'origine di un'associazione dati. I valori validi sono true e false. Il valore di default della proprietà è fasle.
|
||||
|
isBindingTarget
|
Specifica se la proprietà è la destinazione di un'associazione dati. I valori validi sono true e false. Il valore di default della proprietà è fasle.
|
||||
|
isEditable
|
Specifica se la proprietà è modificabile in ThingWorx Composer. I valori validi sono true, che è il valore di default, e false.
|
||||
|
isVisible
|
Specifica se la proprietà è visibile nella finestra delle proprietà. I valori validi sono true e false. Il valore di default della proprietà è true.
|
||||
|
isLocalizable
|
Specifica se la proprietà può essere localizzata. Questo attributo è obbligatorio quando il tipo di base è impostato su STRING. I valori validi sono true e false.
|
||||
|
selectOptions
|
Insieme di strutture di valori o testo visualizzato.
Ad esempio:
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer controlla se la proprietà è l'origine di un'associazione dati. I valori validi sono true e false.
Se il valore dell'attributo è impostato su true ma la proprietà non è associata, ThingWorx Composer genera un elenco degli elementi che è necessario completare per salvare il mashup.
|
||||
|
warnIfNotBoundAsTarget
|
Composer controlla se la proprietà è la destinazione di un'associazione dati. I valori validi sono true e false.
Se il valore dell'attributo è impostato su true ma la proprietà non è associata, ThingWorx Composer genera un elenco degli elementi che è necessario completare per salvare il mashup.
|
• afterLoad() [facoltativa] - La funzione viene chiamata dopo il caricamento dell'oggetto e il ripristino delle proprietà dal file, ma prima del rendering dell'oggetto nella pagina HTML.
• renderHtml() [obbligatoria] - La funzione restituisce il frammento HTML posizionato da ThingWorx Composer nella schermata. Nel contenitore di contenuto del widget, ad esempio div, deve essere specificata una classe di contenuto widget. Dopo questa operazione, l'elemento contenitore viene aggiunto all'elemento DOM. Il contenitore è accessibile mediante jqElement e il relativo ID elemento DOM è disponibile in jqElementId.
• widgetEvents() [facoltativa] - Raccolta di eventi. Ogni evento può disporre della proprietà seguente:
◦ warnIfNotBound - Composer controlla se la proprietà è associata. I valori validi sono true e false.
Se il valore dell'attributo è impostato su true ma la proprietà non è associata, ThingWorx Composer genera un elenco degli elementi che è necessario completare per salvare il mashup.
• widgetServices() [facoltativa] - Raccolta di servizi. Ogni servizio può disporre della proprietà seguente:
◦ warnIfNotBound - Composer controlla se la proprietà è associata. I valori validi sono true e false.
Se il valore dell'attributo è impostato su true ma la proprietà non è associata, ThingWorx Composer genera un elenco degli elementi che è necessario completare per salvare il mashup.
• afterRender() [facoltativa] - La funzione viene chiamata dopo l'inserimento del frammento HTML nell'elemento DOM.
• beforeDestroy() [facoltativa] - La funzione viene chiamata prima della rimozione dell'elemento DOM del widget e prima dello scollegamento del widget dal widget padre e dell'annullamento dell'assegnazione. È consigliabile liberare le risorse acquisite nel corso del ciclo di vita del widget, quali plug-in, gestori eventi e così via.
• beforeSetProperty(name,value) [facoltativa, solo in Mashup Builder e non in fase di esecuzione] - La funzione viene chiamata prima dell'aggiornamento di qualsiasi proprietà in ThingWorx Composer. È possibile eseguire convalide sul nuovo valore della proprietà prima della conferma. Se la convalida ha esito negativo, è possibile restituire una stringa di messaggio per informare l'utente dell'input non valido. Il nuovo valore della proprietà non viene confermato. Se durante la convalida non viene restituito alcun messaggio, il valore viene considerato valido.
• afterSetProperty(name,value) [facoltativa, solo in Mashup Builder e non in fase di esecuzione] - La funzione viene chiamata dopo l'aggiornamento di qualsiasi proprietà in ThingWorx Composer. Se come valore si specifica true, dopo la modifica del valore viene eseguito di nuovo il rendering del widget in ThingWorx Composer.
• afterAddBindingSource(bindingInfo) [facoltativa] - Questa funzione viene chiamata ogni volta che vengono associati dati al widget. L'unico campo in bindingInfo è targetProperty, che è il nome della proprietà ed è associato.
• validate() [facoltativa] - La funzione viene chiamata quando viene aggiornato l'elenco delle attività da fare di ThingWorx Composer. La chiamata restituisce un insieme di oggetti risultato:
◦ severity - Proprietà facoltativa. Gravità del problema rilevato.
◦ message - Proprietà obbligatoria. Il testo del messaggio può contenere uno o più token predefiniti, ad esempio {target-id}. Il messaggio viene sostituito con un collegamento ipertestuale che consente all'utente di passare al widget specifico che ha generato il messaggio e selezionarlo.
Ad esempio:
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;
}