3.2.3. Описание полей таблицы

Data Source Eng Data Source

Обычно каждый 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) - используются при проверки соответствия значения в поле с наложенными ограничениями на значение в поле;
форматера - используются указанным форматером.

Обязательные опции

название опции

описание опции

type (string)

Указывает тип значения, которое будет храниться в поле. Для всех численных типов автоматически проверяется, что значение в поле является числом. Если в таком поле будет не число, а например, строка, то на этапе проверки соответствия (validation) в этом поле будет ошибка. Доступны следующие значения этой опции:

int - целое число (напр. 543);
float - число с плавающей точностью (напр. 14.66);
string - строка (напр. „проверка“).

Устаревшие типы (не использовать):

integer - синоним int;
double - синоним float;
real - синоним float;
numeric - синоним float.

default (mixed)

Значение по умолчанию в этом поле. Должно совпадать со значением по умолчанию у этого поля в базе данных. Если физически не возможно (ограничения в базе данных) синхронизировать значение по умолчанию в базе данных и в опциях поля, то этого делать не надо. Например, при использовании kDateFormatter можно ставить '#NOW#' в качестве значения по умолчанию, но поле с датой числовое (т.к. в нём находиться timestamp) и такое значение в базу данных не записать.

Необязательные опции

название опции	описание опции
not_null (int)	Если поле в базе данных настроено, как `NOT NULL`, то надо указывать данную опцию.
totals (string)	Название агрегатной функции базы данных (напр. `AVG`, `SUM`, `COUNT` и т. п.), которая будет использоваться для подсчёта `total` значения по колонке, в которой будет выводиться это поле.

Опции проверки соответствия

название опции	описание опции
error_field (string)	Название поля, в которое должны писаться ошибки проверок вместо этого поля. Бывает полезно, когда ошибки от нескольких виртуальных полей должны показываться у одного реально поля.
error_msgs (array)	См. Сообщения об ошибках.
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». Ниже приведена таблица, в которой описаны все стандартные ошибки:

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)

Название класса накладываемого форматера. Вот самые ходовые классы:

kFormatter - для обработки чисел, денежных сумм, почтовых адресов
kOptionsFormatter - для работы с элементами ограниченного выбора (dropdown, radio buttons и т.п.)
kDateFormatter - для обработки дат
kUploadFormatter - для загрузки файлов на сервер

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

Автоматическое построение структуры

Добавлено в версии 4.1.0.

В 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).