Валидация моделей

Описаны основные шаги по настройке валидации в приложении

Описание

Клиентская валидация настраивается в приложении с использовнием аддона ember-cp-validations (в документации к данному аддону можно более подробно познакомиться со всеми его возможностями).

По умолчанию валидация задаётся на уровне модели в объекте ValidationRules, при этом определеный набор валидаторов генерируется в автогенерируемый миксин модели на основании заданных настроек на уровне модели предметной области во Flexberry Designer.

Типы валидаторов

Аддон ember-cp-validations предоставляет следующие валидаторы (более подробную информацию можно посмотреть в документации аддона):

alias - связывает текущий атрибут с каким-нибудь другим в качестве псевдонима, позволяет получить все его сообщения валидации и ошибки.
belongs-to - позволяет указать, что атрибут является belongs-to связью, и позволяет получить все сообщения валидации связанной модели.
collection - проверяет, что значение атрибута является массивом (или не является, в зависимости от параметров валидатора).
confirmation - позволяет проверить, что значение атрибута совпадает со значением другого указанного в параметрах атрибута.
date - проверяет, что значение атрибута является датой, также содержит дополнительные проверки в зависимости от переданных параметров.
dependent - позволяет указать, что атрибут будет являться валидным, если валидными являются другие связанные атрибуты.
ds-error - позволяет получить ошибки из DS.Errors аддона ember-data.
exclusion - проверяет, что значение атрибута не содержится в заданном списке.
format - проверяет значение атрибута на соответствие регулярному выражению.
has-many - позволяет указать, что атрибут является has-many связью, и позволяет получить все сообщения валидации связанных моделей.
inclusion - проверяет, что значение атрибута содержится в заданном списке.
length - проверяет длину значения атрибута на равенство числу, либо на вхождение в интервал.
number - проверяет, что значение атрибута является числом, также содержит дополнительные проверки в зависимости от переданных параметров.
presence - проверяет, что значение атрибута не явяется пустым (но можно проверить и то, что значение - пустое).

Генерируемые валидаторы

Валидаторы, которые создаются автоматически при генерации приложения из Flexberry Designer, находятся в автогенерируемом миксине модели (mixins/regenerated/models):

export let ValidationRules = {
  propName: {
    descriptionKey: 'localization_path',
    validators: [
      validator('presence', true),
      validator('length', { is: 15 }),
      ...
    ],
  },
  ...
};

Где propName - имя валидируемого свойста, localization_path - путь в locales до сообщения валидатора.

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

validator('presence', true) - проверка того, что значение свойства не пустое.
validator('length', { is: 15 }) - проверка того, что длина значения свойства равна 15.

Автоматически из Flexberry Designer генрируются следующие валидаторы:

Для всех типов полей: validator('ds-error') и validator('presence', true) (если для соответствующего атрибута на уровне модели предметной области во Flexberry Designer указано, что он не может иметь пустое значение).
Для полей с типом дата: validator('date').
Для числовых типов: validator('number', { allowString: true, allowBlank: true, integer: true }). Значения параметров зависят от свойств атрибута в модели Flexberry Designer: allowString - может ли число быть задано в виде строки; allowBlank - может ли значение быть пустым; integer - если true, то допускаются только целые числа.
Для hasMany связи: validator('has-many').

Дополнительные валидаторы

Для добавления собственных правил валидации, которые не генерируются автоматически из Flexberry Designer, нужно в модели (в папке models) добавить их в объект ValidationRules. Все собственные валидаторы нужно добавлять до строки с определением const Validations = buildValidations(...).

Например:

ValidationRules.name = {
  descriptionKey: 'models.testModel.validations.name.__caption__',
  validators: [
    validator('length', { min: 5 })
  ],
};

В этом примере для поля name добавляется валидатор для проверки минимальной длины строки - не менее 5 символов. В descriptionKey при этом указывается путь в locales до сообщения валидатора.

Компоненты для валидации

Для отображения сообщений валидации в аддоне ember-flexberry есть два компонента - flexberry-validationmessage и flexberry-validationsummary.

Компонент flexberry-validationmessage

Компонент flexberry-validationmessage предназначен для отображения сообщений валидации у определенного свойства модели. В шаблоне роута этот компонент объявляется следующим образом:

{{flexberry-validationmessage error=(v-get validationObject "propertyName" "messages")}}

Где validationObject - валидируемая модель, propertyName - имя свойства модели, сообщения валидаторов которого отображаются в данном компоненте. messages - имя свойства с сообщениями валидации (по умолчанию все сообщения хранятся в свойстве messages, также в message можно получить наиболее приоритетное сообщение, тогда будет отображаться только 1 сообщение валидации, которое будет меняться по мере выполнения условий валидаторов). v-get - хелпер из аддона валидации, который позволяет получить значение указанного свойства некоторого объекта (в документации аддона ember-cp-validations, ссылка на которую указана выше, можно найти о нем дополнительную информацию).

Note: Важно! Имя свойства не должно быть многоуровневым, т.е. если нужно отображать валидацию для поля мастера, то нельзя использовать в качестве имени свойства “master.propertyName”, в этом случае необходимо в качестве модели брать именно модель мастера:

{{flexberry-validationmessage error=(v-get validationObject.master "propertyName" "messages")}}

Компонент flexberry-validationsummary

Компонент flexberry-validationsummary предназначен для отображения списка сообщений валидации. По умолчанию он используется на формах редактирования для отображения всех сообщений валидации редактируемой модели. Например:

{{flexberry-validationsummary errors=(v-get validationObject "messages")}}

Валидация на формах редактирования

Для валидации на формах редактирования используются описанные выше компоненты, которые генерируются автоматически в шаблонах форм редактирования:

flexberry-validationmessage в шаблоне формы располагается после каждого компонента для редактирования атрибута модели.
flexberry-validationsummary - по умолчанию в шаблоне формы располагается перед всеми полями на форме (компонентами для редактирования атрибутов модели).

Компоненты для редактирования атрибутов модели из аддона ember-flexberry меняют свой цвет, если валидация соответствующего атрибута модели не является успешной (по умолчанию используется красный цвет). Для этого компоненту при ошибках валидации устанавливается класс error. Например:

{{flexberry-field
    ...
    class=(if (v-get validationObject "propertyName" "isInvalid") "error")
}}

Где validationObject - валидируемая модель, propertyName - имя свойства, а isInvalid - флаг, определяющий, что хотя бы один валидатор у данного свойства не выполнился успешно.

Кастомные валидаторы

Аддон ember-cp-validations позволяет создавать собственные валидаторы. Для этого необходимо в консоли в папке с приложением выполнить команду ember g validator validator-name, где validator-name - имя создаваемого валидатора.

Данная команда генерирует файл app/validators/validator-name.js, а также тест для него. В сгенерированном валидаторе необходимо доработать логику валидации в методе validate - он должен возвращать либо true, если валидатор выполняется успешно, либо сообщение валидации в виде строки. Также можно возвращать Promise, который разрешается в true, или в сообщение валидации.

Более подробную информации о кастомных валидаторах можно получить в документации аддона.