Функции, доступные для настройки виджетов ThingWorx
В этом разделе приведено описание функций, доступных для виджетов.
Жизненный цикл виджета в Mashup Builder
Для виджета существует следующий жизненный цикл в Mashup Builder. В каждом состоянии жизненного цикла Mashup Builder вызывает следующие функции, доступные для виджетов:
• Обнаружено
Виджет загружается в index.html и добавляется на панель инструментов или палитру виджетов.
|
Функция
|
Описание
|
|---|---|
|
widgetProperties()
|
Получение информации о каждом виджете в мэшапе. Загружается такая информация, как отображаемое имя и описание.
|
|
widgetEvents()
|
Получение информации о событиях, которые представляет каждый виджет.
|
|
widgetServices()
|
Получение информации о сервисах, которые представляет каждый виджет.
|
• Создано
Виджет добавляется на панель мэшапа.
|
Функция
|
Описание
|
|---|---|
|
afterload()
|
Вызывается после загрузки объекта и восстановления свойств из файла, но до визуализации объекта.
|
• Добавлено
Виджет добавляется в элемент DOM рабочей области.
|
Функция
|
Описание
|
|---|---|
|
renderHtml()
|
Получение фрагмента HTML, который вставляется в элемент DOM мэшапа.
|
|
afterRender()
|
Вызывается после вставки фрагмента HTML, представляющего виджет, в элемент DOM мэшапа и назначения элементу DOM, в котором находится содержимое виджета, доступного для использования ИД элемента. После этого элемент DOM готов к выполнению с ним действий.
|
• Обновлено
Размеры виджета изменяются, или виджет обновляется в окне свойств виджета.
|
Функция
|
Описание
|
|---|---|
|
beforeSetProperty()
|
Вызывается перед обновлением свойства виджета.
|
|
afterSetProperty()
|
Вызывается после обновления свойства виджета.
|
• Уничтожено
Виджет удаляется из мэшапа.
|
Функция
|
Описание
|
|---|---|
|
beforeDestroy()
|
Вызывается перед удалением элемента DOM виджета, данный виджет отсоединяется от родительского виджета и освобождается. Необходимо освободить такие ресурсы, как подключаемые модули и обработчики событий, которые получаются в жизненном цикле виджета. Чтобы поддерживать перезагрузку виджета в контейнере с отложенной загрузкой, необходимо добавить аргумент domOnly в функцию beforeDesctroy(), а затем уничтожать виджет только при значении false. Без использования аргумента domOnly форма виджета не перегружается правильно. Дополнительные сведения см. в разделе Использование отложенной загрузки в мэшапе.
|
Контейнер свойств
Контейнер свойств - это набор пар имя-значение. Каждая пара является простым хранилищем значений. ThingWorx использует контейнеры свойств как механизм сохранения структуры мэшапов.
Интерфейсы API Mashup Builder, доступные для виджетов
В контексте Mashup Builder можно получить доступ к следующим интерфейсам API.
• this.jqElementId - это идентификатор элемента DOM объекта после рендеринга виджета на странице HTML.
• this.jqElement - это элемент jQuery.
• this.getProperty(name) - загружает имя свойства.
• this.setProperty(name,value) - каждый вызов этой функции вызывает функцию afterSetProperty(), если функция afterSetProperty() определена в виджете.
• this.updatedProperties() - эта функция должна вызываться при изменении свойств в виджете. После вызова этой функции Mashup Builder обновляет окно свойств виджета.
• this.getInfotableMetadataForProperty(propertyName) - получает метаданные таблицы данных для свойства, которое связано с виджетом. Если свойство не привязано, возвращается значение "Не определено".
• this.resetPropertyToDefaultValue(propertyName) - сбрасывает указанное свойство до его значения по умолчанию.
• this.removeBindingsFromPropertyAsTarget(propertyName) - удаляет привязки целевых данных из указанного свойства.
• this.removeBindingsFromPropertyAsSource(propertyName) - удаляет привязки исходных данных из указанного свойства.
• this.isPropertyBoundAsTarget(propertyName) - проверяет, привязано ли данное свойство как целевое. Можно использовать эту функцию, чтобы определить, задано свойство или привязано. В следующем примере показано, как использовать функцию validate() в виджете "блог", чтобы определить, привязано ли свойство:
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) - проверяет, привязано ли свойство как исходное. Можно использовать эту функцию, чтобы определить, привязано ли свойство к целевому объекту. В следующем примере показано, как использовать функцию validate() в виджете флажка, чтобы определить, привязано ли свойство:
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;
}
Обратные вызовы из Mashup Builder в ваш виджет
Следующие функции в виджете вызываются из Mashup Builder для изменения поведения виджета.
• widgetProperties() [требуется] - возвращает структуру JSON, которая определяет свойства виджета.
Обязательные свойства:
◦ name - имя виджета, которое отображается на панели инструментов виджета.
Дополнительные свойства:
|
Свойство
|
Описание
|
|---|---|
|
description
|
Описание виджета, которое используется как всплывающая подсказка.
|
|
iconImage
|
Имя файла значка или изображения виджета.
|
|
category
|
Массив строк, определяющих категории, в которых доступен виджет.
Например, Общие, Диаграммы, Данные, Контейнеры и т. д. Это позволяет пользователю фильтровать виджеты по типу категории.
|
|
isResizable
|
Указывает, можно ли изменить размер виджета.
|
|
defaultBindingTargetProperty
|
Имя свойства, которое должно использоваться в качестве цели привязки данных или события.
|
|
borderWidth
|
Если виджет имеет границу, задайте в этом свойстве значение ширины границы. Это свойство помогает обеспечить точную до пикселя конструкцию во время разработки и во время выполнения.
Например, рассмотрим виджет, размер которого во время выполнения должен быть 10х10 пикселей с границей в 1 пиксель. Во время конструирования размер виджета должен быть 8х8 пикселей, чтобы можно было добавить во время конструирования 1 пиксель. Это позволяет разместить границу внутри виджета и задать в свойствах точную ширину и высоту виджета.
|
|
isContainer
|
Указывает, может ли экземпляр виджета быть контейнером для других экземпляров виджетов. Допустимые значения: true и false. Значение по умолчанию свойства: false.
|
|
customEditor
|
Имя диалогового окна пользовательского редактора, который нужно использовать для задания и правки конфигурации виджета. В проекте виджета создайте диалоговое окно с именем TW.IDE.Dialogs.<name>.
|
|
customEditorMenuText
|
Текст, который отображается во всплывающем меню виджета. Этот текст также отображается в виде всплывающей подсказки для виджетов в ThingWorx Composer. Например, Настроить столбцы сетки.
|
|
allowPositioning
|
Проверяет, может ли виджет быть помещен на панель. Допустимые значения: true и false. Значение по умолчанию свойства: true.
|
|
supportsLabel
|
Указывает, поддерживает ли виджет свойство "Метка". Допустимые значения: true и false. Значение по умолчанию свойства: false.
Если задано значение true, виджет отображает свойство "Метка". Это свойство используется для создания метки текста, которая отображается рядом с виджетом в ThingWorx Composer и во время выполнения.
|
|
supportsAutoResize
|
Указывает, будет ли виджет автоматически поддерживать изменение размеров. Допустимые значения: true и false. Значение по умолчанию свойства: false.
Если задано значение true, виджет может быть помещен в адаптивные контейнеры, такие как столбцы или строки, адаптивные вкладки и адаптивные мэшапы.
|
|
properties
|
Набор объектов JSON для виджета, описывающий свойства виджета, которые могут быть изменены при добавлении виджета в мэшап. Эти свойства отображаются в окне свойств Mashup Builder с именем каждого объекта, используемым в качестве имени свойства. Соответствующие атрибуты управляют заданием значения свойства.
Например:
properties: {
Prompt: { defaultValue: 'Search for...', baseType: STRING, isLocalizable: true }, Width: { defaultValue: 120 }, Height: { defaultValue: 20, isEditable: false }, } |
Для каждого объекта свойства можно указать следующие атрибуты.
|
Атрибут
|
Описание
|
||||
|---|---|---|---|---|---|
|
description
|
Описание виджета, используемое для его всплывающей подсказки.
|
||||
|
baseType
|
Базовый тип виджета. Если значение базового типа равно FIELDNAME, в окне свойств виджета отображается список полей, доступных в таблице данных. Поля привязываются к значению sourcePropertyName в соответствии с ограничением базового типа.
Ниже перечислены другие специальные базовые типы.
• STATEDEFINITION - выбор определения состояния.
• STYLEDEFINITION - выбор определения стиля.
• RENDERERWITHSTATE - отображает диалоговое окно, позволяющее выбрать формат рендеринга данных и состояния.
• STATEFORMATTING - отображение диалогового окна, позволяющего выбрать фиксированный стиль или стиль, соответствующий состоянию.
• VOCABULARYNAME - выбор словаря тегов данных во время выполнения.
|
||||
|
mustImplement
|
Если задан базовый тип THINGNAME и указан атрибут mustImplement, Mashup Builder ограничивает диалоговое окно и открывает только те всплывающие окна, в которых применяются указанные тип и наименование сущности. Mashup Builder вызывает функцию QueryImplementingThings, чтобы проверить, относится ли переданное значение к типу EntityType, и проверяет, применен ли параметр EntityName.
Например:
'baseType': 'THINGNAME',
'mustImplement': { 'EntityType': 'ThingShapes', 'EntityName': 'Blog' } |
||||
|
baseTypeInfotableProperty
|
Если задан базовый тип виджета RENDERERWITHFORMAT, атрибут указывает, какое свойство таблицы данных используется для конфигурации.
|
||||
|
sourcePropertyName
|
Если задан базовый тип виджета FIELDNAME, атрибут проверяет, какое свойство таблицы данных используется для конфигурации.
|
||||
|
baseTypeRestriction
|
Если указан этот атрибут, это значение используется для ограничения полей, доступных в выпадающем списке FIELDNAME.
|
||||
|
tagType
|
Если задан базовый тип TAGS, этот атрибут указывает тип тега. Допустимые значения: DataTags (значение по умолчанию) или ModelTags.
|
||||
|
defaultValue
|
Используется, чтобы задать значение по умолчанию для свойства. Значение по умолчанию не определено.
|
||||
|
isBindingSource
|
Указывает, является ли свойство источником привязки данных. Допустимые значения: true и false. Значение по умолчанию свойства: fasle.
|
||||
|
isBindingTarget
|
Указывает, является ли свойство целью привязки данных. Допустимые значения: true и false. Значение по умолчанию свойства: fasle.
|
||||
|
isEditable
|
Указывает, является ли свойство редактируемым в ThingWorx Composer. Допустимые значения: true (значение по умолчанию) и false.
|
||||
|
isVisible
|
Указывает, является ли свойство видимым в окне свойств. Допустимые значения: true и false. Значение по умолчанию свойства: true.
|
||||
|
isLocalizable
|
Указывает, можно ли локализовать свойство. Этот атрибут является обязательным, если задан базовый тип STRING. Допустимые значения: true и false.
|
||||
|
selectOptions
|
Массив структур значений или отображаемого текста.
Например:
[{value: ‘optionValue1’, text: ‘optionText1’},
{value: ‘optionValue2’, text: ‘optionText2’}] |
||||
|
warnIfNotBoundAsSource
|
ThingWorx Composer проверяет, является ли свойство источником привязки данных. Допустимые значения: true и false.
Если для атрибута задано значение true, но свойство не привязано, ThingWorx Composer создает список элементов, который необходимо заполнить для сохранения мэшапа.
|
||||
|
warnIfNotBoundAsTarget
|
Composer проверяет, является ли свойство целью привязки данных. Допустимые значения: true и false.
Если для атрибута задано значение true, но свойство не привязано, ThingWorx Composer создает список элементов, который необходимо заполнить для сохранения мэшапа.
|
• afterLoad() [необязательно] - функция вызывается после загрузки объекта и восстановления свойств из файла, но до визуализации объекта на странице HTML.
• renderHtml() [требуется] - функция возвращает фрагмент HTML, который ThingWorx Composer помещает на экране. Для контейнера содержимого виджета, например div, должен быть указан класс widget-content. После этого элемент контейнера добавляется в DOM. Контейнер доступен, если используется jqElement, а его идентификатор элемента DOM доступен в jqElementId.
• widgetEvents() [необязательно] - набор событий; каждое событие может иметь следующее свойство:
◦ warnIfNotBound - Composer проверяет, привязано ли свойство. Допустимые значения: true и false.
Если для атрибута задано значение true, но свойство не привязано, ThingWorx Composer создает список элементов, который необходимо заполнить для сохранения мэшапа.
• widgetServices() [необязательно] - набор сервисов; каждый сервис может иметь следующее свойство:
◦ warnIfNotBound - Composer проверяет, привязано ли свойство. Допустимые значения: true и false.
Если для атрибута задано значение true, но свойство не привязано, ThingWorx Composer создает список элементов, который необходимо заполнить для сохранения мэшапа.
• afterRender() [необязательно] - функция вызывается после вставки фрагмента HTML в DOM.
• beforeDestroy() [необязательно] - функция вызывается перед удалением элемента DOM виджета, данный виджет отсоединяется от родительского виджета и освобождается. Необходимо освободить такие ресурсы, как подключаемые модули, обработчики событий и т. п., которые получены во время жизни виджета.
• beforeSetProperty(name,value) [необязательно] [только Mashup Builder - не во время выполнения] - функция вызывается перед обновлением любого свойства в ThingWorx Composer. Можно выполнить проверки нового значения свойства перед его назначением. Если проверка завершилась неуспешно, можно возвратить строку сообщения, чтобы уведомить пользователя о недопустимом вводе. Новое значение свойства не принимается. Если во время проверки ничего не возвращается, значение считается допустимым.
• afterSetProperty(name,value) [необязательно] [только Mashup Builder - не во время выполнения] - функция вызывается после обновления любого свойства в ThingWorx Composer. Если задать значение true, то виджет будет снова визуализирован в ThingWorx Composer после изменения значения.
• afterAddBindingSource(bindingInfo) [необязательно] - эта функция вызывается при каждой привязке данных к виджету. Единственное поле в bindingInfo - это targetProperty, которое представляет собой имя свойства и которое привязано.
• validate() [необязательно] - функция вызывается при обновлении в ThingWorx Composer списка дел. Вызов возвращает массив объектов результата:
◦ severity - это необязательное свойство. Серьезность обнаруженной проблемы.
◦ сообщение - это обязательное свойство. Текст сообщения может содержать одну или несколько предопределенных лексем, например: {target-id}. Сообщение заменяется гиперссылкой, которая позволяет пользователю перемещаться и выбрать конкретный виджет, создавший сообщение.
Например:
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;
}