Fonctions disponibles à l'exécution pour personnaliser les widgets ThingWorx
Cette rubrique décrit les fonctions disponibles pour les widgets à l'exécution.
Cycle de vie des widgets dans le runtime
• Lorsqu'un widget est créé pour la première fois, le runtime récupère toutes les propriétés déclarées en appelant la fonction runtimeProperties().
• Les valeurs de propriété enregistrées dans la définition d'application composite sont chargées dans votre objet sans qu'aucune fonction ne soit appelée.
• Une fois le widget chargé, mais avant qu'il ne soit rendu à l'écran, le runtime appelle la fonction renderHtml(). Dans cette fonction, vous renvoyez le code HTML pour votre objet. Le runtime restitue le code HTML renvoyé par la fonction à l'emplacement approprié dans le DOM.
• Une fois le code HTML ajouté au DOM, la fonction afterRender() est appelée. Si nécessaire, vous pouvez effectuer des liaisons jQuery. A ce stade, vous pouvez référencer les éléments réels du DOM. Par exemple, utilisez le code suivant pour référencer les éléments DOM :
// note that this is a jQuery object
var widgetElement = this.domElement;
var widgetElement = this.domElement;
 |
Le runtime modifie l'ID de l'élément DOM. Il est recommandé de toujours utiliser l'objet jQuery this.domElementId pour obtenir l'ID de l'élément DOM.
|
• Si vous avez défini un événement qui peut être lié, vous pouvez déclencher l'événement, comme illustré dans l'exemple suivant :
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 des propriétés sont liées en tant que cibles de données, la fonction updateProperty() est appelée. Vous devez mettre à jour le DOM directement s'il est affecté par propriété modifiée. Lorsque les données sont liées, le DOM change dans la plupart des cas.
• Si des propriétés sont définies comme sources de données et qu'elles sont liées, vous pouvez appeler la fonction getProperty_{propertyName}(). Si vous ne définissez pas cette fonction, le runtime obtient la valeur à partir du sac de propriétés.
API d'exécution disponibles pour les widgets
Un widget peut accéder aux API suivantes dans le contexte de l'exécution :
• 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) : obtient le nom de la propriété.
• this.setProperty(name,value) : définit le nom et la valeur de la propriété.
• this.updateSelection(propertyName,selectedRowIndices) : appelez cette fonction lorsque votre widget modifie la propriété sur les lignes sélectionnées. Des données sont liées à ces lignes. Par exemple, dans un rappel, si vous avez défini un événement tel que onSelectStateChanged(), vous pouvez appeler l'API this.updateSelection(propertyName,selectedRowIndices) et le système met alors à jour tous les widgets dépendants des lignes sélectionnées.
Rappels depuis le runtime sur votre widget
Les fonctions suivantes sur le widget sont appelées par le runtime :
• runtimeProperties() [facultatif] : renvoie une structure JSON définissant les propriétés du widget.
Les propriétés facultatives sont les suivantes :
|
Propriété
|
Description
|
|---|---|
|
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 fasle.
|
|
needsDataLoadingAndError
|
Les valeurs possibles sont true et false. La valeur par défaut de la propriété est fasle. Définissez la propriété sur true si vous souhaitez que le widget utilise le réglage d'opacité standard de 25 % en l'absence de données. Le widget devient rouge en cas d'erreur lors de la récupération des données.
|
|
borderWidth
|
Si le 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.
|
|
supportsAutoResize
|
Spécifie si le widget prend automatiquement en charge le redimensionnement. Les valeurs possibles sont true et false.
|
|
propertyAttributes
|
Si vous disposez de propriétés STRING localisables, répertoriez-les dans cette propriété.
Par exemple, si TooltipLabel1 est localisable :
this.runtimeProperties = function () {
return { 'needsDataLoadingAndError': true, 'propertyAttributes': { 'TooltipLabel1': {'isLocalizable': true} } } }; |
• renderHtml() [obligatoire] : la fonction renvoie le fragment HTML que le runtime place à l'écran. Le conteneur de contenu du widget, par exemple div, doit posséder une classe widget-content spécifiée. Une fois la classe spécifiée, l'élément conteneur est ajouté au DOM. Le conteneur est accessible via jqElement et son ID d'élément DOM est disponible dans jqElementId.
• afterRender() [facultatif] : cette fonction est appelée après l'insertion du fragment HTML du widget dans le DOM. Utilisez this.domElementId pour obtenir l'ID d'élément DOM. Utilisez l'élément this.jqElement pour obtenir l'élément DOM jQuery.
• beforeDestroy() [facultatif mais fortement recommandé] : appelez cette fonction lorsque le widget est supprimé de l'écran. Avec cette fonction, vous pouvez :
◦ dissocier les liaisons ;
◦ effacer tous jeux de données avec .data() ;
◦ détruire toutes bibliothèques ou tous plug-ins tiers, appeler leurs destructeurs, etc ;
◦ libérer la mémoire allouée ou conservée en closures en définissant toutes les variables sur null ;
◦ vous n'avez pas besoin de détruire les éléments DOM à l'intérieur du widget, ils seront détruits par le runtime.
• resize(width,height) [facultatif - utile uniquement si vous définissez supportsAutoResize sur "vrai"] : cette fonction est appelée lorsque votre widget est redimensionné.
Certains widgets n'ont pas besoin de cet appel. Par exemple, en cas de mise à l'échelle automatique des éléments du widget et du CSS.
Toutefois, la plupart des widgets nécessitent une manipulation lorsque la taille du widget change.
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) : cette fonction est appelée lorsque les lignes sélectionnées sont modifiées par les sources de données liées avec la propriété spécifiée. selectedRows est un tableau des données réelles, et selectedRowIndices est un tableau des indices des lignes sélectionnées.
|
|
Vous devez définir cette fonctionnalité pour obtenir la fonctionnalité complète de l'événement selectedRows sans avoir à lier un widget liste ou grille.
|
• serviceInvoked(serviceName) : cette fonction est appelée lorsqu'un service que vous avez défini est déclenché.
• updateProperty(updatePropertyInfo) : updatePropertyInfo est un objet avec la structure JSON suivante :
{
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
}
Pour chaque liaison de données, la commande updateProperty() de votre widget est appelée chaque fois que les données source sont modifiées. Vous devez examiner updatePropertyInfo.TargetProperty pour déterminer quel aspect de votre widget doit être mis à jour.
Observez l'exemple suivant pour 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);
}
}
};
Définissez une copie locale de la propriété dans l'objet widget. Ce faisant, vous vous assurez que le système d'exécution pourra récupérer la propriété à partir du sac de propriétés.
Vous pouvez également fournir une méthode getProperty_{propertyName} personnalisée et stocker la valeur d'une autre manière.
• getProperty_{propertyName}() : lorsque le runtime a besoin de la valeur d'une propriété, il vérifie si votre widget implémente une fonction pour remplacer et obtenir la valeur de cette propriété. Est utilisée lorsque le runtime reçoit les données de votre widget pour renseigner les paramètres d'un appel de service.