Category page

Editing a product category in the MiniShop3 admin panel.

Overview

The category edit page (msCategory) extends standard MODX functionality with product management features:

Product table with drag-and-drop sorting
Filtering and search
Bulk operations (publish, delete)
Configurable columns and actions
Category options management

Tab structure

Products

Main category tab — product table with:

Feature	Description
Drag-and-drop	Sort products by dragging
Filters	Search, published status, custom filters
Bulk operations	Publish, unpublish, delete
Configurable columns	Via Utilities → Grid columns
Actions	View, edit, delete, duplicate

Document

Standard MODX tab with resource fields:

Field	Description
`pagetitle`	Category name
`longtitle`	Extended title
`description`	Meta description
`introtext`	Short description
`content`	Full description
`alias`	URL alias
`parent`	Parent category

Settings

Resource system settings:

Template
Publication (date, status)
Indexing and caching
Category options — configure product options in this category (see below)

Category options

From v1.10.0-beta1

The tab is fully Vue (CategoryOptionsTab component). The legacy ExtJS grid and Processors/Category/Option/* processors were removed.

Grid of options linked to this category, with:

Drag-and-drop sorting — order (position) is saved in one POST on drop (/api/mgr/categories/{id}/options/sort)
Inline editing on double-click:
- Default value — used as the default in the product form
- Name (for category) — per-category override of the global caption (empty = use global)
"Global" column (read-only) — shows caption from msOption for comparison with the override
Bulk actions (checkbox selection): Activate / Deactivate / Make required / Remove required / Delete
"Add option" button — dialog to pick an existing option with fields: default value, active, required, caption/description override
"Copy options from category" button — copies all links from another category (skips duplicates). After copy, msCategoryOption::afterSave automatically applies options to all products in the current category.

Resource groups

Access control for the category.

Product table

Technology

The product table is built with Vue 3 + PrimeVue for modern UX:

Virtualization for large lists
Dynamic data loading
Reactive filters
Smooth drag-and-drop animation

Column configuration

Table columns are configured in Utilities → Grid columns (grid category-products).

Deprecated setting

The system setting ms3_category_grid_fields was removed in 1.7.0. Use Grid columns instead.

Inline editing

Double-click a cell to edit in place:

Editor type	Fields
`text`	`pagetitle`, `longtitle`, `article`, `made_in`
`number`	`price`, `old_price`, `weight`
`boolean`	`published`, `new`, `popular`, `favorite`

Configure in Utilities → Grid columns, grid category-products: enable editable, set editor_type (text, number, select, combo). Step-by-step: Grid columns cookbook.

Table column configuration

Via interface

Open Utilities → Grid columns
Select the category-products grid
Configure visibility, order, column width
Save

Via API and utilities

In 1.13.x there is no PHP file core/components/minishop3/custom/grids/category-products.php. Columns live in ms3_grid_fields and are configured via:

Utilities → Grid columns (grid_key=category-products)
Manager API /api/mgr/grid-config/category-products (see Grid columns cookbook)

Example: add a column via API:

http

POST /api/mgr/grid-config/category-products/field

json

{
  "field_name": "stock",
  "label": "Stock",
  "type": "model",
  "visible": true,
  "sortable": true,
  "editable": true,
  "editor_type": "number",
  "config": {}
}

Inline edit uses editable, editor_type (text, number, select, combo), and optional editor_options. Cell write permission: msproduct_save (PUT /api/mgr/categories/{id}/products/{productId}/data).

Column types

Type	Description	Example
`model`	Model field	Title, SKU
`price`	Price with `displayConfig`	1,234.56
`weight`	Weight with `displayConfig`	0.5 kg
`boolean`	Yes/No	Published
`image`	Thumbnail	Product photo
`template`	HTML template	Product link
`actions`	Action buttons	Edit, delete
`relation`	Related table	Status name
`badge`	Colored tag	Status with color
`option`	Product option	`option.key`
`computed`	PHP column class	`computed.className`

Full reference: Grid columns.

Relation and badge

Relation loads a JOIN. For badge in the orders grid, hidden relation columns supply text and HEX; the visible column is type badge with fields at the top level of config (not under computed):

json

{
  "type": "badge",
  "source_field": "status_name",
  "color_field": "status_color"
}

For type computed, config must include computed.className (class implements ComputedFieldInterface).

In category-products, relation aggregation is not supported.

Status colors

In msOrderStatus, color is often HEX without #. The UI prepends # when rendering a badge.

Adding actions to the column

Action configuration

Actions are configured in a column with type actions:

php

[
    'name' => 'actions',
    'label' => 'Actions',
    'visible' => true,
    'type' => 'actions',
    'width' => '180px',
    'actions' => [
        [
            'name' => 'view',
            'handler' => 'view',
            'icon' => 'pi-eye',
            'label' => 'view',
        ],
        [
            'name' => 'edit',
            'handler' => 'edit',
            'icon' => 'pi-pencil',
            'label' => 'edit',
        ],
        [
            'name' => 'publish',
            'handler' => 'publish',
            'icon' => 'pi-check',
            'iconOff' => 'pi-times',
            'label' => 'publish',
            'labelOff' => 'unpublish',
            'toggleField' => 'published',
        ],
        [
            'name' => 'duplicate',
            'handler' => 'duplicate',
            'icon' => 'pi-copy',
            'label' => 'duplicate',
        ],
        [
            'name' => 'delete',
            'handler' => 'delete',
            'icon' => 'pi-trash',
            'label' => 'delete',
            'severity' => 'danger',
            'confirm' => true,
            'confirmMessage' => 'product_delete_confirm_message',
        ],
    ],
]

Action parameters

Parameter	Type	Description
`name`	string	Unique identifier
`handler`	string	Handler name (view, edit, delete, publish, duplicate)
`icon`	string	PrimeIcons icon (pi-*)
`iconOff`	string	Icon for off state (toggle)
`label`	string	Lexicon key for tooltip
`labelOff`	string	Lexicon key for off state
`severity`	string	Button style (danger, success, warning)
`confirm`	bool	Require confirmation
`confirmMessage`	string	Lexicon key for confirmation message
`toggleField`	string	Field for toggle actions
`visible`	function	Visibility condition

Custom actions via JavaScript

javascript

document.addEventListener('DOMContentLoaded', () => {
  if (!window.MS3ActionRegistry) return

  MS3ActionRegistry.register('addToFavorites', async (data, context) => {
    const response = await fetch('/assets/components/mycomponent/api.php', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        action: 'addToFavorites',
        product_id: data.id
      })
    })

    const result = await response.json()

    if (result.success) {
      return { success: true, refresh: true }
    }

    return { success: false, message: result.message }
  })
})

Add the action to the actions column config via Utilities → Grid columns or PUT grid-config:

json

{
  "name": "addToFavorites",
  "handler": "addToFavorites",
  "icon": "pi-heart",
  "label": "Add to favorites"
}

Hooks for standard actions

javascript

MS3ActionRegistry.registerBeforeHook('delete', async (data, context) => {
  if (data.orders_count > 0) {
    return false
  }
  return true
})

MS3ActionRegistry.registerAfterHook('publish', async (data, result, context) => {
  console.log(`Product ${data.id} published:`, result)
})

Adding a filter

Filter structure

Filters are configured via config files:

Default: core/components/minishop3/config/filters/category-products.php
Custom: core/components/minishop3/custom/filters/category-products.php

The custom file overrides the default and is not overwritten on component update.

Filter configuration

php

// core/components/minishop3/custom/filters/category-products.php

return [
    // Text search
    'query' => [
        'type' => 'text',
        'label' => 'search',
        'placeholder' => 'search_by_title_article',
        'width' => '250px',
        'position' => 10,
    ],

    // Published filter
    'published' => [
        'type' => 'select',
        'label' => 'published',
        'placeholder' => 'all',
        'source' => [
            'type' => 'static',
            'options' => [
                ['label' => 'ms3_yes', 'value' => 1],
                ['label' => 'ms3_no', 'value' => 0],
            ],
        ],
        'width' => '120px',
        'position' => 20,
    ],

    // Vendor filter
    'vendor_id' => [
        'type' => 'select',
        'label' => 'vendor',
        'placeholder' => 'all',
        'source' => [
            'type' => 'model',
            'class' => 'MiniShop3\\Model\\msVendor',
            'valueField' => 'id',
            'labelField' => 'name',
            'where' => ['active' => 1],
            'sort' => ['name' => 'ASC'],
        ],
        'width' => '180px',
        'position' => 30,
    ],

    // "New" flag filter
    'new' => [
        'type' => 'select',
        'label' => 'new',
        'placeholder' => 'all',
        'source' => [
            'type' => 'static',
            'options' => [
                ['label' => 'ms3_yes', 'value' => 1],
                ['label' => 'ms3_no', 'value' => 0],
            ],
        ],
        'width' => '100px',
        'position' => 40,
    ],

    // Hidden filter (not shown by default)
    'deleted' => [
        'type' => 'select',
        'label' => 'deleted',
        'visible' => false,
        'position' => 100,
    ],
];

Filter parameters

Parameter	Type	Description
`type`	string	Filter type: `text`, `select`, `datepicker`, `daterange`
`label`	string	Lexicon key for label
`placeholder`	string	Lexicon key for placeholder
`width`	string	CSS width (`150px`, `20%`)
`position`	int	Display order (lower = left)
`visible`	bool	Show filter (default `true`)
`source`	array	Data source config for `select`

Source types for select

Static options

php

'source' => [
    'type' => 'static',
    'options' => [
        ['label' => 'Yes', 'value' => 1],
        ['label' => 'No', 'value' => 0],
    ],
]

From xPDO model

php

'source' => [
    'type' => 'model',
    'class' => 'MiniShop3\\Model\\msVendor',
    'valueField' => 'id',
    'labelField' => 'name',
    'where' => ['active' => 1],
    'sort' => ['name' => 'ASC'],
    'limit' => 500,
]

Server-side filter handling

Filters are applied automatically in CategoryProductsController:

php

// core/components/minishop3/src/Controllers/Api/Manager/CategoryProductsController.php

// Boolean filters for msProduct fields
$productBooleanFields = ['published', 'deleted', 'hidemenu'];
foreach ($productBooleanFields as $field) {
    if (isset($params[$field]) && $params[$field] !== '') {
        $c->where(["msProduct.{$field}" => (int)$params[$field]]);
    }
}

// Boolean filters for msProductData fields
$dataBooleanFields = ['new', 'popular', 'favorite'];
foreach ($dataBooleanFields as $field) {
    if (isset($params[$field]) && $params[$field] !== '') {
        $c->where(["Data.{$field}" => (int)$params[$field]]);
    }
}

// Numeric filters
$dataNumericFields = ['price', 'vendor_id'];
foreach ($dataNumericFields as $field) {
    if (isset($params[$field]) && $params[$field] !== '') {
        $c->where(["Data.{$field}" => $params[$field]]);
    }
}

Adding a custom filter

Step 1: add filter to config

php

// core/components/minishop3/custom/filters/category-products.php

return [
    // ... existing filters ...

    'price_range' => [
        'type' => 'select',
        'label' => 'price_range',
        'placeholder' => 'all',
        'source' => [
            'type' => 'static',
            'options' => [
                ['label' => 'Up to 1000', 'value' => '0-1000'],
                ['label' => '1000-5000', 'value' => '1000-5000'],
                ['label' => '5000-10000', 'value' => '5000-10000'],
                ['label' => 'Over 10000', 'value' => '10000+'],
            ],
        ],
        'width' => '150px',
        'position' => 25,
    ],
];

Step 2: handle filter on server

Create a plugin to handle the custom filter:

php

<?php
// Plugin: CustomCategoryFilters
// Events: msOnBeforeCategoryProductsQuery

if ($modx->event->name !== 'msOnBeforeCategoryProductsQuery') return;

$params = $modx->event->params['params'] ?? [];
$query = $modx->event->params['query'];

// Price range filter
if (!empty($params['price_range'])) {
    $range = $params['price_range'];

    if ($range === '10000+') {
        $query->where(['Data.price:>=' => 10000]);
    } else {
        [$min, $max] = explode('-', $range);
        $query->where([
            'Data.price:>=' => (int)$min,
            'Data.price:<=' => (int)$max,
        ]);
    }
}

Bulk operations

Available operations

Operation	Description
Publish	Publish selected products
Unpublish	Unpublish selected products
Delete	Mark as deleted
Restore	Restore deleted products

Bulk operations API

POST /api/mgr/categories/{id}/products/multiple

Parameters:

json

{
  "method": "publish",
  "ids": [1, 2, 3]
}

Available methods: publish, unpublish, delete, undelete, show, hide

Drag-and-drop sorting

When it works

Drag-and-drop sorting is available when:

Sorting by menuindex
"Show nested products" mode is off
No active filters

Sort API

POST /api/mgr/categories/{id}/products/sort

Parameters:

json

{
  "items": [
    {"id": 5, "menuindex": 0},
    {"id": 3, "menuindex": 1},
    {"id": 8, "menuindex": 2}
  ]
}

System settings

Setting	Description	Default
`ms3_category_show_nested_products`	Show nested products	`false`
`ms3_category_show_options`	Show category options	`true`
`ms3_category_remember_tabs`	Remember active tab	`true`
`ms3_category_remember_grid`	Remember table state	`true`

Events

msOnManagerCustomCssJs

Adding CSS/JS to the category page:

php

<?php
// Plugin: MyCategoryExtension
// Events: msOnManagerCustomCssJs

if ($modx->event->name !== 'msOnManagerCustomCssJs') return;

$page = $modx->event->params['page'] ?? '';

if ($page === 'category_update' || $page === 'category_create') {
    $modx->regClientCSS('/assets/components/mycomponent/css/category.css');
    $modx->regClientStartupScript('/assets/components/mycomponent/js/category.js');
}

API Endpoints

Category products

GET /api/mgr/categories/{id}/products

Parameters:

Parameter	Description
`start`	Offset (pagination)
`limit`	Number of records
`sort`	Sort field
`dir`	Direction (ASC/DESC)
`query`	Search query
`nested`	Show nested (0/1)
`published`	Published filter
`*`	Any other filters

Filter configuration

GET /api/mgr/categories/{id}/products/filters

Response:

json

{
  "success": true,
  "object": {
    "filters": {
      "query": {
        "type": "text",
        "label": "search",
        "position": 10
      },
      "published": {
        "type": "select",
        "label": "published",
        "options": [
          {"label": "Yes", "value": 1},
          {"label": "No", "value": 0}
        ],
        "position": 20
      }
    }
  }
}

Inline product data editing

PUT /api/mgr/categories/{id}/products/{productId}/data

JSON body — msProductData fields (price, article, etc.) from the category grid without opening the product card. Controller: CategoryProductsController::updateProductData().

Utilities: Grid columns — table column configuration
Product — product edit page
System settings — all component settings

Settings

Utilities

Category page ​

Overview ​

Tab structure ​

Products ​

Document ​

Settings ​

Category options ​

Resource groups ​

Product table ​

Technology ​

Column configuration ​

Inline editing ​

Table column configuration ​

Via interface ​

Via API and utilities ​

Column types ​

Relation and badge ​

Adding actions to the column ​

Action configuration ​

Action parameters ​

Custom actions via JavaScript ​

Hooks for standard actions ​

Adding a filter ​

Filter structure ​

Filter configuration ​

Filter parameters ​

Source types for select ​

Static options ​

From xPDO model ​

Server-side filter handling ​

Adding a custom filter ​

Step 1: add filter to config ​

Step 2: handle filter on server ​

Bulk operations ​

Available operations ​

Bulk operations API ​

Drag-and-drop sorting ​

When it works ​

Sort API ​

System settings ​

Events ​

msOnManagerCustomCssJs ​

Category page

Overview

Tab structure

Products

Document

Settings

Category options

Resource groups

Product table

Technology

Column configuration

Inline editing

Table column configuration

Via interface

Via API and utilities

Column types

Relation and badge

Adding actions to the column

Action configuration

Action parameters

Custom actions via JavaScript

Hooks for standard actions

Adding a filter

Filter structure

Filter configuration

Filter parameters

Source types for select

Static options

From xPDO model

Server-side filter handling

Adding a custom filter

Step 1: add filter to config

Step 2: handle filter on server

Bulk operations

Available operations

Bulk operations API

Drag-and-drop sorting

When it works

Sort API

System settings

Events

msOnManagerCustomCssJs