Funzioni disponibili per la personalizzazione dei widget di ThingWorx in fase di esecuzione
Nella presente sezione vengono descritte le funzioni disponibili per i widget in fase di esecuzione.
Ciclo di vita dei widget in fase di esecuzione
• Quando un widget viene creato per la prima volta, l'esecuzione ottiene tutte le proprietà dichiarate chiamando la funzione runtimeProperties().
Per ulteriori informazioni, vedere la sezione Callback dall'esecuzione al widget.
• I valori delle proprietà che vengono salvati nella definizione del mashup vengono caricati nell'oggetto senza chiamare alcuna funzione.
• Dopo che il widget è stato caricato, ma prima che venga sottoposto a rendering sullo schermo, l'esecuzione chiama la funzione renderHtml(). In questa funzione viene restituito l'HTML dell'oggetto. L'esecuzione esegue il rendering dell'HTML restituito dalla funzione nella posizione appropriata nel DOM.
• Una volta aggiunto l'HTML al DOM, viene chiamata la funzione afterRender(). Se necessario, è possibile eseguire associazioni jQuery. A questo punto è possibile fare riferimento agli elementi DOM effettivi. Ad esempio, utilizzare il codice seguente per fare riferimento agli elementi DOM:
// note that this is a jQuery object
var widgetElement = this.domElement;
var widgetElement = this.domElement;
 |
L'esecuzione modifica l'ID dell'elemento DOM. Si consiglia di utilizzare sempre l'oggetto jQuery this.domElementId per ottenere l'ID dell'elemento DOM.
|
• Se è stato definito un evento che può essere associato, è possibile attivare l'evento, come illustrato nell'esempio riportato di seguito.
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');
• Se sono presenti proprietà associate come destinazioni dati, viene chiamata la funzione updateProperty(). È necessario aggiornare direttamente il DOM se è interessato dalla proprietà modificata. Nella maggior parte dei casi quando i dati sono associati, il DOM subisce una modifica.
• Se sono presenti proprietà definite come origini dati associate, è possibile chiamare la funzione getProperty_{propertyName}(). Se non si definisce questa funzione, l'esecuzione ottiene il valore dal contenitore delle proprietà.
API di esecuzione disponibili per i widget
È possibile accedere alle API riportate di seguito da un widget nel contesto dell'esecuzione.
• this.jqElementId- ID dell'elemento DOM dell'oggetto dopo il rendering del widget nella pagina HTML.
• this.jqElement- L'elemento jQuery.
• this.getProperty(name)- Ottiene il nome della proprietà.
• this.setProperty(name,value)- Imposta il nome e il valore della proprietà.
• this.updateSelection(propertyName,selectedRowIndices)- Chiamare questa funzione quando il widget modifica la proprietà nelle righe selezionate. A queste righe sono associati dati. Ad esempio, se in un callback è stato definito un evento come onSelectStateChanged(), chiamando l'API this.updateSelection(propertyName,selectedRowIndices) il sistema aggiorna tutti i widget che dipendono dalle righe selezionate.
Callback dall'esecuzione al widget
Di seguito sono indicate le funzioni sul widget chiamate dall'esecuzione.
• runtimeProperties() [facoltativa] - Restituisce una struttura JSON che definisce le proprietà del widget.
Proprietà facoltative:
|
Proprietà
|
Descrizione
|
|---|---|
|
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à è fasle.
|
|
needsDataLoadingAndError
|
I valori validi sono true e false. Il valore di default della proprietà è fasle. Impostare la proprietà su true se si desidera che il widget visualizzi l'opacità standard del 25% quando non viene ricevuto alcun dato. Il widget diventa rosso quando si verifica un errore durante il recupero dei dati.
|
|
borderWidth
|
Se il widget dispone di un bordo, impostare questa proprietà sulla larghezza del bordo. La proprietà garantisce un progetto ad alta definizione durante lo sviluppo e la fase di esecuzione.
|
|
supportsAutoResize
|
Specifica se il widget supporta automaticamente il ridimensionamento. I valori validi sono true e false.
|
|
propertyAttributes
|
Se sono presenti proprietà STRING localizzabili, elencarle in questa proprietà.
Ad esempio, se TooltipLabel1 è localizzabile:
this.runtimeProperties = function () {
return { 'needsDataLoadingAndError': true, 'propertyAttributes': { 'TooltipLabel1': {'isLocalizable': true} } } }; |
• renderHtml() [obbligatoria] - La funzione restituisce il frammento HTML posizionato nella schermata in fase di esecuzione. Per il contenitore di dati del widget, ad esempio div, deve essere specificata una classe di contenuto widget. Una volta specificata la classe, l'elemento contenitore viene aggiunto al DOM. Il contenitore è accessibile utilizzando jqElement e il relativo ID elemento DOM è disponibile in jqElementId.
• afterRender() [facoltativa] - Questa funzione viene chiamata dopo l'inserimento del frammento HTML del widget nell'elemento DOM. Utilizzare this.domElementId per ottenere l'ID elemento DOM. Utilizzare l'elemento this.jqElement per ottenere l'elemento DOM jQuery.
• beforeDestroy() [facoltativa ma consigliata] - Chiamare questa funzione quando il widget viene rimosso dalla schermata. In questo modo è possibile eseguire le operazioni riportate di seguito.
◦ Annullare qualsiasi associazione
◦ Cancellare qualsiasi insieme di dati con .data()
◦ Eliminare qualsiasi libreria o plug-in di terze parti, chiamare i relativi distruttori e così via.
◦ Liberare qualsiasi memoria allocata o che viene mantenuta nello stato di closure, impostando tutte le variabili su null
◦ Non è necessario eliminare gli elementi DOM all'interno del widget, in quanto questi vengono distrutti dall'esecuzione.
◦ Eliminare il DOM solo aggiungendo l'argomento DOMOnly alla funzione.
|
|
Per utilizzare il caricamento lazy con il widget, aggiungere l'argomento DOMOnly alla funzione.
|
• resize(width,height) [facoltativa, utile solo se si dichiara supportsAutoResize: true] - Questa funzione viene chiamata quando il widget viene ridimensionato.
Non tutti i widget devono gestire questa situazione. È il caso, ad esempio, di elementi del widget e del CSS che vengono scalati automaticamente.
Tuttavia, la gestione riguarda la maggior parte dei widget quando la loro dimensione cambia.
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) - Questa funzione viene chiamata quando le righe selezionate vengono modificate dalle origini dati associate a essa con la proprietà specificata. selectedRows è un insieme di dati effettivi e selectedRowIndices è un insieme degli indici delle righe selezionate.
|
|
È necessario definire questa funzionalità per ottenere la funzionalità completa dell'evento selectedRows senza dover associare un widget elenco o griglia.
|
• serviceInvoked(serviceName)- La funzione viene chiamata quando viene attivato un servizio definito.
• updateProperty(updatePropertyInfo)- updatePropertyInfo è un oggetto con la struttura JSON seguente:
{
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
}
Per ogni associazione dati, l'oggetto updateProperty() del widget viene chiamato ogni volta che vengono modificati i dati di origine. È necessario controllare updatePropertyInfo.TargetProperty per determinare quale aspetto del widget deve essere aggiornato.
Vedere l'esempio riportato di seguito relativo a un 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);
}
}
};
Impostare una copia locale della proprietà nell'oggetto widget. Ciò garantisce che il sistema di esecuzione possa ottenere la proprietà dal contenitore delle proprietà.
In alternativa è possibile fornire un metodo getProperty_{propertyName} personalizzato e memorizzare il valore in un altro modo.
• getProperty_{propertyName}() - Quando l'esecuzione richiede il valore della proprietà, verifica se il widget implementa una funzione per ignorare e ottenere il valore di tale proprietà. Viene utilizzato quando l'esecuzione ottiene i dati dal widget per completare i parametri per una chiamata di servizio.