Устройство и хранение полей

← К разделу «Поля документов»

Определение и значение

Описание поля хранится в контентной таблице rubric_fields. Основные свойства:

Свойство	Назначение
`Id`	Стабильный ID поля.
`rubric_id`	Рубрика, которой принадлежит поле.
`rubric_field_type`	Код зарегистрированного типа.
`rubric_field_alias`	Человекочитаемый стабильный ключ для API и шаблонов.
`rubric_field_settings`	JSON с настройками и правилами валидации.
`rubric_field_default`	Значение по умолчанию; у старых типов может содержать legacy-конфигурацию.
`rubric_field_numeric`	Необходимость числового индекса.
`rubric_field_template`	Точечный вывод в документе.
`rubric_field_template_request`	Точечный вывод в запросе/списке.

Значения документа хранятся по паре document_id + rubric_field_id в document_fields. Длинный хвост значения может лежать в document_fields_text. Писать в эти таблицы напрямую не нужно: панель управления и JSON API используют единый writer, который нормализует поле, обновляет обе части и перестраивает снимок.

Scalar и JSON

Метод save() по контракту возвращает строку. Простое поле возвращает каноническое scalar-значение, а структурное кодирует массив в JSON без экранирования Unicode и URL.

public function save(FieldContext $ctx)
{
    return Json::encode(array(
        'width' => (float) $ctx->value['width'],
        'height' => (float) $ctx->value['height'],
    ), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
}

При чтении FieldValueCodec::decodeStructured() понимает JSON и временно понимает старый PHP serialize без разрешения классов.

Не храните JSON вручную в scalar-поле ради нескольких визуальных параметров. Настройки представления принадлежат rubric_field_settings, а значение документа должно содержать только данные конкретного документа.

Числовой индекс

Если isNumeric() возвращает true, writer дополнительно записывает число в field_number_value. Этот индекс используется сортировкой, условиями запросов и range-фильтрами. save() такого типа обязан возвращать каноническое число с точкой без пробелов и единиц измерения.

FieldContext

Каждый метод типа получает FieldContext:

$ctx->value;                 // текущее значение
$ctx->definition;            // строка rubric_fields
$ctx->document;              // документ, если доступен на этом этапе
$ctx->rubric;                // рубрика, если доступна
$ctx->mode;                  // edit, view, filter или save
$ctx->extra;                 // дополнительные данные вызывающего кода

$ctx->fieldId();
$ctx->alias();
$ctx->type();
$ctx->rubricId();
$ctx->inputName();           // fields[123]
$ctx->inputName('[]');       // fields[123][]
$ctx->settings();
$ctx->setting('unit', '');
$ctx->legacyDefault();

Порядок сохранения

content.field.normalizing может изменить входные значение и определение.
Вызывается FieldType::save().
FieldValueCodec приводит результат к строке хранения.
content.field.normalized может заменить нормализованный результат.
FieldValidator проверяет правила поля.
content.field.saving может заменить значение или отменить запись поля.
Writer обновляет short/text части и числовой индекс.
Вызывается content.field.saved.
После сохранения документа перестраивается его JSON-снимок.

Чтобы все эти этапы выполнялись, модуль не должен самостоятельно обновлять таблицы значений через SQL.

5.0 KiB Raw Blame History