Функции времени выполнения, доступные для настройки виджетов ThingWorx
В этом разделе описаны функции, доступные для виджетов во время выполнения.
Жизненный цикл виджета во время выполнения
• При первом создании виджета среда выполнения получает все объявленные свойства путем вызова функции runtimeProperties().
Дополнительные сведения см. в разделе Обратные вызовы из среды выполнения в виджет.
• Значения свойств, которые сохраняются в определении мэшапа, загружаются в объект без вызова какой-либо функции.
• После загрузки виджета, но перед его рендерингом на экране среда выполнения вызывает функцию renderHtml(). Эта функция возвращает HTML для объекта. Среда выполнения выполняет рендеринг фрагмента HTML, возвращенного этой функцией, в соответствующем месте в DOM.
• После добавления HTML в DOM вызывается функция afterRender(). При необходимости можно выполнить привязывание jQuery. На этом этапе можно ссылаться на фактические элементы DOM. Например, можно использовать следующий код для ссылки на элементы DOM:
// note that this is a jQuery object
var widgetElement = this.domElement;
var widgetElement = this.domElement;
 |
Среда выполнения изменяет идентификатор вашего элемента DOM. Рекомендуется всегда использовать объект jQuery this.domElementId для получения идентификатора элемента DOM.
|
• Если определено событие, которое можно привязать, можно инициировать это событие, как показано в следующем примере:
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');
• При наличии каких-либо свойств, привязанных как цели данных, вызывается функция updateProperty(). Если измененное свойство оказывает влияние на DOM, необходимо обновить непосредственно DOM. При привязке данных DOM в большинстве случаев изменяется.
• При наличии свойств, которые определены как источники данных и привязаны к ним, можно вызвать функцию getProperty_{propertyName}(). Если эта функция не определена, среда выполнения получает значение из контейнера свойств.
Интерфейсы API времени выполнения, доступные для виджетов
К следующим интерфейсам API можно получить доступ из виджета в контексте времени выполнения.
• this.jqElementId - ИД элемента DOM объекта, после рендеринга виджета на странице HTML.
• this.jqElement - это элемент jQuery.
• this.getProperty(name) - получает имя свойства.
• this.setProperty(name,value) - задает имя и значение свойства.
• this.updateSelection(propertyName,selectedRowIndices) - эта функция вызывается, если свойство изменяется в виджете в выбранных строках. К этим строкам привязаны данные. Например, в обратном вызове - если было определено событие, например onSelectStateChanged(), то вызовите интерфейс API this.updateSelection(propertyName,selectedRowIndices), и система обновит все виджеты, которые зависят от выбранных строк.
Обратные вызовы из среды выполнения в ваш виджет
Следующие функции виджета вызываются средой выполнения:
• runtimeProperties() [необязательно] - возвращает структуру JSON, определяющую свойства виджета.
Дополнительные свойства:
|
Свойство
|
Описание
|
|---|---|
|
isContainer
|
Указывает, может ли экземпляр виджета быть контейнером для других экземпляров виджетов. Допустимые значения: true и false. Значение по умолчанию свойства: fasle.
|
|
needsDataLoadingAndError
|
Допустимые значения: true и false. Значение по умолчанию свойства: fasle. Задайте для свойства значение true, если требуется, чтобы отображение в виджете имело стандартную непрозрачность 25 % при отсутствии данных. Виджет становится красным, если возникает ошибка при загрузке данных.
|
|
borderWidth
|
Если виджет имеет границу, задайте в этом свойстве значение ширины границы. Это свойство помогает обеспечить точную до пикселя конструкцию во время разработки и во время выполнения.
|
|
supportsAutoResize
|
Указывает, будет ли виджет автоматически поддерживать изменение размеров. Допустимые значения: true и false.
|
|
propertyAttributes
|
При наличии свойств типа STRING, доступных для локализации, перечислите их в этом свойстве.
Например, TooltipLabel1 доступно для локализации:
this.runtimeProperties = function () {
return { 'needsDataLoadingAndError': true, 'propertyAttributes': { 'TooltipLabel1': {'isLocalizable': true} } } }; |
• renderHtml() [требуется] - функция возвращает фрагмент HTML, который среда выполнения помещает на экран. Для контейнера содержимого виджета, например, divдолжен быть указан класс виджета-содержимого. После задания класса элемент контейнера добавляется в DOM. Контейнер доступен, если используется jqElement, а его идентификатор элемента DOM доступен в jqElementId.
• afterRender() [необязательно] - эта функция вызывается после вставки фрагмента HTML виджета в DOM. Используйте this.domElementId, чтобы получить ИД элемента DOM. Используйте элемент this.jqElement, чтобы получить элемент DOM jQuery.
• beforeDestroy() [необязательно, но настоятельно рекомендуется] - вызывайте эту функцию, когда виджет удаляется с экрана. С помощью этой функции можно выполнять следующие действия:
◦ Отменить привязку всех привязок.
◦ Очистить любой набор данных, используя .data().
◦ Удалите все сторонние библиотеки или подключаемые модули, вызовите их деструкторы и т. д.
◦ Освободите какую-либо память, которая была выделена или содержится в замыканиях, задав для всех переменных значение null
◦ Не нужно уничтожать элементы DOM в виджете, они уничтожаются во время выполнения
◦ Удаляйте DOM только путем добавления аргумента DOMOnly в функцию.
|
|
Чтобы использовать отложенную загрузку с виджетом, добавьте аргумент DOMOnly в функцию.
|
• resize(width,height) [необязательно - применяется, только если объявить supportsAutoResize = true] - эта функция вызывается при изменении размера виджета.
Для некоторых виджетов такая обработка не нужна. Например, если элементы виджета и CSS автоматически масштабируются.
Однако для большинства виджетов требуется специальная обработка при изменении размеров виджета.
• handleSelectionUpdate(propertyName, selectedRows, selectedRowIndices) - эта функция вызывается при изменении выбранных строк источниками данных, привязанными к ним с помощью указанного свойства. selectedRows - массив фактических данных, а selectedRowIndices - массив индексов выбранных строк.
|
|
Необходимо определить эту функциональность, чтобы получить полную функциональность события selectedRows без необходимости привязки виджета списка или сетки.
|
• serviceInvoked(serviceName) - функция вызывается при инициировании определенного ранее сервиса.
• updateProperty(updatePropertyInfo) - updatePropertyInfo представляет собой объект со следующей структурой JSON:
{
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
}
Для каждой привязки данных при каждом изменении исходных данных в виджете вызывается объект updateProperty(). Необходимо установить флажок для updatePropertyInfo.TargetProperty, чтобы определить, какой аспект виджета должен обновляться.
См. следующий пример для виджета:
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);
}
}
};
Задайте локальную копию свойства в объекте виджета. Это обеспечивает для системы времени выполнения возможность получения этого свойства из контейнера свойств.
Кроме того, можно определить пользовательский метод getProperty_{propertyName} и сохранить значение каким-либо другим способом.
• getProperty_{propertyName}() - если во время выполнения требуется значение свойства, эта функция проверяет, реализована ли в виджете функция для переопределения и получения значения этого свойства. Используется, если среда выполнения получает данные из виджета, чтобы заполнить параметры для вызова сервиса.