Стандартные ссылки

Стандартные ссылки могут указывать на:

Таблицы данных, содержащие значения переменных контекста, ввод/вывод функций контекста или другие данные.

Отдельные ячейки вышеуказанных таблиц.

Свойства определений переменных/функций/событий контекста (их описания или флажки, указывающие доступна ли переменная для чтения/записи).
Свойства полей таблиц данных (например, тексты их описания и "справки").
И другие элементы единой модели данных.

Полный синтаксис стандартной ссылки: context:entity(parameter_list)$field[row]#property

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

Варианты синтаксиса

Таблица показывает и описывает различные возможные варианты синтаксиса стандартных ссылок:

Синтаксис	Описание	Аналог на базе функций
`field`	Возвращает значение ячейки таблицы данных, указанной field и рядом по умолчанию.	`cell(dt(), "field")`
`field[row]`	Возвращает значение ячейки таблицы данных по умолчанию, указанной field и row.	`cell(dt(), "field", row)`
`variable$`	Возвращает таблицу данных, представляющую значение variable в контексте по умолчанию.	`getVariable(dc(), "variable")`
`function(parameter_list)`	Вызывает function контекста по умолчанию с параметрами, указанными в parameter_list. Возвращает таблицу данных, представляющую выход функции.	`callFunction(dc(), "function", parameter_list)`
`variable$field`	Получает таблицу данных, представляющую значение variable из контекста по умолчанию. Возвращает значение ячейки этой таблицы данных, указанной field и рядом по умолчанию.	`cell(getVariable(dc(), "variable"), "field")`
`variable$field[row]`	Получает таблицу данных, представляющую значение variable из контекста по умолчанию. Возвращает значение ячейки этой таблицы данных, указанной field и row.	`cell(getVariable(dc(), "variable"), "field", row)`
`function(parameter_list)$field`	Получает таблицу данных, представляющую выходное значение, возвращаемое function контекста по умолчанию, которая вызывается с параметрами из parameter_list. Возвращает значение ячейки этой таблицы, указанной field и рядом по умолчанию.	`cell(callFunction(dc(), "function", parameter_list), "field")`
`function(parameter_list)$field[row]`	Получает таблицу данных, представляющую выходное значение, возвращаемое function контекста по умолчанию, которая вызывается с параметрами из parameter_list. Возвращает значение ячейки этой таблицы данных, указанной field и row.	`cell(callFunction(dc(), "function", parameter_list), "field", row)`
`context:variable`	Возвращает таблицу данных, представляющую значение variable в контексте (context).	`getVariable("context", "variable")`
`context:function(parameter_list)`	Вызывает function в контексте (context) с параметрами, указанными в parameter_list. Возвращает таблицу данных, представляющую выход функции.	`callFunction("context", "function", parameter_list)`
`context:variable$field`	Возвращает таблицу данных, представляющую значение variable в контексте (context). Возвращает значение ячейки этой таблицы данных, указанной field и рядом по умолчанию.	`cell(getVariable("context", "variable"), "field")`
`context:variable$field[row]`	Получает таблицу данных, представляющую значение variable из context. Возвращает значение ячейки этой таблицы данных, указанной field и row.	`cell(getVariable("context", "variable"), "field", row)`
`context:function(parameter_list)$field`	Получает таблицу данных, представляющую выходное значение, возвращаемое function контекста (context), которая вызывается с параметрами из parameter_list. Возвращает значение ячейки этой таблицы, указанной field и рядом по умолчанию.	`cell(callFunction("context", "function", parameter_list), "field")`
`context:function(parameter_list)$field[row]`	Получает таблицу данных, представляющую выходное значение, возвращаемое function контекста (context) которая вызывается с параметрами из parameter_list. Возвращает значение ячейки этой таблицы данных, указанной field и row.	`cell(callFunction("context", "function", parameter_list), "field", row)`
`.:`	Возвращает путь контекста по умолчанию.	`dc()`
`(empty reference text)`	Возвращает таблицу по умолчанию.	`dt()`

Ряд по умолчанию

Если ряд не задан, значение берется из:

текущего ряда, если обрабатывается каждый ряд таблицы данных в текущей среде;
ряда 0 (первый ряд в Таблице данных) в остальных случаях.

Полный синтаксис: context:entity(parameter_list)$field

Значение из Контекста по умолчанию: entity(parameter_list)$field

Значение из Таблицы данных по умолчанию: field

Контекст по умолчанию

Если в ссылке задан контекст, то данные берутся из него.

Если контекст не определен, данные берутся из контекста по умолчанию.

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

Пример: При работе с виджетами, контекстом по умолчанию является тот, из которого запускается виджет.

Относительные пути контекстов (например, devices.device1) разрешаются, начиная с данного контекста по умолчанию.

Пример: childInfo$firstname ссылается на контекст по умолчанию, в то время как users.admin:childInfo$firstname ссылается на определенный контекст.

{.:} ссылка вернет путь контекста по умолчанию. dc() функция также вернет этот путь.

Таблица данных по умолчанию

Подобно тому, что вы можете опустить контекстную часть ссылки и всё равно она будет пригодной, вы можете пропустить объектную часть (entity part). При ее пропуске, предполагается, что вы ссылаетесь на так называемую таблицу данных "по умолчанию", которая также называется "текущая таблица данных". Например, при фильтрации событий, таблица данных по умолчанию - таблица для фильтруемого на данный момент события.

Примером использования Таблицы данных по умолчанию может стать ссылка firstname. Это ссылка целиком -- просто firstname. Во время ее записи, вы предполагаете, что система "знает, что вы имеете в виду" -- т.е. она будет обращаться к полю firstname таблицы данных для каждого фильтруемого события, в случае фильтрации событий.

{} (пустая) ссылка вернет целую таблицу данных (которая может быть использована, например, функциями обработки таблиц данных). Функция dt() также вернет эту таблицу.

Разрешение объекта

Часть объекта, заданная в ссылке, является именем переменной или функции в контексте, на который вы ссылаетесь. Она рассматривается в качестве функции, если ссылка содержит в скобках parameter_list, и в качестве переменной, если не содержит. Таким образом, users.admin:childInfo ссылается на переменную, в то время как users.admin:delete()ссылается на функцию. Если объект, на который вы ссылаетесь (например, delete()), не существует, разрешение не будет выполнено.

Если ссылка указывает на функцию, она вызывается параметрами, заданными при помощи parameter_list во время разрешения.

Пример: Разрешение ссылки :register("charlie", "12345", "12345") приведет к выполнению функции register из корневого контекста.

Список параметров функции

parameter_list используется для создания таблицы данных согласно формату передаваемых функции параметров, как описано здесь.

Обработка ошибок

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

Разрешение свойств

Иногда вам может понадобиться задать свойство для определения какого-либо свойства контекста, переменной, функции, таблицы данных или поля таблицы данных.

Возможно у вас возникнет вопрос, в чем разница между полем и свойством. Поле содержит актуальные данные, а свойство - "метаданные", то есть данные о данных. Предположим, мы работаем с переменной version контекста server (его путь - server:version). Переменная содержит поле (тоже с именем version) с актуальными данными, например, "4.01.00" (версия сервера). Вы можете ссылаться на данное поле через server:version$version.

Та же переменная также имеет свойство description, содержащее данные о переменной. В этом случае, свойство будет содержать строку, "Версия сервера". Свойство не сохраняется в Таблице данных переменной - наоборот, оно "касается" определения переменной (а не ее значения). Вы можете сослаться на данное свойство через server:version#description.

Поэтому при ссылке на поле вы используете знак $, а при ссылке на свойство - знак #. Это важно, потому что поля часто имеют свойства (т.е. поле имеет описание). Более подробно об этом см. далее.

Свойства контекста

Синтаксис ссылки на свойство контекста: context:#property

Свойство	Тип	Описание
name	String	Имя контекста
description	String	Описание контекста.
type	String	Тип контекста.
icon	Image	Иконка контекста. Может использоваться компонентом виджета Изображение.

Свойства определения переменной

Синтаксис ссылки на свойство определения переменной: context:variable#property

Свойство	Тип	Описание
description	String	Описание переменной.
icon	Image	Иконка свойства. Может использоваться компонентом виджета Изображение.
readable	Boolean	True, если переменная доступна для чтения для текущего пользователя.
writable	Boolean	True, если переменная доступна для записи для текущего пользователя.

Свойства определения функции

Синтаксис ссылки на свойство определения функции: context:function(parameter_list)#property

Свойство	Тип	Описание
description	String	Описание функции

Свойства таблицы данных

Синтаксис ссылки на свойства Таблицы данных: context:entity(parameter_list)#property

Свойство	Тип	Описание
records	Integer	Количество записей в таблице. Может быть полезным для вычисления, сколько записей было получено в ответ на вашу ссылку. Например, `users:list()#records` вызывает функцию, просматривающую всех пользователей в системе и возвращает число записей в результате (т.е. сколько пользователей вы можете увидеть в системе согласно вашим правам доступа).
quality	Integer	Качество таблицы данных. Объясняет, насколько надежен экземпляр данных, представленный таблицей данных.
timestamp	Date	Временная метка значения таблицы данных. Некоторые части системы предоставляют информацию о времени вместе с образцом данных. Например, некоторые типы драйверов в качестве значения для этого свойства используют временную метку физического устройства, если это предусмотрено коммуникационным протоколом.

Свойства поля таблицы данных

Синтаксис ссылки на свойство поля Таблицы данных: context:entity(parameter_list)$field#property

Свойство	Тип	Описание
description	String	Описание поля
help	String	"Справка" поля (подробное описание)
svdesc	String	Описание значения выборки, т.е. строки, используемой для представления значения текущего поля в пользовательском интерфейсе.

Например, users.admin:childInfo$firstname возвращает что-то похожее на "John" (значение поля), в то время как users.admin:childInfo$firstname#description вернет нечто похожее на "Имя пользователя" (свойство описания поля).

Ссылки, состоящие только из свойств

Если ссылка состоит только из свойства (например, #property), она разрешается в следующее свойство:

Свойство	Тип	Описание
row	Integer	Данное свойство разрешается в текущий ряд обрабатываемой Таблицы данных. Например, когда виджет график основан на пользовательских данных, его таблица Исходные данные обрабатывается построчно. Рассчитываются выражения привязки Исходных данных для каждой строки. Таким образом, мы можем использовать `{#row}` в любом выражении Привязки исходных данных для создания последовательной серии или категории имен (0, 1, 2, ...).

Примеры

Текст ссылки	Комментарии
`recipient`	Данная ссылка возвращает значение поля `recipient` в таблице данных по умолчанию ("текущая таблица"). Это полезно, например, во время работы с выражениями фильтра событий.
`recipient[3]`	То же, что и выше, но значение берется из четвертого ряда.
`users.admin:childInfo$email`	Разрешается в значение поля `email` в Таблице данных, содержащего значение для переменной `childInfo` контекста `user.admin`. В данном случае будет содержать email адрес системного администратора.
`:info$description`	Данный пример начинается с двоеточия. Поэтому она ссылается на контекст "" (пустую строку), что является именем корневого контекста. Таким образом, ссылка вернет описание поля переменной info корневого контекста. Имейте в виду, что "description" - имя свойства, которое также может быть именем поля. Различие заключается в том, используете ли вы # или $ для ссылки на него.
`DS_setting#description`	Разрешается в описание свойства поля `DS_setting` в таблице данных по умолчанию.
`users.test.deviceservers.ds1:buzz()`	Разрешается в Таблицу данных, полученную в результате выполнения функции "Показать все устройства" в контексте users.test.deviceservers. Чтобы получить таблицу данных, должна быть вызвана функция "Показать все устройства", что заставит устройство ds1 Device Server моргать светодиодами.
`.:childInfo$firstname`	Разрешается в значение поля `firstname` переменной `childInfo` контекста по умолчанию ("текущего" контекста). Данная ссылка использует относительный контекстный путь ("."). Вы можете ничего не ставить перед двоеточием, однако, точка будет работать точно так же. Вы получите строку с именем пользователя ("Joe").
`.:childInfo$country#svdesc`	Возвращает название страны пользователя (т.е. описание значения выборки поля `country`). Имейте в виду, что `.:childInfo$country` вернет системный цифровой код страны.
`users.admin.deviceservers.ds1.devices.1:selfTest("quick")$status`	Данная ссылка указывает на поле `status`, возвращаемое функцией `selfTest`, определенной в контексте `users.admin.deviceservers.ds1.devices.1`. Данная функция вызывается с одним параметром.
`attendance:dailyActivityData('{.:}','{date}')`	Данная ссылка разрешится в Таблицу данных, полученную в результате выполнения функции `dailyActivityData`, определенной в контексте `attendance`. Данная функция вызывается с двумя параметрами: Результат оценки выражения `{.:}`, т.е. путь к контексту по умолчанию ("`.`"). Результат оценки выражения `{date}`, т.е. значение поля `date` в первом ряду таблицы данных по умолчанию.
`users.admin#icon`	Укажет на иконку контекста пользователя ().

DPF_EXPORT_V5.8.8 / TIME_1716484482 / 2024-05-23 17:14:42 / STRLEN_38191 / STRLEN_HTML_39816

{VERSION}