Источники данных
С помощью источников данных виджеты и боковые панели получают данные для отображения.
Стандартные источники получают данные от провайдеров данных, используя выборку. Существуют и другие способы получения данных: из локального хранилища браузера, значения по умолчанию, наследуемые источники и др. О каждом случае будет рассказано далее.
Местоположение источников#
Источники задаются на странице <page> или в структуре приложения <application> с помощью элемента <datasources>.
Источники данных на странице#
Наиболее частым случаем является задание источника на странице для заполнения виджета данными.
<page xmlns="http://n2oapp.net/framework/config/schema/page-4.0"> <datasources> <!-- Источники данных страницы --> <datasource id="main"/> <datasource id="docs"/> <datasource id="addresses"/> </datasources></page>На такой источник данных можно сослаться из виджета с помощью атрибута datasource:
<form datasource="main"> ...</form>note
Из разных виджетов можно ссылаться на один и тот же источник данных. В этом случае они все будут оперировать одними и теми же данными.
Вложенный источник данных в виджете#
Источник данных можно создать внутри виджета, если данные нужны только этому виджету.
В этом случае не нужно задавать идентификатор id источника, т.к. на него нельзя будет сослаться.
<form> <datasource> <!-- Источник данных виджета --> </datasource></form>note
В качестве вложенного источника может использоваться только стандартный источник данных.
note
Если у виджета никак не задан источник данных, то он создастся автоматически.
Передача источника на открываемую страницу#
Источники данных можно передать на открываемую страницу:
<button label="Создать"> <open-page page-id="personCard"> <datasources> ... <!-- Источники данных, которые будут переданы на страницу personCard --> </datasources> </open-page></button>Или в модальное окно, и любые другие виды окон:
<button label="Создать"> <show-modal page-id="personCard"> <datasources> ... <!-- Источники данных, которые будут переданы на страницу personCard --> </datasources> </show-modal></button>В случае, если id пробрасываемых источников не пересекаются с источниками открываемой страницы,
то они просто дополнят список источников открываемой страницы.
Однако наибольший интерес представляет случай, когда совпадения все-таки есть. Тогда пробрасываемые источники заменят собой указанные на странице источники. В связи с этим возникает возможность открытия страницы из разных мест с разными данными
Представим, что открываемая страница имеет следующий вид:
<page xmlns="http://n2oapp.net/framework/config/schema/page-4.0"> <datasources> <datasource id="docs"/> </datasources>
<form datasource="docs"> <fields> <input-text id="name" label="Наименование"/> <input-text id="description" label="Описание"/> </fields> </form></page>Теперь откроем эту страницу сначала на создание (поля не будут заполнены):
<button label="Создать"> <show-modal page-id="docPage" page-name="Создание документа"> <datasources> <datasource id="docs" default-values-mode="defaults"/> </datasources> </show-modal></button>А после - на редактирование (поля заполнены значениями определенной записи):
<button label="Изменить"> <show-modal page-id="docPage" page-name="Изменение документа"> <datasources> <datasource id="docs" query-id="documents"> <filters> <eq filter-id="id" value={id}/> </filters> <datasource/> </datasources> </show-modal></button>note
Для передачи источника данных на страницу simple-page можно не задавать id.
Он будет сливаться с единственным источником данных, который есть на странице.
note
В пробрасываемых источниках могут присутствовать ссылки на другие источники данных (например source-datasource в inherited-datasource).
В таком случае считается, что эти источники заданы на открываемой странице.
Если же вы хотели сослаться на источник родительской страницы, то укажите на открываемой странице parent-datasource.
Источники данных в приложении#
Источники данных, заданные в приложении могут выполнять сразу несколько функций: заполнение данными боковых панелей, а также определение глобального для всех страниц источника данных.
Первая функция будет описана далее, а для второй существует специальный вид источника данных.
Для задания источников данных в приложении используется элемент datasources.
<application xmlns="http://n2oapp.net/framework/config/schema/application-3.0"> <datasources> <datasource id="appDs"/> ... <!-- Источники данных в приложении --> </datasources></application>На заданные таким образом источники можно ссылаться из боковых панелей <sidebar> с помощью атрибута datasource.
<sidebar datasource="appDs"> ...</sidebar>Источник данных в боковой панели <sidebar> позволяет отображать динамические данные в заголовках или ссылках навигационного меню.
note
Из разных боковых панелей можно ссылаться на один и тот же источник данных. В этом случае они все будут оперировать одними и теми же данными.
Вложенный источник данных в боковой панели#
Источник данных можно создать внутри боковой панели, если данные нужны только этой боковой панели.
В этом случае не нужно задавать идентификатор id источника, т.к. на него нельзя будет сослаться.
<sidebar> <datasource> <!-- Источник данных боковой панели --> </datasource></sidebar>note
В качестве вложенного источника может использоваться только стандартный источник данных.
note
Если у боковой панели не задан источник данных, то он создастся автоматически.
Виды источников данных#
Стандартный источник данных#
В стандартном источнике данных можно задать объект и выборку, чтобы загружать и сохранять данные через провайдеры.
<datasource id="main" object-id="person" query-id="person"> ...</datasource>Фильтрация источника данных#
Выборку можно отфильтровать через элемент <filters>.
<datasource id="main" query-id="person"> <filters> <eq field-id="id" value="123"/> ... <!-- Другие фильтры выборки --> </filters></datasource>Подробнее о фильтрации выборок
Отправка данных формы#
Данные формы можно сохранить через стандартный источник данных с помощью элемента <submit>.
<datasource id="main" object-id="person"> <submit operation-id="save"/></datasource>Атрибутом operation-id задается ссылка на операцию объекта, которая вызовется при отправке данных.
Отправка данных формы может быть вызвана по кнопке.
<button label="Сохранить"> <submit datasource="main"/></button>Можно отправлять данные формы автоматически при каждом изменении полей формы.
<datasource id="main" object-id="person"> <submit auto="true" operation-id="save"/></datasource>Это задается с помощью атрибута auto. По умолчанию выключено.
Валидация источника данных#
Для источника данных можно вызвать валидации. Валидация вызывается по мере ввода в полях формы и при отправке данных по кнопке.
<button label="Сохранить" validate="true" validate-datasource="main, docs, addresses"> ... <!-- Действие --></button>С помощью атрибута validate-datasources можно указать источники данных, которые требуется провалидировать перед вызовом действия.
Значения по умолчанию в источниках данных#
Значения по умолчанию задаются в полях формы через атрибут default-value.
<input-text id="firstName" default-value="Joe"/>Но также можно комбинировать значения по умолчанию и данные, полученные через выборку.
Для этого необходимо настроить правила слияния с помощью атрибута default-values-mode.
<datasource id="main" query-id="person" default-values-mode="merge"> ...</datasource>Правила слияний
| Правило | Описание |
|---|---|
| merge | Значения по умолчанию заполняются путем слияния данных, прописанных в полях и полученных из запроса (полученные из запроса в приоритете). |
| query | Значения по умолчанию заполняются данными из запроса. Значения по умолчанию игнорируются. |
| defaults | Значения по умолчанию заполняются значениями по умолчанию. Выборка не вызывается. |
Подробнее о значениях по умолчанию
Подробнее о стандартном источнике данных
Браузерное хранилище#
Элемент <browser-storage> позволяет получать и сохранять данные в localStorage
или sessionStorage браузера.
Удобство данного хранилища заключается в том, что при закрытии вкладки или перезагрузке, данные не будут потеряны.
<datasources> <browser-storage id="main" key="n2o.storage.main" type="sessionStorage"> ... </browser-storage></datasources>Атрибут key задает пространство в браузерном хранилище, в котором будут сохраняться данные.
Сохранение данных в браузерное хранилище#
Данные формы можно сохранить в браузерное хранилище с помощью элемента <submit>.
<browser-storage id="main" key="n2o.storage.main" type="sessionStorage"> <submit auto="true" model="resolve"/></browser-storage>Атрибут model в элементе <submit> определяет модель данных, которая будет сохраняться в хранилище браузера.
Подробнее о браузерном хранилище
Наследуемый источник данных#
Источники данных могут получать данные путем копирования из других источников.
Такие источники называются наследуемыми и задаются элементом <inherited-datasource>.
<datasources> <inherited-datasource id="docs" source-datasource="person" source-model="resolve" source-field-id="docs"> ... </inherited-datasource></datasources>Атрибуты source-* задают ссылку на родительский источник данных.
С помощью наследуемых источников данных можно получать данные для формы и таблицы одним запросом выборки.
<datasources> <datasource id="person" query-id="person" size="1"/>
<inherited-datasource id="docs" source-datasource="person" source-model="resolve" source-field-id="docs"/></datasources>note
Наследуемый источник копирует данные из родительского источника в тот момент, когда виджет запрашивает получение данных.
Можно заставить виджет принудительно скопировать данные через действие <refresh>:
<button label="Обновить"> <refresh datasource="docs"/></button>Либо использовать зависимость обновления данных:
<datasources> <datasource id="person" query-id="person" size="1"/>
<inherited-datasource id="docs" source-datasource="person" source-model="resolve" source-field-id="docs"> <dependencies> <fetch on="ds1"/> </dependencies> </inherited-datasource></datasources>Подробнее о наследуемом источнике данных
Stomp источник данных#
Stomp источник данных получает данные с помощью STOMP протокола и
задается элементом <stomp-datasource>.
<datasources> <stomp-datasource id="notifCount" destination="/notif"> ... </stomp-datasource></datasources>Атрибут destination определяет очередь сообщений, на которую подписывается источник данных.
note
Наиболее частым случаем применения Stomp источника данных является асинхронное получение счетчиков.
<application xmlns="http://n2oapp.net/framework/config/schema/application-3.0"> <datasources> <!-- клиент будет прослушивать данные, полученные по указанному destination --> <stomp-datasource id="notifCount" destination="/notif"> <values> <!-- значение счетчика на момент инициализации --> <value count=""/> <!-- цвет значка на момент инициализации --> <value color="success"/> </values> </stomp-datasource> </datasources> ...</application>С помощью <values> задаются значения при старте приложения, когда данные из STOMP еще не были получены.
Использовать Stomp источник данных можно в меню навигации.
<application> <header title="Хедер"> <nav> <!-- элемент меню, в котором отобразится обновленное значение счетчика и изменится цвет значка--> <!-- атрибут должен ссылаться на имя поля, используемого в stomp-datasource (в данном случае count и color) --> <menu-item id="notif" icon="fa fa-bell" datasource="notifCount" badge="{count}" badge-color="{color}"> ... </menu-item> </nav> </header></application>Подробнее о stomp источниках данных
Источник данных приложения на странице#
На источник данных, заданный в структуре приложения, можно сослаться из виджетов страницы.
Для этого нужно на странице определить специальный источник данных <app-datasource>.
<page> <datasources> <app-datasource id="appDs"/> <!-- Ссылка на источник данных в приложении --> </datasources>
<regions> <form datasource="appDs"/> <!-- Ссылка на app-datasource --> </regions></page>Где id - это ссылка на идентификатор источника в приложении.
note
В этом случае один и тот же источник данных можно будет использовать на разных страницах.
note
Элемент app-datasource нельзя использовать в application.xml.
Подробнее об источниках данных приложения на странице
Источник данных родительской страницы#
На источник данных, заданный в родительской странице, можно сослаться из модального окна и любого другого вида окон.
Для этого нужно на странице определить специальный источник данных <parent-datasource>.
<page> <datasources> <parent-datasource id="docs"/> <!-- Ссылка на источник данных родительской страницы --> </datasources>
<regions> <form datasource="docs"/> <!-- Ссылка на parent-datasource --> </regions></page>Где id - это ссылка на идентификатор источника родительской страницы.
note
В случае, если понадобится с N-ой страницы сослаться на источник данных первой страницы,
то необходимо последовательно указать parent-datasource, начиная со 2-ой страницы и далее.
note
Элемент parent-datasource нельзя использовать в application.xml.
Подробнее об источниках данных родительской страницы
Зависимости источников данных#
В источнике данных можно добавить зависимости на изменения других источников данных.
Зависимости задаются в элементе <dependencies>.
<datasource> <dependencies> ... <!-- Зависимости источника данных --> </dependencies></datasource>Зависимость обновления данных#
Если требуется обновить текущий источник данных при изменении в другом источнике, нужно добавить зависимость <fetch>.
<datasources> <datasource id="main"/>
<datasource id="docs" query-id="docs"> <dependencies> <!-- При изменении resolve модели источника main будет выполнен запрос выборки docs --> <fetch on="main" model="resolve"/> </dependencies> </datasource></datasources>Зависимость копирования данных#
Если требуется скопировать данные из другого источника, нужно добавить зависимость copy.
<datasources> <datasource id="docs" query-id="docs"/>
<datasource id="card"> <dependencies> <!-- При изменении resolve модели источника main будут скопированы данные поля number в поле phone --> <copy on="main" source-model="resolve" source-field-id="number" target-model="resolve" target-field-id="phone"/> </dependencies> </datasource></datasources>note
Если не указывать target-field-id или source-field-id, то будет копироваться вся модель.
Подробнее о зависимостях источников данных
Модели данных#
Источник данных загружает данные на клиент в формате json и перемещает их в Redux хранилище с ключем models.[model].[page_datasource],
где
page- адрес страницы,datasource- идентификатор источника данных страницы,model- модель данных.
У источника данных может быть несколько моделей:
Модели данных
| Модель | Описание | Пример |
|---|---|---|
| datasource | Все загруженные записи | Список записей у таблицы |
| resolve | Текущая запись | Выделенная запись таблицы |
| filter | Значения фильтров | Значения фильтров таблицы, заданные пользователем |
| multi | Все выделенные записи | Помеченные чекбоксы в таблице |
| edit | Не сохраненные данные | Форма, открытая на редактирование, с изменёнными полями |
На модель данных можно ссылаться, например, в зависимостях или в фильтрах:
<datasource id="docs" query-id="docs"> <filters> <!-- Фильтр со значением, взятым из источника main с моделью resolve --> <eq field-id="person.id" value="{id}" datasource="main" model="resolve"/> </filters></datasource>На модель виджета так же ссылаются в действиях, чтобы задать область данных, над которой происходит действие.
<button> <!-- Вызов операции с данными из источника docs с моделью resolve --> <invoke operation-id="delete" datasource="docs" model="resolve"/></button>