Файлы конфигураций

В N2O Framework разработка WEB страниц и их связей с данными осуществляется при помощи N2O файлов конфигураций.

Расположение

Файлы конфигураций располагаются в папке проекта или в папке модуля. По умолчанию /src/main/resources/META-INF/conf.

Любой файл из этой папки может быть переопределен одноименным файлом в папке расширений. Путь к папке расширений задаётся настройкой n2o.config.path. По умолчанию: [USER_HOME]/.n2o/conf.

Формат файлов

Конфигурации N2O имеют определенный формат имени файла:

[id].[type].[ext]

• id - Уникальный идентификатор метаданной в рамках типа
• type - Тип конфигурации
• ext - Способ задания метаданной (.xml)

Типы конфигураций

Конфигурации N2O иерархически структурированы по типу. Все типы конфигураций наследуются от java интерфейса SourceMetadata.

Типы конфигураций

Тип	Описание	XML Схема	Java класс
page	Страница	http://n2oapp.net/framework/config/schema/page-4.0	N2oPage
widget	Виджет	http://n2oapp.net/framework/config/schema/widget-5.0	N2oWidget
object	Объект	http://n2oapp.net/framework/config/schema/object-4.0	N2oObject
query	Выборка	http://n2oapp.net/framework/config/schema/query-5.0	N2oQuery
fieldset	Филдсет	http://n2oapp.net/framework/config/schema/fieldset-5.0	N2oFieldSet
application	Структура приложения	http://n2oapp.net/framework/config/schema/application-3.0	N2oApplication
menu	Меню	http://n2oapp.net/framework/config/schema/menu-3.0	N2oSimpleMenu
access	Схема доступа	http://n2oapp.net/framework/config/schema/access-2.0	N2oAccessSchema

Структура XML файла

В теле XML файла первой строчкой должен идти заголовок xml:

<?xml version='1.0' encoding='UTF-8'?>

Далее корневой элемент метаданной и XML схема, определяющая её структуру:

<?xml version='1.0' encoding='UTF-8'?>
<object xmlns="http://n2oapp.net/framework/config/schema/object-4.0">
    ...
</object>

note

В наименовании схемы содержится её версия. Это позволяет схемам эволюционировать с полным сохранением обратной совместимости.

Ссылки на другие файлы

Конфигурации могут иметь ссылки друг на друга. Для ссылки используются элементы или атрибуты XML с окончанием: -id. В качестве значения ссылки используется идентификатор файла:

<query object-id="myObject">
  ...
</query>

Библиотеки компонентов

Внутри некоторых XML элементов разрешается вставлять элементы из другой схемы:

<set xmlns="http://n2oapp.net/framework/config/schema/fieldset-5.0"
     xmlns:ctrl="http://n2oapp.net/framework/config/schema/control-3.0">
    <ctrl:input-text>...</ctrl:input-text>
</set>

Такие места называются местами подключения библиотек компонентов.

note

В схеме элемента, допускающего библиотеки расширения, должен стоять элемент: <xs:any namespace="##other"/>

Вложенные конфигурации

Внутри некоторых XML элементов используются вложенные элементы другого типа.

Например, страница <simple-page> с таблицей <table> внутри.

<simple-page>
    <!-- Вложенный виджет -->
    <table>
        <!-- Элементы вложенного виджета -->
        <columns>...</columns>
        ...
    </table>
</simple-page>

Можно сослаться на внешний файл используя атрибут ref-id:

<simple-page>
    <table ref-id="myTable"/><!-- Ссылка на внешний виджет -->
</simple-page>

Переопределение свойств

Во вложенных конфигурациях можно переопределить некоторые свойства заданные по ссылке:

<simple-page>
    <table ref-id="myTable"
           name="Моя таблица">
        <!-- свойство name, заданное здесь, переопределит name, заданный в myTable -->
    </table>
</simple-page>

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

В N2O XML файлы можно добавить свойства, специфичные для прикладного проекта. Для этого нужно создать XSD схему расширений, подключить её к XML файлу и вставить атрибуты в те элементы, которые допускают расширения:

Схема расширений

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://myproject.net/config/schema/ext-props-1.0"
           xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:attribute name="prop1" type="xs:string"/>
    <xs:attribute name="prop2" type="xs:string"/>
</xs:schema>

Подключение схемы расширений

<?xml version='1.0' encoding='UTF-8'?>
<page xmlns="http://n2oapp.net/framework/config/schema/page-4.0"
      xmlns:ext="http://myproject.net/config/schema/ext-props-1.0"
      ext:prop1="value1"
      ext:prop2="value2">
    ...
</page>

note

В схеме элемента, допускающего расширения, должен стоять атрибут: <xs:anyAttribute/>

Расширенные свойства считываются автоматически в свойство properties. К ним можно получить доступ из трансформации метаданных или процессинга данных.

note

XSD схему создавать не обязательно, расширенные свойства все равно считаются в свойство properties. Без XSD схемы не будет подсказок и проверки свойств в xml.

Пример без создания схемы расширений

<form xmlns="http://n2oapp.net/framework/config/schema/widget-5.0"
      xmlns:ext="http://example.com/n2o/ext-2.0">
    <fields>
        <field id="testId" src="src"
               ext:attr="attr1"
               ext:new-attr="attr1">
               ...
        </field>
    </fields>
</form>

Плейсхолдеры

Плейсхолдеры - это ссылки в метаданных на какие-либо значения, которые должны быть разрешены на различных этапах жизненного цикла приложения.

Ссылки на настройки

В любых значениях атрибутов и элементов XML можно использовать плейсхолдер ${property}, где property - это ссылка на настройки и локализацию.

Ссылки на контекст

В некоторых атрибутах и элементах (как правило в value и default-value) допускается использование плейсхолдера #{context}, где context - это название свойства в контексте пользователя.

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

Во многих свойствах визуальных компонентов (таких как поля, ячейки, филдсеты), а так же в атрибутах value в фильтрах, можно использовать ссылки на данные заданные через плейсхолдер {expression}, где expression - ссылка на поле в текущей модели данных, либо JavaScript выражение.

note

Ссылка на конкретную модель данных задается в паре с дополнительными атрибутами datasource и model.

Экранирование строк

В некоторых случаях N2O приходится автоматически приводить значения к типу. Например, в элементах option:

<option id="1" name="true"/>
<!-- id будет приведен к числовому типу,
     name будет приведет к булевому типу -->

Иногда требуется избежать автоматического приведения к типу и оставить значение строкой. Для этого можно использовать плейсхолдер "одинарная кавычка" 'string'.

note

Для экранирования одинарной кавычки нужно вставить перед ней еще одну одинарную кавычку "''123''".

Валидация конфигураций

Все файлы конфигураций проверяются на корректность связей и логики. Проверка инициируется в runtime при первой загрузке файла в приложение.

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

За валидацию отвечают java классы реализующие интерфейс SourceValidator<T>.

Валидация страницы

@Component
class MyPageValidator implements SourceValidator<N2oPage> {
    /**
     * Валидировать исходную метаданную
     * @param source Исходная метаданная
     * @throws N2oMetadataValidationException Иключение при ошибке валидации
     */
    @Override
    public void validate(N2oPage source,
                         ValidateProcessor p) {
        ... //проверки валидности
    }
}