K4:Defining Database, Virtual and Calculated Fields
From In-Portal Developers Guide
| ||
---|---|---|
Статьи в этой категории | ||
|
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:
|
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) | 'min_value_exc' => 0 . Field must be filled in. If a value is not set, then the field will contain an error. Zero as the field value doesn't result in an error saying that the field wasn't filled in. However, if the field value being set to zero should result in an error, it's possible to additionally set an interval for what the value must be, for example 'min_value_exc' => 0 .
|
All of the above described options can be combined into meaningful groups:
- intervals (
max_value_inc
,min_value_inc
,max_value_exc
,min_value_exc
) - options used for checking whether a field value falls in the indicated range. - length (
max_len
,min_len
) - options used for checking the length of a String.
If one or another option is not need, then its declaration can simply be removed from the array of field options, making it not necessary to set its value to 0 or false .
|
Error Messages
For each field it's possible to set alternative error message text for all error messages by using the option error_msgs
(array). The below table describes all standard errors:
Pseudo | Description | Default Value | Controlled by Options |
---|---|---|---|
required | Field value not filled in. | !la_err_required! | required |
unique | Field value not unique. | !la_err_unique! | unique |
value_out_of_range | Field value is not within the indicated range | !la_err_value_out_of_range! | max_value_inc, min_value_inc, max_value_exc, min_value_exc |
length_out_of_range | String too long. | !la_err_length_out_of_range! | max_len, min_len |
bad_type | Field value type isn't the type it's set to be (for example, a character was entered instead of an integer). | !la_err_bad_type! | type |
invalid_format | String format isn't as required. | !la_err_invalid_format! | regexp |
bad_date_format | Date format isn't as required. | !la_err_bad_date_format! | опции kDateFormatter |
primary_lang_required | Field value not entered in primary language. | !la_err_primary_lang_required! | required, kMultiLanguage Options |
bad_file_format | Attempt to upload a file whose (mime-type ) isn't in the allowed types. | !la_error_InvalidFileFormat! | allowed_types, опции kUploadFormatter |
bad_file_size | Attempt to upload a file whose size is greater than allowed maximum size. | !la_error_FileTooLarge! | max_size, опции kUploadFormatter |
cant_save_file | File uploaded to the server couldn't be saved to the requested directory. | !la_error_cant_save_file! | upload_dir, опции kUploadFormatter |
This option is set in the form of an associative one-dimensional array, where each key is an error's "pseudo
" (see the above table) and each field is the error message.
'error_msgs' => Array ( 'required' => '!la_error_CustomRequiredError!' )
To make it so that a phrase translation is used as an error message it's name must be enclosed in exclamation marks:
- "
!la_error_ErrorPhrase!
" - phrase (it's translation in the current language will be the error message); - "
Error Message
" - text (will be the same for all languages).
Formatter Options
All of the remaining options are processed with specific formatters. Some of them for example are:
Option Name | Option Description |
---|---|
formatter (string) | Name of the formatter's class. Here are the most common classes:
The specifics about which formatters exist and how to use them can be read in this article. |
Автоматическое построение структуры
В 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.