From In-Portal Developers Guide

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

K4 has two ways of processing/showing data:

• For storing in the database
• For displaying to the user

A classic example of this is a calendar date. The user enters the date in a familiar format, i.e. "28/12/2007 22:10:43" (dd/mm/yyyy hh:mm:ss) and the database stores this date as a timestamp, e.g. "1198872643" (the number of seconds since January 1, 1969). K4 has a set of classes called formatters that automatically take care of such formatting for us. Naturally, they're named formatters because they format data. All formatters are inherited from the kFormatter class. Each has a minimum of 2 accessible methods (maybe more depending on the formatter):

• Format - formats db_value -> form_value (direct formatting)
• Parse - formats form_value -> db_value (reverse formatting)

These methods are automatically called when the kDBBase::GetField (item and list) and kDBItem::SetField (item) methods are used. The kDBBase::GetField method accepts two parameters. The first is the name of the field. The second and optional parameter is $format. $format allows setting a different output format (see the specific formatter's format option) for the current call to this method. This format can also be set in the format parameter in this tag:

<inp2:prefix_Field name="CreatedOn" format="d-m-Y"/>

It's not recommended to use formatters manually.

format behavior can be controlled by setting certain options for the field that's described in the Fields array in unit configs.

kFormatter

Данный форматер используется на формах где требуется вводить числа (т.к. они форматируются согласно региональным установкам), а так же если требуется вводить адреса электронной почты. Этот форматер является базовым классом для всех форматеров, а так же позволяет использовать оператор строго равенства (===) на итоговое значение поля, т.к. производит приведение типов (type casting). Далее перечислены опции, которые использует этот форматер:

kOptionsFormatter

Данный форматер используется на формах, где присутствует элементы ввода с ограниченным выбором (напр. dropdown, radio buttons, checkboxes, multiselect). Данный форматер может содержать статический (заранее определённый) набор опций, а так же динамический набор опций, формируемый при помощи указанного sql запроса. Далее перечислены опции, которые использует этот форматер:

<inp2:m_RenderElement name="inp_edit_options"
	prefix="test-prefix" field="DropdownField" title="la_fld_DropdownField" has_empty="1"
/>

'SELECT %s FROM '.TABLE_PREFIX.'SampleTable ORDER BY SampleName'

Можно комбинировать статические и динамические опции, т.е. задавать полю опцию options и options_sql одновременно. В значениях опций поля, отвечающих за формирование динамических опций для форматера (options_sql, option_key_field, option_title_field) можно указывать ключевое слово "%2$s", которое замениться на ID текущего языка. Обычно это используется когда требуется построить список опций на текущем языке из многоязычного поля (т.е. поля, которое использует форматер kMultiLanguage).

kMultiLanguage

Данный форматер используется для обработки многоязычных полей, т.е. полей, значение в которых может изменяться в зависимости от языка, на котором просматривается сайт. Обычно это элементы (form controls) со свободным вводом данных (textbox, textarea), т.к. у элементов ввода с ограниченным выбором видимая пользователю часть состоит из переводов фраз. В базе данных для каждого поля, использующего этот форматер, автоматически создаётся (напр. при добавлении нового языка) по одной колонке на каждый язык. Название колонки состоит из ID языка и названия поля в формате "l<LanguageId>_<FieldName>", напр. для хранения значения поля TestField в языке с 1-м ID колонка будет называться "l1_TestField". Если требуется добавить новое многоязычное поле в базу данных, то надо:

• добавить его описание в массив Fields в unit config
• воспользоваться функцией "Re-build Multilanguage Fields" в секции "Configuration -> Service Tools" (Platform) или "Tools -> Service" (In-Portal).

Далее перечислены опции, которые использует этот форматер:

Будьте внимательны, т.к. этот форматер добавляет префикс языка (напр. "l5_") только при чтении значения из поля (т.е. в методе Format). А при записи значения в поле (метод Parse) его нужно добавлять в ручную. Это можно наглядно увидеть из следующих примеров:

Форматер изменяет название поля (т.е. добавляет к нему префикс языка) только одном случае, когда префикс языка не указан и читается значение из поля. Во всех остальных случаях название указанного поля и название поля, которое читается из базы данных совпадают.

kDateFormatter

Данный форматер используется для работы с датой и временем. Он используется на формах, где присутствует элементы ввода даты, времени, даты и времени в одном поле. Дата и время на формах вводятся в понятной для человека форме, а в базе хранятся в форме timestamp. Формат даты и времени берётся из региональных настроек системы (Configuration -> Regional). Форматы, используемые данным форматером делятся на 2 группы:

• input formats - используются для ввода данных из форм;
• output formats - используются для отображения данных.

Такое разделение форматов обосновано ограничениями в работе форматера. Для анализа, введённой пользователем, даты и времени этот форматер использует регулярные выражения, в основе которых используются численно-буквенные последовательности фиксированной длинны. Это в некоторой мере ограничивает его возможности (напр. буква "F" из формата дат в php), поэтому для его корректной работы требуется ограничить набор доступных форматов ввода дат. В то же время на отображение дат это ограничение не накладывается. От этого и такое разделение. Далее перечислены опции, которые использует этот форматер:

В качестве значения любой из выше описанных опций задающих формат можно указать значение в форме "_regional_FieldName", где FieldName является названием поля из текущего объекта языка. В этом случае формат будет взят из указанного поля у объекта текущего языка.

Кроме преобразований значения поля этот форматер добавляет новое вычисляемое поле (calculated field), в котором будет отформатированное, по опции format (превращённого в аналогичный формат в SQL), значение поля. Это поле будет называться "<Field>_formatted" (где Field будет соответствовать названию поля с датой). Оно используется в In-Portal для поиска по полям, использующих этот форматер (если его не использовать, то поиск будет идти по значению timestamp). Для Platform эта проблема не актуальна, т.к. в grids над каждой колонкой используется индивидуальный фильтр с собственным форматом.

Так же этот форматер создаёт по 2 виртуальных поля и 2 вычисляемых поля (для редактируемых grids) на каждое поле, на которое он наложен. Они используются для отдельного хранения даты и времени (т.к. на формах редактирования тоже 2 поля):

• <FieldName>_date - для даты (напр. CreatedOn_date);
• <FieldName>_time - для времени (напр. CreatedOn_time).

Если требуется установить значение в поле, то надо пользоваться именно этими двумя полями:

$timestamp = adodb_mktime(); // то, что мы ставим (оригинальное поле с датой: DateField)
$object->SetDBField('DateField_date', $timestamp);
$object->SetDBField('DateField_time', $timestamp);

Если ставить значение в поле на прямую (не использую данные виртуальные поля), то тогда это значение будет переписано значениями из соответствующих виртуальных полей.

kUploadFormatter

Это форматер используется для загрузки файлов на сервер. Существует 2 способа загрузки файлов на сервер, которые понимает этот форматер:

• загрузка с индикатором прогресса загрузки файла (поддерживается только начиная с Flash 7 версии):
  

  Flash upload control

• загрузка без индикации процесса загрузки, используя HTML тэг <input type="file"/> (поддерживается везде):
  

  HTML input upload control

У каждого из них есть свои плюсы и минусы, но исторически сложилось, что в Platform используется индикатор загрузки файла, а в In-Portal нет. Далее перечислены опции, которые использует этот форматер:

Общие опции

опция	описание
format (string)	Данная опция допускает следующие значения: full_url - вернуть ссылку для сохранения файла (для браузера) full_path - вернуть полный путь к файлу на сервере (в файловой системе сервера) file_size - вернуть размер файла в байтах resize:WxH - вернуть масштабированную к указанному размеру картинку (W - ширина, H - высота) img_size - вернуть размеры изображения для img HTML-тэга в виде: width="M" height="N" (доступно начиная с Core v 5.0.0); wm:WM_FILENAME|H_MARGIN|V_MARGIN - наложить указанный водяной знак (watermark) на запрашиваемое изображение: WM_FILENAME - файл, содержащий водяной знак (путь относительно директории с темой на Front-End); H_MARGIN - смещение водяного знака на основном изображении по горизонтали: C - по центру изображения; положительное значение - отступ от левой границы изображения; отрицательное значение - отступ от правой границы изображения; V_MARGIN - смещение водяного знака на основном изображении по вертикали: C - по центру изображения; положительное значение - отступ от верхней границы изображения; отрицательное значение - отступ от нижней границы изображения. Значения resize и wm можно комбинировать используя точку с запятой, напр. 'resize:150x150;wm:platform/img/wm.png|-5|-5'. Если применяется формат "resize" или "files_resized" то предварительно необходимо создать директорию "resized" в директории, где хранятся исходные изображения. В случае, когда требуется обработать поле, в котором находяться несколько файлов надо использовать значения: file_urls - аналог full_url; file_paths - аналог full_path (начиная с версии Core v 4.3.1); file_sizes - аналог file_size; files_resized - аналог resize (начиная с версии Core v 4.2.1); img_sizes - аналог img_size (начиная с версии Core v 5.0.0); wms - аналог wm (начиная с версии Core v 4.2.1). Например для получения масштабированной версии изображения, хранящегося в поле требуется написать следующее: <img src="<inp2:Field name='$field' format='resize:120x120'/>" <inp2:Field name='$field' format='resize:120x120;img_size' no_special='1'/> alt=""/> Если не использовать параметр no_speial тэга Field, то кавычки вокруг размеров изображения заменятся на "&quot;" символы. Также можно указывать формат "img_size/img_sizes" без формата "resize/files_resized".
upload_dir (string)	Директория, куда нужно сохранять закачанный файл. Задаётся относительно значения FULL_PATH константы, напр. "/system/user_files/manufactures/". Если некоторые составляющие пути можно заменить значением констант, то это конечно нужно сделать. Например в Platform есть константа WRITEBALE_BASE со значением "/system", которую можно здесь использовать. Обычно относительный путь для сохранения закачанных файлов (т.е. значение данной опции) определяют в файле constants.php у модуля "Custom" для последующего использования в дальнейшем.
max_size (int)	Максимальный размер одного загружаемого файла в байтах. Если не задан, то будет использоваться значение константы MAX_UPLOAD_SIZE.

Опции только для загрузчика без индикатора

Опции только для загрузчика с индикатором

Задание всех из ниже описанных параметров, кроме multiple, является обязательным для успешной работы загрузчика.

Если не задать хотя-бы один из ниже перечисленных параметров, кнопки "browse" и "upload" работать не будут!

опция	описание
multiple (int)	Максимальное количество файлов, которое можно загрузить в поле. Если загружено больше одного файла, то, в значении поля, имена файлов будут разделены символом вертикальной черты ("|").
direct_links (boolean)	Строить прямые ссылки на сохранение загруженных файлов в swf upload control.
file_types (string)	Маска для имён файлов, которые можно загружать на сервер. Например: '*.jpg;*.gif;*.png'.
files_description (string)	Описание к указанной маске файлов, напр. '!la_title_ImageFiles!'. Значение данной опции не запрещает наличие и фраз и простого текста одновременно. Для того, чтобы текст был рассмотрен, как фраза его надо экранировать одинарными кавычками. Вот более сложный пример: 'sample text !la_phrase! other text'. В данном примере фразой будет текст la_phrase, а остальной текст останется без изменений. К сожалению на данный момент времени фразы, из значения данного параметра не переводятся (см. заявку).

При использовании загрузчика с индикатором файл после закачки (нажатия кнопки "Upload") попадает в директорию "/system/tmp" и только если объект, содержащий поле для загрузки будет сохранён в базу данных (напр. события OnCreate, OnUpdate, OnPreSave, OnSave и т.п.) файл будет перемещён в директорию, указанную в опции upload_dir у используемого поля.

Результат загрузки файлов на сервер может быть удачным, а может и не быть. В таком случае будет показана ошибка. Самая распространённая ошибка о том, что нету права сохранять файлы в директорию заданную в опции upload_dir или директорию "/system/tmp". Так же бывают ошибки о том, что файл нельзя загрузить, т.к.

• его размер больше требуемого;
• его mime-тип не соответствует заданному.

Если файл не загружается по неизвестной причине, то надо проверить наличие атрибута enctype у HTML тэга form. Подробнее об этом здесь.

Translated from: revision 1025