Опции товаров

Откройте Пакеты → MiniShop3 → Настройки → Свойства товаров.

С v1.10.0-beta1

Интерфейс опций построен на Vue 3 + PrimeVue. Старые ExtJS-окна и процессоры Processors/Settings/Option/*, Processors/Category/Option/* удалены. Все операции идут через /api/mgr/options/* и /api/mgr/categories/{id}/options/*.

Назначение

Опции хранят характеристики товара (EAV): цвет, размер, материал, любые свои ключи. Компонент не изменяет таблицы ядра MODX.

Интерфейс

Вкладка «Опции»

• Слева: дерево категорий MODX (class_key = msCategory). Флажки независимые: отметка на родителе не выделяет дочерние категории. Контекстное меню управляет ветками (обновить, развернуть, выделить), есть поиск по названию.
• Справа: грид опций. Фильтры: выбранные категории и группа (option_group_id). Массовые действия: назначить опции категориям, удалить.

Диалог создания и правки: слева форма (ключ, название, описание, тип, группа msOptionGroup, единица измерения), справа дерево категорий для привязки. Для combobox / comboMultiple / comboColors есть редактор значений с сортировкой перетаскиванием. У comboColors рядом с полем hex стоит ColorPicker.

Вкладка «Группы опций»

Вкладка управляет msOptionGroup: создание, правка, удаление, порядок перетаскиванием. Группы лежат в ms3_option_groups (name, description, sort_order). Это не modCategory: категории других пакетов в списке больше не появляются.

У опции есть поле option_group_id. Удаление группы только отвязывает опции (option_group_id = NULL) — сами опции остаются.

Несовместимые изменения (v1.11)

Существующие группы переносятся при обновлении автоматически. Руками нужно поправить два места:

• в чанках заменить {$option.category_name} и {$option.category} на {$option.group_name};
• в своём коде — вместо удалённого /api/mgr/options/modcategories вызывать /api/mgr/option-groups.

Поля опции

Поле	Тип	Описание
key	string	Уникальный ключ опции (латиница, цифры, _, -)
caption	string	Название для отображения
description	text	Описание опции
measure_unit	string	Единица измерения (шт, кг, см)
option_group_id	int / null	Группа msOptionGroup. Необязательно
type	string	Тип значения (см. ниже)
properties	JSON	Дополнительные настройки (для типов со списком значений)

Типы опций

Тип хранится в msOption.type в формате lowerCamelCase. Все 10 поддерживаемых типов:

type	Описание	Редактор значений в настройках	Виджет в карточке товара
textfield	Однострочное текстовое поле	—	InputText
textarea	Многострочный текст	—	Textarea
numberfield	Число	—	InputNumber
datefield	Дата	—	DatePicker (YYYY-MM-DD)
checkbox	Флажок (Да / Нет)	—	Checkbox
comboBoolean	Выпадающий Да / Нет	—	Select из двух значений
combobox	Одиночный выбор из списка	Список строк, порядок перетаскиванием	Select
comboMultiple	Множественный выбор из списка	Список строк, порядок перетаскиванием	MultiSelect
comboColors	Множественный выбор с цветами	Список {value, name=hex} + ColorPicker	MultiSelect с цветовыми квадратами
comboOptions	Свободный ввод тегов с автодополнением	— (значения накапливаются при сохранении товаров)	PrimeVue InputChips + список подсказок из ранее введённых значений

Структура properties для типов со списком

combobox, comboMultiple:

{
  "values": ["S", "M", "L", "XL"]
}

comboColors: hex лежит в name, подпись для людей в value.

{
  "values": [
    { "value": "Красный", "name": "#FF0000" },
    { "value": "Синий",   "name": "#0000FF" }
  ]
}

comboOptions не требует готового списка. На карточке товара вводите любой текст (Enter, запятая или клик вне поля фиксируют значение). Автодополнение берёт значения того же ключа с других товаров через /api/mgr/options/suggestions.

Привязка к категориям

Опция видна в товарах только привязанных категорий. Привязать можно тремя способами:

• В диалоге опции — отметьте категории в дереве справа.
• В карточке категории, вкладка «Опции» — добавьте опцию.
• В гриде опций — выделите несколько и нажмите «Назначить в категории».

Переопределение названия и описания для категории

С v1.10.0-beta1

У связи «опция ↔ категория» (msCategoryOption) есть свои caption и description.

Если в этой категории нужно другое название, задайте его в гриде опций категории (правка по месту в колонке «Название (для категории)») или в диалоге «Добавить опцию». Пустое поле — берётся глобальное название. Заполненное видно в админке на товарах этой категории и на фронтенде через OptionLoaderService::loadForProduct / loadForProducts.

Несколько категорий у товара. Если у родительской и дополнительных категорий названия разные, действует такой порядок:

1. Категория-родитель товара (msProduct.parent)
2. Меньший msCategoryOption.position
3. Меньший category_id (решает при равенстве)

Через PHP

/** @var \MiniShop3\Model\msOption $option */
$option = $modx->getObject(\MiniShop3\Model\msOption::class, ['key' => 'color']);
$option->setCategories([5, 10, 15]); // ID категорий

// Через сервис (с поддержкой override caption/description):
$optionService = $modx->services->get('ms3_option_service');
$optionService->addOptionToCategory(
    optionId: $option->get('id'),
    categoryId: 5,
    defaultValue: 'Красный',
    active: true,
    position: 0,
    caption: 'Цвет обивки',       // override для этой категории
    description: null
);

Значения опций товара

Значения хранятся в таблице ms3_product_options (product_id, key, value). Для многозначных типов (comboMultiple, comboColors, comboOptions) на товар приходится несколько строк с одним key.

Добавление значения

$modx->services->get('ms3_option_service')->saveProductOptions(
    productId: 123,
    options: [
        'color' => 'Красный',            // single value
        'size' => ['S', 'M', 'L'],       // multi value
    ],
    removeOther: true                     // удалить ключи, не упомянутые в $options
);

Получение значений

Стандартный путь — через OptionLoaderService:

$loader = $modx->services->get('ms3_option_service')->getLoader();

// Для одного товара (уже с применённым per-category caption override)
$data = $loader->loadForProduct(123);
// $data = [
//   'color'         => ['Красный'],
//   'color.caption' => 'Цвет обивки',  // override из msCategoryOption (если задан)
//   'size'          => ['S', 'M'],
//   ...
// ]

// Для каталога (batch, без N+1)
$byProduct = $loader->loadForProducts([123, 124, 125]);

Вывод опций

Сниппет msOptions

Выводит список опций для фильтрации:

{'msOptions' | snippet : [
    'tpl' => 'tpl.msOptions.row',
    'parents' => 5
]}

Сниппет msProductOptions

Выводит опции конкретного товара:

{'msProductOptions' | snippet : [
    'product' => $id,
    'tpl' => 'tpl.msProductOptions.row'
]}

В карточке товара

Опции доступны в шаблоне через переменную $options:

{if $options?}
<div class="product-options">
    {foreach $options as $key => $value}
    <div class="option">
        <span class="option-name">{$key}:</span>
        <span class="option-value">{$value}</span>
    </div>
    {/foreach}
</div>
{/if}

Опции в корзине

При добавлении товара в корзину передайте выбранные опции:

JavaScript (Web API)

await ms3.cartAPI.add(123, 1, { color: 'Красный', size: 'L' })

Отображение в корзине

Опции пишутся в позицию корзины и доступны в чанке:

{if $options?}
    {foreach $options as $key => $value}
        <small>{$key}: {$value}</small>
    {/foreach}
{/if}

REST API

Все операции интерфейса идут через Manager API (/assets/components/minishop3/connector.php, action MiniShop3\Processors\Api\Router). Права: mssetting_save для опций, mscategory_save для привязки к категории.

Опции

Метод	Путь	Описание
GET	/api/mgr/options	Список. Параметры: start, limit, option_group_id (0 = без группы), category_id, categories[]
GET	/api/mgr/options/{id}	Одна опция + карта categories
POST	/api/mgr/options	Создать (key, caption, type, option_group_id, properties, categories, …)
PUT	/api/mgr/options/{id}	Частичное обновление
DELETE	/api/mgr/options/{id}	Удалить опцию (каскадом удалятся значения у товаров)
DELETE	/api/mgr/options/bulk	Массовое удаление (ids[])
POST	/api/mgr/options/bulk/assign	Назначить options[] к categories[]
GET	/api/mgr/options/types	Список типов
GET	/api/mgr/options/tree	Дерево категорий msCategory (ленивая загрузка по parent)
GET	/api/mgr/options/suggestions	Уникальные значения для comboOptions (key, query, limit)
GET	/api/mgr/option-groups	Список групп
POST	/api/mgr/option-groups	Создать группу
GET / PUT / DELETE	/api/mgr/option-groups/{id}	Чтение, правка, удаление
PUT	/api/mgr/option-groups/positions	Порядок после перетаскивания
DELETE	/api/mgr/option-groups/bulk	Массовое удаление

Привязки категорий

Метод	Путь	Описание
GET	/api/mgr/categories/{category_id}/options	Опции, привязанные к категории (с global_caption/global_description + category_caption/category_description override)
POST	/api/mgr/categories/{category_id}/options	Добавить опцию к категории (option_id, value, active, required, caption, description)
PUT	/api/mgr/categories/{category_id}/options/{option_id}	Частичное обновление связки (value / active / required / position / caption / description)
DELETE	/api/mgr/categories/{category_id}/options/{option_id}	Удалить связку
POST	/api/mgr/categories/{category_id}/options/sort	Сохранить новый порядок (option_ids[])
POST	/api/mgr/categories/{category_id}/options/bulk	Массовые действия: activate / deactivate / require / unrequire / remove для option_ids[]
POST	/api/mgr/categories/{category_id}/options/duplicate	Скопировать все связки из другой категории (category_from), пропуская уже существующие

Импорт опций

При импорте товаров из CSV опции создаются автоматически из столбцов с префиксом option. (точка, не подчёркивание):

pagetitle	price	option.color	option.size
Футболка	1500	Красный	L
Футболка	1500	Синий	M

Опции color и size создаются сами, если их ещё нет. Тип по умолчанию — textfield, поменять его можно потом в интерфейсе.