In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Defining Database, Virtual and Calculated Fields

From In-Portal Developers Guide

Jump to: navigation, search
Unit Configs Unit Configs
Статьи в этой категории

Usually, each unit config is created to interact with one database table. For this, each field from the database table must be declared in the unit config. The Fields option exists for this purpose. This option is an associative array (almost all options in a unit config are associative arrays), in which the keys are the names of the table fields and the values are the options of these fields. This array can, for example, look like this:

'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),
),

From the above example it's not difficult to see that ProductId, Name and Description are fields, and the contents of the arrays are the sets of options for these fields. Fields options are divided into 3 groups:

  • required - must always be there;
  • validation - used to validate field values against the restrictions on the field values;
  • formatter - used by the indicated formatter.

Contents

Required Options

Option Name Option Description
type (string) Indicates the type of value that's going to be stored in the field. For all numerical types, it's automatically checked that the field value is a number. If this field has something else, for example a String, then at the validation stage this field will contain an error. The following values are available for this option:
  • int - whole number (e.g. 543);
  • float - floating point number (e.g. 14.66);
  • string - line of text (e.g. 'validate').


Deprecated Types (Don't Use):

  • integer - synonym int;
  • double - synonym float;
  • real - synonym float;
  • numeric - synonym float.
default (mixed) Default field value. Must correspond to the default value of this field in the database. If it's physically impossible (database restriction) to synchronize default values in options and in the database field, then this doesn't have to be done. For example, when using kDateFormatter it's allowed to put '#NOW#' as the default value, but the database field with the date is numeric (since it's a timestamp) and such a value can't be stored in the database.

Not Required Options

Option Name Option Description
not_null (int) If the field in the database is setup as "NOT NULL", then this option needs to be set.

Validation Options

Option Name Option Description
error_field (string) Name of the field which stores validation error messages in place of this field. It's useful when errors from several virtual fields need to show in one real field.
max_value_inc (int, float) Maximum value (inclusive) that can be in this field. Only for numeric fields.
min_value_inc (int, float) Minimum value (inclusive) that can be in this field. Only for numeric fields.
max_value_exc (int, float) Minimum value (exclusive) that can be in this field. Only for numeric fields.
min_value_exc (int, float) Minimum value (exclusive) that can be in this field. Only for numeric fields.
max_len (int) Maximum String length that can be in this field. Only for String fields.
min_len (int) Minimum String length that can be in this field. Only for String fields.
unique (array) To verify that the field in the table is unique. If it's necessary to check that a field is unique compared to other fields, then they need to be in an array. If this isn't necessary (i.e. we're checking just this one field), then an empty array needs to be set. It's not necessary to put the field that has this option set into the array.
current_table_only (boolean) Checks whether a value in a field is unique in the current table (live or temporary). By default, the field is checked in both the live and temporary tables (if accessible).
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).
Image:Tipbox Icon.gif Если та, или иная опция не нужна, то можно просто убрать её определение из массива опций поля. В таком случае не надо будет ставить её значение в 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) Название класса накладываемого форматера. Вот самые ходовые классы:
  • kFormatter - для обработки чисел, денежных сумм, почтовых адресов
  • kOptionsFormatter - для работы с элементами ограниченного выбора (dropdown, radio buttons и т.п.)
  • kDateFormatter - для обработки дат
  • kUploadFormatter - для загрузки файлов на сервер

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

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

В K4 есть механизм, который автоматически выстраивает массив для опции Fields. Чтобы воспользоваться им следуйте приведённым шагам:

  • пойти в секцию "Configuration -> System Tools" (в Platform) или "Tools -> System Tools" (в In-Portal);
  • в поле "Table Structure" вписать имя таблицы (можно без TABLE_PREFIX) или префикс от unit config;
  • нажать на кнопку "Go";
  • откроется новое окно со структурой введённой таблицы:
Автоматически построенная структура таблицы
Автоматически построенная структура таблицы


Image:Infobox Icon.gif При добавлении новых полей в таблицу нужно повторить все выше описанные шаги, но из результата скопировать описание только нужных полей, а не всех как обычно. Не надо писать всё руками.

При построении структуры полям автоматически прописываются (если удаётся определить) следующие опции:

  • type - php тип значения, которое будет храниться в поле;
  • not_null - NULL или NOT NULL пометка;
  • default - значение по умолчанию;
  • formatter - класс форматера, пока только для дробный полей (float, double, decimal);
  • max_len - ограничение по длине значения в поле, только для строковых полей (varchar).

Функциональность доступна начиная с Core v 4.1.0.