Fonctions disponibles pour personnaliser les widgets ThingWorx
Cette rubrique décrit les fonctions disponibles pour les widgets.
Cycle de vie des widgets dans le Mashup Builder
Dans le Mashup Builder, le cycle de vie d'un widget est le suivant. A chaque état du cycle de vie, le Mashup Builder appelle les fonctions disponibles pour les widgets suivantes :
• Découvert
Le widget est chargé dans index.html et ajouté à la barre d'outils ou à la palette du widget.
|
Fonction
|
Description
|
|---|---|
|
widgetProperties()
|
Obtenez des informations sur chaque widget de l'application composite. Le nom affiché et la description sont notamment récupérés.
|
|
widgetEvents()
|
Obtenez des informations sur les événements exposés par chaque widget.
|
|
widgetServices()
|
Obtenez des informations sur les services exposés par chaque widget.
|
• Créé
Le widget est ajouté au panneau de l'application composite.
|
Fonction
|
Description
|
|---|---|
|
afterload()
|
Cette fonction est appelée une fois votre objet chargé et les propriétés restaurées à partir du fichier, mais avant que votre objet n'ait été rendu.
|
• Ajouté
Le widget est ajouté à l'élément DOM de l'espace de travail.
|
Fonction
|
Description
|
|---|---|
|
renderHtml()
|
Obtenez le fragment HTML inséré dans l'élément DOM de l'application composite.
|
|
afterRender()
|
Cette fonction est appelée après l'insertion dans l'élément DOM de l'application composite du fragment HTML représentant le widget et l'affectation d'un ID d'élément utilisable à l'élément DOM comprenant le contenu du widget. L'élément DOM est alors prêt à être manipulé.
|
• Mis à jour
Le widget est redimensionné ou mis à jour dans la fenêtre des propriétés du widget.
|
Fonction
|
Description
|
|---|---|
|
beforeSetProperty()
|
Cette fonction est appelée avant la mise à jour d'une propriété de widget.
|
|
afterSetProperty()
|
Cette fonction est appelée après la mise à jour d'une propriété de widget.
|
• Détruit
Le widget est supprimé de l'application composite.
|
Fonction
|
Description
|
|---|---|
|
beforeDestroy()
|
Cette fonction est appelée avant la suppression de l'élément DOM du widget, et avant la dissociation du widget de son widget parent et l'annulation de l'allocation. Vous devez libérer les ressources, telles que les plug-ins et les gestionnaires d'événements, acquises pendant la durée de vie du widget.
|
Sac de propriétés
Le sac de propriétés est un ensemble de paires nom-valeur. Chaque paire est un simple stockage de valeurs. ThingWorx utilise les sacs de propriétés comme un mécanisme de persistance de structure pour les applications composites.
API du Mashup Builder disponibles pour les widgets
Un widget peut accéder aux API suivantes dans le contexte du Mashup Builder :
• this.jqElementId : l'ID d'élément DOM de votre objet après le rendu du widget sur la page HTML.
• this.jqElement : l'élément jQuery.
• this.getProperty(name) : récupère le nom de la propriété.
• this.setProperty(name,value) : chaque appel à cette fonction appelle la fonction afterSetProperty(), si afterSetProperty() est défini dans le widget.
• this.updatedProperties() : cette fonction doit être appelée lorsque des propriétés sont modifiées dans le widget. Une fois la fonction appelée, le Mashup Builder met à jour la fenêtre des propriétés du widget.
• this.getInfotableMetadataForProperty(propertyName) : obtient les métadonnées de la table d'informations pour une propriété qui est liée. Renvoie undefined si la propriété n'est pas liée.
• this.resetPropertyToDefaultValue(propertyName) : rétablit la valeur par défaut de la propriété spécifiée.
• this.removeBindingsFromPropertyAsTarget(propertyName) : supprime les liaisons de données cibles de la propriété spécifiée.
• this.removeBindingsFromPropertyAsSource(propertyName) : supprime les liaisons de données source de la propriété spécifiée.
• this.isPropertyBoundAsTarget(propertyName) : vérifie si la propriété est liée en tant que cible. Vous pouvez utiliser la fonction pour déterminer si une propriété a été définie ou liée. Par exemple, l'extrait de code suivant illustre l'utilisation de la fonction validate() dans le widget Blog pour déterminer si une propriété est liée :
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) : vérifie si la propriété est liée en tant que source. Vous pouvez utiliser la fonction pour déterminer si une propriété a été liée à une cible. Par exemple, l'extrait de code suivant illustre l'utilisation de la fonction validate() dans le widget Case à cocher pour déterminer si une propriété est liée :
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;
}
Rappels depuis le Mashup Builder sur votre widget
Les fonctions suivantes sur le widget sont appelées par le Mashup Builder pour modifier le comportement d'un widget.
• widgetProperties() [obligatoire] : renvoie une structure JSON définissant les propriétés du widget.
Les propriétés requises sont les suivantes :
◦ name : nom du widget affiché dans la barre d'outils du widget.
Les propriétés facultatives sont les suivantes :
|
Propriété
|
Description
|
|---|---|
|
description
|
Description du widget, utilisée comme info-bulle.
|
|
iconImage
|
Nom du fichier d'icône ou d'image du widget.
|
|
category
|
Tableau de chaînes qui spécifie les catégories dans lesquelles le widget est disponible.
Par exemple, Commun, Graphiques, Données, Conteneurs, etc. Cela permet à l'utilisateur de filtrer les widgets selon le type de catégorie.
|
|
isResizable
|
Spécifie si le widget peut être redimensionné.
|
|
defaultBindingTargetProperty
|
Nom de la propriété à utiliser en tant que cible de liaison de données ou d'événements.
|
|
borderWidth
|
Si votre widget a une bordure, définissez cette propriété sur la largeur voulue de la bordure. Cette propriété vous permet d'obtenir un rendu parfait lors du développement et de l'exécution.
Prenons l'exemple d'un widget dont la taille à l'exécution doit être de 10 X 10 pixels avec une taille de bordure de 1 pixel. Au moment de la conception, la taille du widget doit être de 8 X 8 pixels pour gérer le pixel ajouté au moment de la conception. La bordure est placée à l'intérieur du widget et les propriétés de largeur et de hauteur du widget sont précises.
|
|
isContainer
|
Spécifie si une instance du widget peut faire office de conteneur pour d'autres instances du widget. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est false.
|
|
customEditor
|
Nom de la boîte de dialogue de l'éditeur personnalisé qui doit être utilisée pour définir et modifier la configuration du widget. Dans votre projet de widget, créez une boîte de dialogue avec le nom TW.IDE.Dialogs.<name>.
|
|
customEditorMenuText
|
Texte qui apparaît dans le menu contextuel du widget. Il s'agit également du texte qui apparaît en tant qu'info-bulle pour les widgets dans ThingWorx Composer. Par exemple, Configurer les colonnes de la grille.
|
|
allowPositioning
|
Vérifie si le widget peut être placé sur un panneau. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est true.
|
|
supportsLabel
|
Spécifie si le widget prend en charge la propriété Etiquette. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est false.
Lorsque cette option est définie sur true, le widget expose une propriété Etiquette. Cette propriété est utilisée pour créer une étiquette de texte qui apparaît à côté du widget dans ThingWorx Composer et à l'exécution.
|
|
supportsAutoResize
|
Spécifie si le widget prend automatiquement en charge le redimensionnement. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est false.
Lorsque cette option est définie sur true, le widget peut être placé dans des conteneurs dynamiques, tels que des colonnes, des lignes, des onglets dynamiques et des applications composites dynamiques.
|
|
properties
|
Collection d'objets JSON du widget qui décrivent les propriétés de ce dernier pouvant être modifiées lorsque le widget est ajouté à une application composite. Ces propriétés s'affichent dans la fenêtre de propriétés du Mashup Builder avec le nom de chaque objet utilisé comme nom de propriété. Les attributs correspondants contrôlent la façon dont la valeur de propriété est définie.
Par exemple :
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
Les attributs suivants peuvent être spécifiés pour chaque objet de propriété :
|
Attribut
|
Description
|
||||
|---|---|---|---|---|---|
|
description
|
Description du widget utilisé pour l'info-bulle.
|
||||
|
baseType
|
Type de base du widget. Si la valeur du type de base est FIELDNAME, la fenêtre de propriétés du widget affiche une liste des champs disponibles dans la table d'informations. Les champs sont liés à la valeur de sourcePropertyName en fonction de la restriction du type de base.
Les autres types de base spéciaux sont les suivants :
• STATEDEFINITION : sélectionne une définition d'état.
• STYLEDEFINITION : sélectionne une définition de style.
• RENDERERWITHSTATE : affiche une boîte de dialogue qui vous permet de sélectionner un rendu de données et un formatage d'état.
• STATEFORMATTING : affiche une boîte de dialogue qui vous permet de sélectionner un style fixe ou un style basé sur l'état.
• VOCABULARYNAME : sélectionne le vocabulaire des tags de données lors de l'exécution.
|
||||
|
mustImplement
|
Si le type de base est THINGNAME et que vous spécifiez l'attribut mustImplement, le Mashup Builder limite la boîte de dialogue afin de n'ouvrir que les fenêtres contextuelles qui implémentent le type (EntityType) et le nom (EntityName) d'entité spécifiés. Le Mashup Builder appelle la fonction QueryImplementingThings pour valider si la valeur transmise est de type EntityType et vérifie l'implémentation d'EntityName.
Par exemple :
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
Si le type de base du widget est défini sur RENDERERWITHFORMAT, l'attribut vérifie la propriété de la table d'informations utilisée pour la configuration.
|
||||
|
sourcePropertyName
|
Si le type de base du widget est défini sur FIELDNAME, l'attribut vérifie la propriété de la table d'informations utilisée pour la configuration.
|
||||
|
baseTypeRestriction
|
Si cet attribut est spécifié, la valeur est utilisée pour limiter les champs disponibles dans la liste déroulante FIELDNAME.
|
||||
|
tagType
|
Si le type de base est défini sur TAGS, l'attribut spécifie le type de tag. Les valeurs valides sont DataTags (valeur par défaut) et ModelTags.
|
||||
|
defaultValue
|
Permet de définir la valeur par défaut d'une propriété. La valeur par défaut est undefined.
|
||||
|
isBindingSource
|
Spécifie si la propriété est la source d'une liaison de données. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est fasle.
|
||||
|
isBindingTarget
|
Spécifie si la propriété est la cible d'une liaison de données. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est fasle.
|
||||
|
isEditable
|
Spécifie si la propriété est modifiable dans ThingWorx Composer. Les valeurs valides sont true (valeur par défaut) et false.
|
||||
|
isVisible
|
Spécifie si la propriété est visible dans la fenêtre des propriétés. Les valeurs possibles sont true et false. La valeur par défaut de la propriété est true.
|
||||
|
isLocalizable
|
Spécifie si la propriété peut être localisée. Cet attribut est obligatoire lorsque le type de base est défini sur STRING. Les valeurs possibles sont true et false.
|
||||
|
selectOptions
|
Ensemble de structures de valeurs ou de texte affiché.
Par exemple :
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer vérifie si la propriété est la source d'une liaison de données. Les valeurs possibles sont true et false.
Si la valeur de l'attribut est définie sur true, mais que la propriété n'est pas liée,ThingWorx Composer génère une liste d'éléments que vous devez compléter pour enregistrer l'application composite.
|
||||
|
warnIfNotBoundAsTarget
|
Composer vérifie si la propriété est la cible d'une liaison de données. Les valeurs possibles sont true et false.
Si la valeur de l'attribut est définie sur true, mais que la propriété n'est pas liée,ThingWorx Composer génère une liste d'éléments que vous devez compléter pour enregistrer l'application composite.
|
• afterLoad() [facultatif] : la fonction est appelée une fois votre objet chargé et les propriétés restaurées à partir du fichier, mais avant que votre objet n'ait été rendu sur la page HTML.
• renderHtml() [obligatoire] : la fonction renvoie le fragment HTML que ThingWorx Composer place à l'écran. Le conteneur de contenu du widget, par exemple div, doit posséder une classe widget-content spécifiée. L'élément conteneur est ensuite ajouté au DOM. Le conteneur est accessible via jqElement et son ID d'élément DOM est disponible dans jqElementId.
• widgetEvents() [facultatif] : collection d'événements ; chaque événement peut avoir la propriété suivante :
◦ warnIfNotBound : Composer vérifie si la propriété est liée. Les valeurs possibles sont true et false.
Si la valeur de l'attribut est définie sur true, mais que la propriété n'est pas liée,ThingWorx Composer génère une liste d'éléments que vous devez compléter pour enregistrer l'application composite.
• widgetServices() [facultatif] : collection de services ; chaque service peut avoir la propriété suivante :
◦ warnIfNotBound : Composer vérifie si la propriété est liée. Les valeurs possibles sont true et false.
Si la valeur de l'attribut est définie sur true, mais que la propriété n'est pas liée,ThingWorx Composer génère une liste d'éléments que vous devez compléter pour enregistrer l'application composite.
• afterRender() [facultatif] : la fonction est appelée après l'insertion du fragment HTML du widget dans le DOM.
• beforeDestroy() [facultatif] : la fonction est appelée avant la suppression de l'élément DOM du widget, et avant la dissociation du widget de son widget parent et l'annulation de l'allocation. Vous devez libérer les ressources, telles que les plug-ins et les gestionnaires d'événements, acquises pendant la durée de vie du widget.
• beforeSetProperty(name,value) [facultatif] [Mashup Builder uniquement - pas au moment de l'exécution] : la fonction est appelée avant la mise à jour d'une propriété dans ThingWorx Composer. Vous pouvez effectuer des validations sur la nouvelle valeur de propriété avant qu'elle ne soit confirmée. En cas d'échec de la validation, il est possible de renvoyer une chaîne de message pour informer l'utilisateur que l'entrée n'est pas valide. La nouvelle valeur de propriété n'est pas confirmée. Si aucun élément n'est renvoyé lors de la validation, la valeur est considérée comme valide.
• afterSetProperty(name,value) [facultatif] [Mashup Builder uniquement - pas au moment de l'exécution] : la fonction est appelée après la mise à jour d'une propriété dans ThingWorx Composer. Si la valeur est définie sur true, le rendu du widget sera de nouveau effectué dans ThingWorx Composer après modification de la valeur.
• afterAddBindingSource(bindingInfo) [facultatif] : cette fonction est appelée chaque fois que des données sont liées à votre widget. Le seul champ dans bindingInfo est targetProperty, qui correspond au nom de la propriété et est lié.
• validate() [facultatif] : la fonction est appelée lorsque ThingWorx Composer actualise sa liste de tâches. L'appel renvoie un ensemble d'objets de résultats :
◦ severity : propriété facultative. Elle indique la gravité du problème détecté.
◦ message : propriété obligatoire. Le texte du message peut contenir un ou plusieurs jetons prédéfinis, tels que {target-id}. Le message est remplacé par un lien hypertexte qui permet à l'utilisateur d'accéder au widget spécifique qui a généré le message et de le sélectionner.
Par exemple :
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;
}