From In-Portal Developers Guide

Revision as of 22:27, 26 April 2009

Unit Configs
Статьи в этой категории
Unit Configuration File Registration of Unit Classes Defining Database, Virtual and Calculated Fields Formatters Hooks Regular Events Using "TitlePresets" Option

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.

Required Options

Not Required Options

Validation Options

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:

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:

Automatic Structuring

K4 has a mechanism that automatically builds an array for Fields options. To use it, following these steps:

• Go to section "Configuration -> System Tools" (in Platform) or "Tools -> System Tools" (in In-Portal);
• In the field "Table Structure" enter the table name' (without TABLE_PREFIX is ok) or unit config prefix;
• Press "Go" button;
• A new window will open with the structure of the table:

Automatically built table structure

When adding new fields to a table all of the above steps need to be taken, but from the result copy only the needed fields rather than all of them as usual. It's not necessary to write everything by hand.

While building the structure of the fields, the following options are automatically set (if possible to determine):

• type - PHP data value type that's going to be stored in the field;
• not_null - NULL or NOT NULL;
• default - Default value;
• formatter - Formatter class, for now only for numerical fields (float, double, decimal);
• max_len - Limit on the length of a field value, only for String fields (varchar).

Functionality available starting with Core v 4.1.0.