Funciones de tiempo de ejecución disponibles para la personalización de widgets de ThingWorx
En esta sección se describen las funciones disponibles para los widgets en tiempo de ejecución.
Ciclo de vida de widgets en tiempo de ejecución
• Cuando se crea un widget por primera vez, el tiempo de ejecución obtiene las propiedades declaradas llamando a la función runtimeProperties().
Consulte la sección Llamadas del tiempo de ejecución al widget para obtener más información.
• Los valores de propiedades que se guardan en la definición del mashup se cargan en el objeto sin llamar a ninguna función.
• Después de cargar el widget, pero antes de que se represente en la pantalla, el tiempo de ejecución llama a la función renderHtml(). En esta función, se devuelve el HTML del objeto. El tiempo de ejecución representa el HTML que la función devuelve en el lugar adecuado del DOM.
• Después de añadir el HTML al DOM, se llama a la función afterRender(). Si fuera necesario, se pueden realizar enlaces jQuery. En este punto, se puede hacer referencia a los elementos DOM reales. Por ejemplo, utilice el siguiente código para hacer referencia a los elementos DOM:
// note that this is a jQuery object
var widgetElement = this.domElement;
var widgetElement = this.domElement;
 |
El tiempo de ejecución cambia el ID del elemento DOM. Se recomienda utilizar siempre el objeto jQuery this.domElementId para obtener el ID del elemento DOM.
|
• Si se ha definido un evento que se puede enlazar, se puede activar el evento, tal como se muestra en el siguiente ejemplo:
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');
• Si hay propiedades enlazadas como destinos de datos, se llama a la función updateProperty(). El DOM se debe actualizar directamente si la propiedad que se ha cambiado afecta al DOM. Cuando se enlazan los datos, en la mayoría de los casos, cambia el DOM.
• Si hay propiedades definidas como orígenes de datos y están enlazadas, se puede llamar a la función getProperty_{propertyName}(). Si no se define esta función, el tiempo de ejecución obtiene el valor de la bolsa de propiedades.
API de tiempo de ejecución disponibles para widgets
Un widget puede acceder a las siguientes API en el contexto del tiempo de ejecución:
• this.jqElementId: se trata del ID del elemento DOM del objeto después de que el widget se representa en la página HTML.
• this.jqElement: el elemento jQuery.
• this.getProperty(name): permite obtener el nombre de la propiedad.
• this.setProperty(name,value): permite definir el nombre y el valor de la propiedad.
• this.updateSelection(propertyName,selectedRowIndices): permite llamar a esta función cuando el widget cambie la propiedad en las filas seleccionadas. Estas filas tienen datos enlazados. Por ejemplo, en una llamada, si se ha definido un evento como onSelectStateChanged(), llame a la API this.updateSelection(propertyName,selectedRowIndices) y el sistema actualizará todos los widgets que sean dependientes de las filas seleccionadas.
Llamadas del tiempo de ejecución al widget
El tiempo de ejecución llama a las siguientes funciones del widget:
• runtimeProperties() (opcional): permite devolver una estructura JSON que defina las propiedades del widget.
Las propiedades opcionales son las siguientes:
|
Propiedad
|
Descripción
|
|---|---|
|
isContainer
|
Permite especificar si una instancia del widget puede ser un contenedor para otras instancias de widget. Los valores válidos son true y false. El valor por defecto de la propiedad es fasle.
|
|
needsDataLoadingAndError
|
Los valores válidos son true y false. El valor por defecto de la propiedad es fasle. Defina la propiedad en true si desea que el widget muestre la opacidad estándar del 25 % cuando no se reciba ningún dato. El widget se vuelve de color rojo cuando se produce un error al recuperar los datos.
|
|
borderWidth
|
Si el widget tiene un borde, defina esta propiedad en el ancho del borde. La propiedad ayuda a garantizar un diseño de píxeles perfectos durante el desarrollo y tiempo de ejecución.
|
|
supportsAutoResize
|
Permite especificar si el widget soporta automáticamente el cambio de tamaño. Los valores válidos son true y false.
|
|
propertyAttributes
|
Si hay propiedades STRING que se pueden localizar, enumérelas en esta propiedad.
Por ejemplo, si TooltipLabel1 se localizable:
this.runtimeProperties = function () {
return { 'needsDataLoadingAndError': true, 'propertyAttributes': { 'TooltipLabel1': {'isLocalizable': true} } } }; |
• renderHtml() (obligatorio): la función devuelve el fragmento de HTML que el tiempo de ejecución coloca en la pantalla. El contenedor de contenido del widget, por ejemplo, div, debe tener especificada una clase de contenido de widget. Una vez especificada la clase, el elemento contenedor se incorpora al DOM. Se puede acceder al contenedor mediante jqElement y el ID de elemento DOM está disponible en jqElementId.
• afterRender() (opcional): se llama a esta función después de insertar el fragmento de HTML del widget en DOM. Utilice this.domElementId para obtener el ID de elemento DOM. Utilice el elemento this.jqElement para obtener el elemento DOM jQuery.
• beforeDestroy() (opcional, pero muy recomendable): se llama a esta función cuando se quita el widget de la pantalla. Con esta función, se puede realizar lo siguiente:
◦ Desenlazar los enlaces.
◦ Despejar cualquier conjunto de datos con .data().
◦ Destruir las bibliotecas o plug-ins de terceros, llamar a sus destructores, etc.
◦ Liberar la memoria asignada o retenida en clausuras, definiendo todas las variables en null
◦ No es necesario destruir los elementos DOM del interior del widget, ya que el tiempo de ejecución los destruye.
◦ Destruya el DOM solo añadiendo el argumento DOMOnly a la función.
|
|
Para utilizar la carga diferida con el widget, añada el argumento DOMOnly a la función.
|
• resize(width,height) (opcional: solo es útil si el usuario declara supportsAutoResize: true); se llama a esta función cuando se cambia el tamaño del widget.
No es necesario gestionarlo para algunos widgets. Por ejemplo, si los elementos del widget y CSS se escalan automáticamente.
Sin embargo, se requiere gestionar para la mayoría de los widgets cuando cambia su tamaño.
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices): se llama a esta función cuando los orígenes de datos enlazados por la propiedad especificada modifican las filas seleccionadas. selectedRows es una matriz de los datos reales y selectedRowIndices es una matriz de los índices de las filas seleccionadas.
|
|
Esta funcionalidad se debe definir para obtener toda la funcionalidad del evento selectedRows sin tener que enlazar un widget de lista o rejilla.
|
• serviceInvoked(serviceName): la función se llama cuando se activa un servicio definido.
• updateProperty(updatePropertyInfo): updatePropertyInfo es un objeto con la estructura JSON que se indica a continuación.
{
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
}
Para cada enlace de datos, se llama a updateProperty() del widget cada vez que se modifican los datos de origen. Se debe verificar updatePropertyInfo.TargetProperty para determinar qué aspecto del widget se debe actualizar.
Consulte el siguiente ejemplo de 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);
}
}
};
Defina una copia local de la propiedad en el objeto de widget. De este modo, se garantiza que el sistema de tiempo de ejecución puede obtener la propiedad del contenedor de propiedades.
Como alternativa, se puede proporcionar un método getProperty_{propertyName} personalizado y almacenar el valor de algún otro modo.
• getProperty_{propertyName}(): cuando el tiempo de ejecución requiere el valor de la propiedad, se comprueba si el widget implementa una función para sustituir y obtener el valor de dicha propiedad. Se utiliza cuando el tiempo de ejecución obtiene los datos del widget para rellenar los parámetros de una llamada de servicio.