Технические новости
Разработчикам
Получение продукции на тестирование
Тестирование интерфейсов LogicMachine и Amati.linea
Совместимое периферийное оборудование
FAQ
Форум

ID виджета

Каждый пользовательский тип виджета должен иметь свой уникальный в рамках одного контроллера идентификатор (ID). В качестве ID может выступать любая строка.

ID виджета используется при установке виджета, фигурирует в его программном коде и не может быть легко изменен после установки виджета в приложение. Кроме как при установке ID виджета больше нигде не фигурирует в пользовательском интерфейсе. Для минимизации риска возникновения коллизий при использовании Вашего виджета в различных инсталляциях мы рекомендуем использовать в качестве ID набор символов, содержащий в себе часть, уникальную для разработчика виджета (префикс).

Кроме того, некоторые ID уже зарезервированы в системных виджетах, о чем приложение Вас проинформирует при попытке установки виджета.

Структура файлов виджета

Любой виджет представляет собой следующий набор файлов

  • script.js, обязательный файл в корневой папке виджета, который содержит JavaScript код, описывающий интерфейс виджета и логику его работы. Скрипт подгружается на страницу один раз вне зависимости от количества виджетов данного типа, которое было создано пользователем в конкретном приложении.
  • style.css, необязательный файл в корневой папке виджета, содержащий стили CSS, уникальные для Вашего виджета. При наличии его в папке с виджетом файл также будет автоматически подгружен при загрузке страницы.
  • любые другие графические, JavaScript, CSS файлы, которые будут использованы в Вашем виджете, но их подгрузку на страницу Вы должны гарантировать сами в одном из двух описанных выше файлов.

Мы рекомендуем использовать следующую структуру папок для виджета:

  • script.js
  • style.css
  • images
    1. графические файлы
  • js
    1. дополнительный JavaScript файлы и библиотеки.

Доступные библиотеки и фреймворки

В своем виджете Вы можете использовать следующий набор библиотек и фреймворков, уже включенных в проект:

Файл script.js

Перед прочтением дальнейшей части документации рекомендуем Вам ознакомится с документацией библиотеки Backbone.js http://backbonejs.org/ .

В своем JavaSctipt коде Вам необходимо в коллекции классов виджетов добавить свои расширения базовых классов Widget (модель) и WidgetView (представление), реализовав в них необходимый набор полей и методов, перечисленных в примере:

Widget["ID вашего виджета"] = Widget.extend({
/* описание настроек виджета*/
config : {
...
},
 
/*вызывается при изменении значений объектов контроллера Logic Machine*/
changeValue : function(name, value) {
...
}
}
 
WidgetView["ID вашего виджета"] = WidgetView.extend({
/*ширина виджета в ячейках*/
width : ...,
/*высота виджета в ячейках*/
height : ....,
 
/*вызывается при инициализации объекта*/
init : function() {
....
}
 
/*основной шаблон виджета*/
template : ...,
 
/*шаблон для предсмотра в режиме конструктора*/
preview : ....,
 
/*вызывается после отрисовки виджета при иницииализации*/
afterRender : function() { ...}
 
...
})

Вместо «ID вашего виджета» Вы должны использовать ID своего виджета и его же указать при установке виджета через интерфейс приложения. При реализации данных классов кроме описанных служебных атрибутов Вы можете реализовать любые свои вспомогательные методы и свойства, отвечающие за конвертацию данных, валидацию, вычисления, работу с DOM Вашего виджета и т. п.

Базовые классы Widget и WidgetView в свою очередь являются расширениями базовых классов модели (Backbone.Model) и представления (Backbone.View) Backbone соответственно и включают в себя набор вспомогательных методов для работы с объектами Logic Machine, которые могут использоваться в Вашей реализации.

Для каждого отдельного виджета данного типа, созданного пользователем приложения в конструкторе Mosaic, создается по одному экземпляру классов по следующему принципу:

model = new Widget[«ID вашего виджета»]();

view = new WidgetView[«ID вашего виджета»]({model:model});

Таким образом, вызов методов модели внутри самой модели должен осуществляться с указанием контекста this:

this.func()

Вызов же свойств и методов модели внутри представления должен осуществляться следующим образом:

this.model.func()

Конфигурация виджета

Все настройки виджета, необходимые для связывания его с объектами Logic Machine, а также другие настройки и данные, необходимые для формирования форм создания и редактирования в конструкторе Mosaic должны быть описаны Вами в свойстве config вашей модели.

Пример описания:

Widget["ID вашего виджета"] = Widget.extend({
config : {
title : "Name of widget",
fields : {
title : {
datatype : "string",
title : "Title"
}
},
objects : {
key : {
datatype : dt.bit,
title : "Object"
}
...
},
settings : {
"min-value" : {
datatype : "number",
title : "Minimum value"
}
...
},
systems:["blinds", "ac"]
},
...
}

Поле «title» служит для указания названия виджета, которое будет отображаться в режиме предпросмотра в списке виджетов и форме редактирования.

Поле «fields» служит для указания списка полей виджета, которые должны настраиваться пользователем в конструкторе. Ключи объекта будут использоваться для доступа к значениям этих свойств. Доступ к полям внутри модели будет осуществляться следующим образом this.field. Мы рекомендуем использовать это поле только для редактирования свойства title, а все остальные настройки виджета вынести в раздел settings.

Поле «settings» служит для указания списка настроек виджета, доступных для редактирования пользователем в режиме конструктора. Ключи объекта используются для доступа к настройкам с помощью вспомогательных методов, описанных ниже. Для каждого свойства необходимо указать название (title), которое будет отображаться в форме редактирования виджета и тип данных (datatype). В настоящий момент поддерживается два типа данных string и number.

Поле «objects» служит для указания списка объектов Logic Machine (групповых адресов), которые могут быть связаны с данным виджетом. Конкретные объекты должны быть указаны пользователем с помощью формы создания виджета в конструкторе Mosaic. Ключи объекта служат для доступа к значениям и свойствам объектов с помощью вспомогательных методов, описанных ниже. Для каждого объекта также необходимо указать название (title), которое будет отображаться в форме редактирования виджета и номер типа данных KNX. Полный список поддерживаемых типов данных приведен здесь http://openrb.com/docs/lua.htm#grp-info. Для указания конкретных числовых констант мы рекомендуем использовать предопределенный объект dt со списком полей, приведенным по ссылке выше. Если в качестве типа данных Вами указан конкретный подтип KNX то пользователю будет предложено выбрать объект только этого типа, если указан тип, включающий подтипы, то пользователю будет предложено выбрать объекты основного типа или любого из его подтипов.

Поле «systems» служит для указания списка инженерных систем, которое будет использовано в навигации Mosaic. Виджеты данного типа будут отображаться на экране всех инженерных систем, которые перечислены в массиве. Список идентификаторов инженерных систем, которые могут быть использованы:

  • lighting
  • blinds
  • power
  • windows
  • ac
  • ventilation
  • floor

Вспомогательные методы класса Widget (базовая модель)

Здесь приведен список предопределенных методов Widget, которые Вы можете использовать в своих моделях и представлениях.

Работа с объектами Logic Machine (групповыми адресами):

getValue(key)
Вернет текущее значение объекта.

existsValue(key)
Вернет true, если пользователь в конфигураторе Mosaic для данного виджета указал конкретный объект и false, если объект не указан.

getObject(key)
Вернет информацию об объекте с информацией о групповом адресе, включающий тип данных и название объекта.

Пример ответа:

{
updatetime:1461825143,
address : "1/1/1",
units "",
value : true,
name : "alarm",
datatype: 1005
}

write(key, value)
Записать значение объекта на контроллер (в шину).

Другие методы и свойства

conf(key)
Вернет значение настройки (описанной в разделе settings конфигурации виджета), которое указал пользователь.

title()
Вернет значение поля «title», которое указал пользователь при настройке виджета в конструкторе Mosaic.

сtitle()
Вернет название виджета, указанное в разделе «title» конфигурации виджета.

isPreview
Поле имеет значение true, если виджет отображается в режиме предпросмотра. Внимание! Виджет отображается в режиме предпросмотра до настройки пользователем, то есть для него еще не указано ни групповых адресов, ни других пользовательских настроек.

Вызов методов класса Widget

Для доступа к перечисленным выше вспомогательным функциями используйте правильный контекст.

Примеры вызова функции title():

  • в методах модели this.title()
  • в методах представления this.model.title()
  • в шаблонах title()

Вспомогательные методы класса WidgetView (базовое представление)

Список предопределенных методов WidgetView, которые Вы можете использовать в своих представлениях.

size(width, height)
Позволяет изменить размеры виджета после инициализации (на лету). Размер виджета должен указываться в количестве занятых ячеек. Размер одной ячейки составляет 110px*110px, но с учетом полей, реальные размеры виджета вычисляются по формуле (110*width-10) px * (110*height-10) px

el
Контейнер DOM-модели HTML документа, в который заключен Ваш виджет. Подробнее с его использованием можно ознакомится в документации к библиотеке Backbone.js http://backbonejs.org/#View-el . Мы рекомендуем использовать его везде, где Вы используете селекторы для доступа к DOM-модели Вашего виджета во избежание коллизий с другими виджетами.
Пример поиска на странице заголовка вашего виджета:

$(“div.widget-title”, this.el)

Методы класса WidgetView могут быть вызваны только из Вашего представления. Для доступа к ним используется контекст this (Например, this.size(1,2)).

Триггерные методы

Часть, описанных в структуре JS-файла методов представляют собой события и вызываются ядром программы в определенных случаях.

changeValue(key, value) для модели
Если Вы реализовали этот метод в своей модели, то он будет вызываться каждый раз, когда было изменено значение любого из объектов Logic Machine (групповых адресов), связанных с Вашим виджетом. В параметрах метода будут переданы ключ объекта (как указано в конфигурации) и его новое значение.

init() для представления
Если Вы реализовали этот метод в своем представлении, то он будет вызываться один раз при инициализации представления до его рендеринга (отрисовки), в нем можно инициализировать стартовые параметры представления, которые могут быть использованы в шаблоне при его отрисовке.

afterRender() для представлени
Если Вы реализовали этот метод в своем представлении, то он будет вызываться один раз сразу после отрисовки виджета. Его можно использовать для инициализации отдельных контролов, которые не могут быть сделаны в шаблоне (например, диммер knob).

Шаблоны виджета

В классе представления виджета Вам необходимо реализовать два метода:

template(model)
Будет вызван системой при инициализации виджета для его отрисовки в основном списке виджетов. В качестве входного параметра ему будет передан инициализированный экземпляр вашей модели.

preview(model
Будет вызван системой при инициализации виджета для его отрисовки в режиме предпросмотра в конструкторе Mosaic. Необходимо учитывать, что в данном случае модель не будет содержать объектов и настроек виджета, которые задаются пользователем при его создании в конструкторе.

Мы настоятельно рекомендуем использовать для шаблонизации метод _.template библиотеки Underscore.js http://underscorejs.org/#template , но Вы также можете использовать любой другой шаблонизатор или создавать DOM-объекты Вашего виджета на JavaScript. В таком случае не забывайте что весь виджет помещается в контейнер который можно получить в Вашем представлении как this.el

Все дальнейшие примеры в документации будут приведены с использованием библиотеки Underscore.js, которая уже включена в проект.

Рекомендуемая структура виджета

Чтобы к виджету были применены основные базовые классы системных виджетов мы рекомендуем использовать следующую структуру HTML в шаблоне

WidgetView["ID вашего виджета"] = WidgetView.extend({
...
template: _.template(" \
<div class=\"widget\"> \
<div class=\"widget-title\"> \
<div class=\"txt\"><%=title() || ctitle()%></div> \
</div> \
widget controls
</div> \
"),
...
})

Также Вы можете добавлять любые свои классы и задавать им стили в своем style.css или использовать другую структуру виджета на свое усмотрение. Помните, что все созданные Вами новые CSS классы для Вашего виджета могут оказать влияние на внешний вид других элементов приложения. Во избежание подобных коллизий мы рекомендуем использовать уникальные имена (например, со своим префиксом) для новых вводимых CSS классов.

Использование методов и свойств модели в шаблонах

Если для шаблонизации виджетов Вы используете метод _.template Underscore.js, то так как экземпляр модели виджета передается в качестве входного параметра в Ваш шаблон, вызывать любые методы модели и его свойства Вы можете в шаблоне напрямую без указания контекста.

Пример:

WidgetView["ID вашего виджета"] = WidgetView.extend({
...
template: _.template(" \
<div class=\"widget\"> \
<div class=\"widget-title\"> \
<div class=\"txt\"><%=title() || ctitle()%></div> \
</div> \
<% if (existsValue('object')) { %> \
Значение объекта <%= getValue('object')%> \
<% } %> \
</div> \
"),
...
})

Шаблон для предпросмотра

Для отображения, виджета в режиме предпросмотра в конструкторе Mosaic Вы можете реализовать отдельный метод, как в примере:

WidgetView["ID вашего виджета"] = WidgetView.extend({
...
template: _.template(" \
<div class=\"widget\"> \
<% if (existsValue(\"object\") { %> \
<%=getValue(\"object\")%> \
<% } %> \
</div> \
"),
preview: _.template(" \
<div class=\"widget\"> \
Object value \
</div> \
")
...
})

Если метод preview реализован не будет, то при инициализации виджета для предпросмотра будет вызван метод template. Таким образом для виджета может быть реализован один единый шаблон, но при этом нужно учитывать, что в режиме предпросмотра виджет не содержит объектов и настроек и все необходимые проверки должны быть сделаны в шаблоне.

Предыдущий пример с использованием единого шаблона для обоих режимов отображения виджета:

WidgetView["ID вашего виджета"] = WidgetView.extend({
...
template: _.template(" \
<div class=\"widget\"> \
<% if (isPreview) { %> \
Object value \
<% } else if (existsValue(\"object\")) { %> \
<%=getValue(\"object\")%> \
<% } %> \
</div> \
"),
...
})

Обмен данными между моделью и представлением

Как уже было сказано выше любые свойства модели доступны в представлении так как экземпляр объекта является его атрибутом, но не наоборот. При этом часто возникает ситуация, когда изменения атрибутов модели должны влиять на представление (отображение) виджета. В данном случае мы рекомендуем использовать события Backbone http://backbonejs.org/#Events .

Следующий пример иллюстрирует как вывести изменившиеся значение объекта на странице:

Widget["ID вашего виджета"] = Widget.extend({
...
changeValue : function(name, value) {
//иницируем событие
if (name=="status") return this.trigger("changedStatus");
...
}
...
}
 
WidgetView["ID вашего виджета"] = WidgetView.extend({
...
init : function() {
//подписываемся на конкретное событие модели
this.listenTo(this.model, "changedStatus", this.changedStatus);
},
template: _.template(" \
<div class=\"widget\"> \
<%=getValue(\"status\")%> \
</div> \
"),
changedStatus : function() {
//меняем значение в html коде
$(".widget", this.el).text(this.model.getValue("status"))
},
...
})




Copyright
© Embedded Systems Rus
2019. All Rights Reserved