K4:Defining Database, Virtual and Calculated Fields
From In-Portal Developers Guide
| ||
---|---|---|
Статьи в этой категории | ||
|
Обычно каждый unit config создаётся для взаимодействия с одной таблицей в базе данных. Для этого в нём необходимо объявить каждое поле из связанной таблицы в базе данных. Для этого существует опция Fields
. Эта опция является ассоциативным массивом (почти все опции в unit config это ассоциативные массивы) , в котором ключи это названия полей в таблице, а значения это опции этих полей. Это массив может быть например таким:
'Fields' => Array ( 'ProductId' => Array('type' => 'int', 'not_null' => 1, 'default' => 0), 'Name' => Array ('type' => 'string', 'formatter' => 'kMultiLanguage', 'required' => 1, 'max_len' => 255, 'default' => ''), 'Description' => Array ('type' => 'string', 'formatter' => 'kMultiLanguage', 'default' => NULL), ),
Из приведённого примера несложно заметить, что ProductId
, Name
и Description
это поля, а содержание остальных массивов это набор опций этих полей. Опции поля делятся на 3 группы:
- обязательные - должны всегда присутствовать;
- проверки соответствия (validation) - используются при проверки соответствия значения в поле с наложенными ограничениями на значение в поле;
- форматера - используются указанным форматером.
Contents |
Обязательные опции
название опции | описание опции |
---|---|
type (string) | Указывает тип значения, которое будет храниться в поле. Для всех численных типов автоматически проверяется, что значение в поле является числом. Если в таком поле будет не число, а например, строка, то на этапе проверки соответствия (validation) в этом поле будет ошибка. Доступны следующие значения этой опции:
|
default (mixed) | Значение по умолчанию в этом поле. Должно совпадать со значением по умолчанию у этого поля в базе данных. Если физически не возможно (ограничения в базе данных) синхронизировать значение по умолчанию в базе данных и в опциях поля, то этого делать не надо. Например, при использовании kDateFormatter можно ставить '#NOW#' в качестве значения по умолчанию, но поле с датой числовое (т.к. в нём находиться timestamp) и такое значение в базу данных не записать.
|
Необязательные опции
название опции | описание опции |
---|---|
not_null (int) | Если поле в базе данных настроено, как "NOT NULL ", то надо указывать данную опцию.
|
Опции проверки соответствия
название опции | описание опции |
---|---|
error_field (string) | Название поля, в которое должны писаться ошибки проверок вместо этого поля. Бывает полезно, когда ошибки от нескольких виртуальных полей должны показываться у одного реально поля. |
max_value_inc (int, float) | Максимальное значение (включая это значение), которое может быть в этом поле. Только для числовых полей. |
min_value_inc (int, float) | Минимальное значение (включая это значение), которое может быть в этом поле. Только для числовых полей. |
max_value_exc (int, float) | Максимальное значение (не включая это значение), которое может быть в этом поле. Только для числовых полей. |
min_value_exc (int, float) | Минимальное значение (не включая это значение), которое может быть в этом поле. Только для числовых полей. |
max_len (int) | Максимальная длинна строки, которая может быть в этом поле. Только для строковых полей. |
min_len (int) | Минимальная длинна строки, которая может быть в этом поле. Только для строковых полей. |
unique (array) | Осуществлять проверку на уникальность значения поля в таблице. Если надо проверить уникальность в сочетании со значениями из других полей, то их надо перечислить в виде массива. Если этого делать не надо (т.е. проверяем это поле само по себе), то надо указать пустой массив. Не надо перечислять в массиве поле, у которого указанна данная опция. |
current_table_only (boolean) | Проверять уникальность значения в поле только из текущей таблицы (live или временной). По умолчанию проверяется из live таблицы и из временной (если доступна). |
required (int, boolean) | Поле обязательно к заполнению. Если значение не указано, то в поле будет ошибка. Несмотря на ошибочное мнение ноль, в качестве значения поля не вызывает ошибку о том, что в поле не указано значение. Но если 0, указанный в качестве значения, должен вызывать ошибку можно дополнительно указать опции ограничения интервала значения, напр. 'min_value_exc' => 0 .
|
Все выше описанные опции можно объединить в группы по смыслу:
- интервалы (
max_value_inc
,min_value_inc
,max_value_exc
,min_value_exc
) - опции, использующиеся для проверки принадлежности значения поля указанному интервалу (range); - длинна (
max_len
,min_len
) - опции, использующиеся для проверки длинны строки (length).
Если та, или иная опция не нужна, то можно просто убрать её определение из массива опций поля. В таком случае не надо будет ставить её значение в 0 или false .
|
Сообщения об ошибках
У каждого поля можно указать альтернативные тексты для всех ошибок используя опцию error_msgs
(array). Ниже приведена таблица, в которой описаны все стандартные ошибки:
pseudo | описание | значение по умолчанию | управляется опциями |
---|---|---|---|
required | Значение в поле не заполнено. | !la_err_required! | required |
unique | Значение в поле не уникально. | !la_err_unique! | unique |
value_out_of_range | Значение в поле не находиться в разрешённом интервале значений | !la_err_value_out_of_range! | max_value_inc, min_value_inc, max_value_exc, min_value_exc |
length_out_of_range | Длинна строки превышена. | !la_err_length_out_of_range! | max_len, min_len |
bad_type | Тип значения в поле не соответствует описанию поля (напр. ввели букву вместо числа). | !la_err_bad_type! | type |
invalid_format | Формат строки не соответствует требуемому. | !la_err_invalid_format! | regexp |
bad_date_format | Формат введённой даты не соответствует требуемому. | !la_err_bad_date_format! | опции kDateFormatter |
primary_lang_required | Значение в поле на первичном (primary) языке не заполнено. | !la_err_primary_lang_required! | required, опции kMultiLanguage |
bad_file_format | Попытка загрузить файл, у которого миме-тип (mime-type ) не находиться в списке разрешённых. | !la_error_InvalidFileFormat! | allowed_types, опции kUploadFormatter |
bad_file_size | Попытка загрузить файла, размер которого превышает разрешённый. | !la_error_FileTooLarge! | max_size, опции kUploadFormatter |
cant_save_file | Загруженный на сервер файл неудалось сохранить в требуемую директорию. | !la_error_cant_save_file! | upload_dir, опции kUploadFormatter |
Эта опция задаётся в виде ассоциативного одномерного массива, в ключах которого указаны "pseudo
" ошибок (см. приведённую выше таблицу), а в значениях соответствующие им тексты ошибок:
'error_msgs' => Array ( 'required' => '!la_error_CustomRequiredError!' )
Если требуется чтобы перевод фразы стал текстом сообщения об ошибке, то нужно заключить её название в восклицательные знаки:
- "
!la_error_ErrorPhrase!
" - фраза (её перевод на текущем языке это текст ошибка); - "
Error Message
" - текст (будет один для всех языков).
Опции форматера
Все оставшиеся опции обрабатываются указанным форматером. Вот, к примеру некоторые из них:
название опции | описание опции |
---|---|
formatter (string) | Название класса накладываемого форматера. Вот самые ходовые классы:
Подробнее о том, какие есть форматеры и как их использовать можно прочесть в этой статье. |
Автоматическое построение структуры
В K4 есть механизм, который автоматически выстраивает массив для опции Fields. Чтобы воспользоваться им следуйте приведённым шагам:
- пойти в секцию "Configuration -> System Tools" (в Platform) или "Tools -> System Tools" (в In-Portal);
- в поле "Table Structure" вписать имя таблицы (можно без TABLE_PREFIX) или префикс от unit config;
- нажать на кнопку "Go";
- откроется новое окно со структурой введённой таблицы:
При добавлении новых полей в таблицу нужно повторить все выше описанные шаги, но из результата скопировать описание только нужных полей, а не всех как обычно. Не надо писать всё руками. |
При построении структуры полям автоматически прописываются (если удаётся определить) следующие опции:
-
type
- php тип значения, которое будет храниться в поле; -
not_null
- NULL или NOT NULL пометка; -
default
- значение по умолчанию; -
formatter
- класс форматера, пока только для дробный полей (float, double, decimal); -
max_len
- ограничение по длине значения в поле, только для строковых полей (varchar).
Функциональность доступна начиная с Core v 4.1.0.