Funciones disponibles para la personalización de los widgets de ThingWorx
En esta sección se describen las funciones disponibles para los widgets.
Ciclo de vida del widget en Mashup Builder
Un widget tiene el siguiente ciclo de vida en Mashup Builder. En cada estado del ciclo de vida, Mashup Builder llama a las siguientes funciones que están disponibles para los widgets:
• Detectado
El widget se carga en index.html y se añade a la barra de herramientas o la paleta de widgets.
|
Función
|
Descripción
|
|---|---|
|
widgetProperties()
|
Permite obtener información sobre cada uno de los widgets del mashup. Se recupera información como, por ejemplo, el nombre mostrado y la descripción.
|
|
widgetEvents()
|
Permite obtener información sobre los eventos que se exponen en cada widget.
|
|
widgetServices()
|
Permite obtener información sobre los servicios que se exponen en cada widget.
|
• Creado
El widget se añade al panel de mashups.
|
Función
|
Descripción
|
|---|---|
|
afterload()
|
Se invoca después de que se cargue el objeto y se hayan restaurado las propiedades del fichero, pero antes de que se haya representado el objeto.
|
• Incorporados
El widget se incorpora al elemento DOM del espacio de trabajo.
|
Función
|
Descripción
|
|---|---|
|
renderHtml()
|
Permite obtener el fragmento de HTML que está insertado en el elemento DOM del mashup.
|
|
afterRender()
|
Se invoca después de insertar el fragmento de HTML que representa el widget en el elemento DOM del mashup y se asigna un ID de elemento utilizable al elemento DOM que incluye el contenido del widget. Después, el elemento DOM está listo para la manipulación.
|
• Actualizado
El widget cambia de tamaño o se actualiza en la ventana de propiedades del widget.
|
Función
|
Descripción
|
|---|---|
|
beforeSetProperty()
|
Se invoca antes de que se actualice una propiedad de widget.
|
|
afterSetProperty()
|
Se invoca después de actualizar una propiedad de widget.
|
• Destruido
El widget se borra del mashup.
|
Función
|
Descripción
|
|---|---|
|
beforeDestroy()
|
Se invoca antes de que se quite el elemento DOM del widget y el widget se desconecte del widget padre y se anule la asignación. Se deben liberar los recursos, tales como los plug-ins y los controladores de eventos que se adquieren durante la vida del widget.
|
Bolsa de propiedades
La bolsa de propiedades es un conjunto de pares de nombre y valor. Cada par es un almacén de valores simple. ThingWorx utiliza bolsas de propiedades como mecanismo de persistencia de estructuras para mashups.
API de Mashup Builder disponibles para widgets
Un widget puede acceder a las siguientes API en el contexto de Mashup Builder:
• this.jqElementId: el ID del elemento DOM del objeto después de que el widget se haya representado en la página HTML.
• this.jqElement: el elemento jQuery.
• this.getProperty(name): se recupera el nombre de la propiedad.
• this.setProperty(name,value): cada llamada a esta función llama a la función afterSetProperty(), si afterSetProperty() se ha definido en el widget.
• this.updatedProperties(): esta función debe invocarse cuando se cambian las propiedades del widget. Después de llamar a la función, Mashup Builder actualiza la ventana de propiedades del widget.
• this.getInfotableMetadataForProperty(propertyName): permite obtener los metadatos de InfoTable para una propiedad que está enlazada. Se devuelve undefined si la propiedad no está enlazada.
• this.resetPropertyToDefaultValue(propertyName): permite redefinir en el valor por defecto la propiedad especificada.
• this.removeBindingsFromPropertyAsTarget(propertyName): permite quitar de la propiedad especificada los enlaces de datos de destino.
• this.removeBindingsFromPropertyAsSource(propertyName): permite quitar de la propiedad especificada los enlaces de datos de origen.
• this.isPropertyBoundAsTarget(propertyName): permite verificar si la propiedad está enlazada como destino. La función se puede utilizar para determinar si una propiedad se ha definido o enlazado. Por ejemplo, en el siguiente ejemplo se muestra cómo utilizar la función validate() en el widget de blog para determinar si una propiedad está enlazada:
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): permite verificar si la propiedad se ha enlazado como origen. Se puede utilizar la función para determinar si una propiedad se ha enlazado a un destino. Por ejemplo, en el siguiente ejemplo se muestra cómo utilizar la función validate() en el widget de casilla para determinar si una propiedad está enlazada:
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;
}
Llamadas de Mashup Builder al widget
Mashup Builder llama a las siguientes funciones del widget para modificar el comportamiento de un widget.
• widgetProperties() (obligatorio): permite devolver una estructura JSON que define las propiedades del widget.
Las propiedades obligatorias son las siguientes:
◦ name: nombre del widget que se muestra en la barra de herramientas del widget.
Las propiedades opcionales son las siguientes:
|
Propiedad
|
Descripción
|
|---|---|
|
Descripción
|
Descripción del widget, que se utiliza como sugerencia.
|
|
iconImage
|
Nombre de fichero del icono o la imagen del widget.
|
|
category
|
Matriz de cadenas que especifican las categorías en las que está disponible el widget.
Por ejemplo, Comunes, Gráficos, Datos, Contenedores, etc. De este modo, el usuario puede filtrar los widgets según el tipo de categoría.
|
|
isResizable
|
Permite especificar si se puede cambiar el tamaño del widget.
|
|
defaultBindingTargetProperty
|
Nombre de la propiedad que se debe utilizar como destino de enlace de datos o eventos.
|
|
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 en tiempo de ejecución.
Por ejemplo, considere un widget cuyo tamaño en tiempo de ejecución debe ser 10X10 píxeles con un tamaño de borde de 1 píxel. En la fase de diseño, el tamaño del widget debe ser 8X8 píxeles para gestionar el píxel añadido en la fase de diseño. De este modo, el borde se coloca dentro del widget y hace que el ancho y la altura de las propiedades del widget sean precisos.
|
|
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 false.
|
|
customEditor
|
Nombre del cuadro de diálogo del editor personalizado que se debe utilizar para definir y editar la configuración del widget. En el proyecto de widget, cree un cuadro de diálogo con el nombre TW.IDE.Dialogs.<name>.
|
|
customEditorMenuText
|
El texto que aparece en el menú emergente del widget. También es el texto que aparece como sugerencia para los widgets de ThingWorx Composer. Por ejemplo, Configurar columnas de cuadrícula.
|
|
allowPositioning
|
Permite verificar si el widget se puede colocar en un panel. Los valores válidos son true y false. El valor por defecto de la propiedad es true.
|
|
supportsLabel
|
Permite especificar si el widget soporta la propiedad Rótulo. Los valores válidos son true y false. El valor por defecto de la propiedad es false.
Cuando se define en true, el widget expone una propiedad de rótulo. Esta propiedad se utiliza para crear un rótulo de texto que aparece junto al widget en ThingWorx Composer y en 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. El valor por defecto de la propiedad es false.
Cuando se define en true, el widget se puede colocar en contenedores dinámicos, como columnas, filas, fichas dinámicas y mashups dinámicos.
|
|
properties
|
Una recopilación de objetos JSON para el widget que describen las propiedades del widget que se pueden modificar cuando el widget se añade a un mashup. Estas propiedades se muestran en la ventana de propiedades de Mashup Builder con el nombre de cada objeto que se utiliza como nombre de propiedad. Los atributos correspondientes controlan cómo se define el valor de la propiedad.
Por ejemplo:
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
Se pueden especificar los siguientes atributos para cada objeto de propiedad:
|
Atributo
|
Descripción
|
||||
|---|---|---|---|---|---|
|
Descripción
|
Descripción del widget que se utiliza para la sugerencia.
|
||||
|
baseType
|
Tipo base del widget. Si el valor de tipo base es FIELDNAME, en la ventana de propiedades del widget se muestra una lista de campos disponibles en la InfoTable. Los campos se enlazan al valor sourcePropertyName en función de la restricción de tipo base.
Los demás tipos base especiales son:
• STATEDEFINITION: permite seleccionar una definición de estado.
• STYLEDEFINITION: permite seleccionar una definición de estilo.
• RENDERERWITHSTATE: permite mostrar un cuadro de diálogo en el que se puede seleccionar un procesador de datos y un formato de estado.
• STATEFORMATTING: permite mostrar un cuadro de diálogo en el que se puede seleccionar un estilo fijo o un estilo basado en estado.
• VOCABULARYNAME: permite seleccionar el vocabulario de etiquetas de datos en tiempo de ejecución.
|
||||
|
mustImplement
|
Si el tipo base es THINGNAME y se especifica el atributo mustImplement, Mashup Builder restringe el cuadro de diálogo para abrir solo los elementos emergentes que permiten implementar los valores de Tipo de entidad y Nombre de entidad especificados. Mashup Builder llama a la función QueryImplementingThings para validar si el valor pasado es de la clase Tipo de entidad y verifica si se ha implementa Nombre de entidad.
Por ejemplo:
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
Si el tipo base del widget se define en RENDERERWITHFORMAT, el atributo especifica la propiedad de InfoTable que se utiliza para la configuración.
|
||||
|
sourcePropertyName
|
Si el tipo base del widget se define en FIELDNAME, el atributo verifica qué propiedad de InfoTable se utiliza para la configuración.
|
||||
|
baseTypeRestriction
|
Si se especifica este atributo, el valor se utiliza para restringir los campos disponibles en la lista desplegable FIELDNAME.
|
||||
|
tagType
|
Si el tipo base se define en TAGS, el atributo especifica el tipo de etiqueta. Los valores válidos son DataTags, que es el valor por defecto, o ModelTags.
|
||||
|
defaultValue
|
Se utiliza para definir el valor por defecto de una propiedad. El valor por defecto no está definido.
|
||||
|
isBindingSource
|
Permite especificar si la propiedad es un origen de enlace de datos. Los valores válidos son true y false. El valor por defecto de la propiedad es fasle.
|
||||
|
isBindingTarget
|
Permite especificar si la propiedad es un destino de enlace de datos. Los valores válidos son true y false. El valor por defecto de la propiedad es fasle.
|
||||
|
isEditable
|
Permite especificar si la propiedad es editable enThingWorx Composer. Los valores válidos son true que es el valor por defecto y false.
|
||||
|
isVisible
|
Permite especificar si la propiedad está visible en la ventana de propiedades. Los valores válidos son true y false. El valor por defecto de la propiedad es true.
|
||||
|
isLocalizable
|
Permite especificar si la propiedad se puede localizar. Este atributo es obligatorio cuando el tipo base se ha definido en STRING. Los valores válidos son true y false.
|
||||
|
selectOptions
|
Una matriz de estructuras de texto de visualización o valores.
Por ejemplo:
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer verifica si la propiedad es un origen de enlace de datos. Los valores válidos son true y false.
Si el valor de atributo se define en true, pero la propiedad no está enlazada, ThingWorx Composer genera una lista de elementos que se deben completar para guardar el mashup.
|
||||
|
warnIfNotBoundAsTarget
|
Composer verifica si la propiedad es un destino de enlace de datos. Los valores válidos son true y false.
Si el valor de atributo se define en true, pero la propiedad no está enlazada, ThingWorx Composer genera una lista de elementos que se deben completar para guardar el mashup.
|
• afterLoad() (opcional): se llama a la función después de cargar el objeto y restaurar las propiedades desde el fichero, pero antes de que el objeto se represente en la página HTML.
• renderHtml() (obligatorio): la función devuelve el fragmento HTML que ThingWorx Composer coloca en la pantalla. El contenedor de contenido del widget, por ejemplo, div, debe tener especificada una clase de contenido de widget. Después, el elemento contenedor se incorpora al DOM. Se puede acceder al contenedor mediante jqElement y el ID de elemento DOM está disponible en jqElementId.
• widgetEvents() (opcional): una recopilación de eventos. Cada evento puede tener la propiedad que se indica a continuación.
◦ warnIfNotBound: Composer verifica si la propiedad está enlazada. Los valores válidos son true y false.
Si el valor de atributo se define en true, pero la propiedad no está enlazada, ThingWorx Composer genera una lista de elementos que se deben completar para guardar el mashup.
• widgetServices() (opcional): una recopilación de servicios. Cada servicio puede tener la propiedad que se indica a continuación.
◦ warnIfNotBound: Composer verifica si la propiedad está enlazada. Los valores válidos son true y false.
Si el valor de atributo se define en true, pero la propiedad no está enlazada, ThingWorx Composer genera una lista de elementos que se deben completar para guardar el mashup.
• afterRender() (opcional): se llama a la función después de insertar el fragmento de HTML en DOM.
• beforeDestroy() (opcional): la función se invoca antes de que se quite el elemento DOM del widget y el widget se desconecte de su widget padre y se anule la asignación. Se deben liberar los recursos, tales como plug-ins, controladores de eventos, etc., adquiridos durante toda la vida del widget.
• beforeSetProperty(name,value) (opcional) (solo Mashup Builder; no en tiempo de ejecución): se llama a la función antes de que se actualice cualquier propiedad en ThingWorx Composer. Se pueden realizar validaciones en el nuevo valor de propiedad antes de confirmarlo. Si la validación falla, se puede devolver una cadena de mensaje para informar al usuario acerca de la entrada no válida. El nuevo valor de la propiedad no se confirma. Si no se devuelve nada durante la validación, se supone que el valor es válido.
• afterSetProperty(name,value) (opcional) (solo Mashup Builder: no en tiempo de ejecución): se llama a la función después de que se actualice cualquier propiedad en ThingWorx Composer. Si el valor se especifica en true, el widget se vuelve a representar en ThingWorx Composer después de que se cambie el valor.
• afterAddBindingSource(bindingInfo) (opcional): se llama a esta función siempre que haya datos enlazados al widget. El único campo de bindingInfo es targetProperty, que es el nombre de la propiedad y está enlazado.
• validate()(opcional): se llama a la función cuando ThingWorx Composer renueva la lista de tareas pendientes. La llamada devuelve una matriz de objetos de resultados:
◦ severity: se trata de una propiedad opcional. La gravedad del problema detectado.
◦ message: es una propiedad obligatoria. El texto del mensaje puede contener uno o varios tokens predefinidos, como {target-id}. El mensaje se reemplaza por un hipervínculo que permite al usuario navegar y seleccionar el widget específico que ha generado el mensaje.
Por ejemplo:
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;
}