webinmd · Ibochkarev · Aug 9, 2026 · Aug 9, 2026
diff --git a/README.md b/README.md
@@ -1,84 +1,121 @@
 # mixedimage
 
-mixedImage - modx custom TV  [сhangelog](core/components/mixedimage/docs/changelog.txt)
-
-![mixedImage](mixedimage2.png) 
+mixedImage — кастомный TV для MODX. [Changelog](core/components/mixedimage/docs/changelog.txt)
 
+![mixedImage](mixedimage2.png)
 
 ## Требования
+
 - PHP >= 7.0
-- MODX >= 2.8 
+- MODX >= 2.8
+
+## Что делает
+
+Добавляет тип TV **Смешанная загрузка файла / Mixed Image Input**.
+
+Вы загружаете файл через менеджер MODX, с компьютера, по URL или обрезаете уже загруженное изображение. Поле рассчитано на картинки. Другие типы файлов тоже проходят, если их разрешает сайт. Для не-изображений отключите превью, иначе под полем будет битая миниатюра.
 
--------------------------------------- 
+## Настройки TV
 
-Добавляет новый тип TV поля: **Смешанная загрузка файла/Mixed Image Input**
+**Путь сохранения** — папка относительно корня медиа-источника. Если у TV свой источник с `assets/images/`, а в пути указали `uploads/`, итоговая папка будет `assets/images/uploads/`.
 
-Данный тип поля позволяет прикреплять изображения к ресурсам используя стандартный менеджер файлов, либо напрямую с компьютера пользователя, минуя все остальные шаги.
-Предназначен для загрузки изображений, но может загружать и другие типы файлов, разрешенные для загрузки в системных настройках сайта, но в данном случае необходимо отключить показ миниатюр, чтобы не было битой картинки.
+**Удаление файла** — при «Да» очистка поля удаляет файл с диска.
 
-#### При создании TV такого типа можно указать следующие настройки: 
+**Префикс имени файла** — строка в начале имени. Пример: `{rand}_`
 
-**- Путь сохранения** - папку в которую будут загружаться картинки с компьютера пользователя (ВАЖНО: при указании источника файлов отличным от стандартного, этот путь будет браться с учетом папки источника файлов)
-*Например вы создали новый источник файлов IMAGES и указали ему путь assets/images/ (в настройках источника файлов), а в поле Путь сохранения указали папку uploads/ - итоговая папка загрузки файлов будет такой: assets/images/uploads/*
+Плейсхолдеры префикса:
 
-**- Удаление файла** - если выставлено "Да", то при очистке поля файл физически удаляется с сервера
+- `{id}` — ID ресурса
+- `{pid}` — ID родителя
+- `{alias}` — алиас ресурса
+- `{palias}` — алиас родителя
+- `{tid}` — ID TV
+- `{uid}` — ID пользователя
+- `{rand}` — случайная строка (длина в системной настройке)
+- `{t}` — timestamp
+- `{y}`, `{m}`, `{d}`, `{h}`, `{i}`, `{s}` — компоненты даты и времени
 
-**- Префикс имени файла** - добавляет данную строку в начало наименования файла, можно использовать различные плейсхолдеры. Пример: {rand}_
+**Принимаемые типы MIME** — дополнительный список через запятую. Пример: `image/jpeg, image/png, application/pdf`
 
-* {id} - ID ресурса
-* {pid} - ID ресурса родителя
-* {alias} - Алиас ресурса
-* {palias} - Алиас ресурса родителя
-* {tid} - ID доп. поля (tv)
-* {uid} - ID юзера
-* {rand} - Случайная строка *(количество символов указывается в системных настройках)*
-* {t} - Время в формате timestamp
-* {y} - Год
-* {m} - Месяц
-* {d} - День
-* {h} - Час
-* {i} - Минута
-* {s} - Секунда
+**Использовать префикс как имя файла** — имя файла полностью берётся из префикса, без исходного имени загрузки.
 
-**- Принимаемые типы MIME** - указывает какие типы файлов можно загружать (по умолчанию те что указаны в системных настройках modx)
-*Например: image/jpeg, image/png, application/pdf*
+**Показать превью** — миниатюра или видеоплеер под полем (по умолчанию включено).
 
-**- Использовать префикс как имя файла** - позволяет не обращать внимания на пользовательское название файла и полностью заменить его на значение из поля **Префикс имени файла**
+**Показывать значение TV** — путь к файлу под полем (по умолчанию включено).
 
-**- Показать изображение** - выводить под полем изображение миниатюры или нет *(по умолчанию выводит)*. 
+**Параметры для ресайза изображений** — параметры phpThumb при выводе.
+
+Примеры:
+
+```
+w=200&h=200&zc=1
+fltr=wmt|Hello|60|C|ff0000|
+fltr=wmi|/assets/wt.png|C|
+```
 
-**- Показывать значение TV** - выводить под полем путь к загруженному файлу или нет *(по умолчанию выводит)*
+**Список кнопок (triggerlist)** — кнопки через запятую: `clear`, `manager`, `pc`, `url`, `crop`. По умолчанию: `clear,manager,pc`.
 
-**- Параметры для ресайза изображений** - параметры для modphpthumb.
+## Обрезка изображения (Crop)
 
-*Примеры: <br>
-w=200&h=200&zc=1   <br>
-для наложения ватермарка:   <br>
-fltr=wmt|Hello|60|C|ff0000|   <br>
-fltr=wmi|/assets/wt.png|C|   <br>*
+Добавьте `crop` в **triggerlist**, например: `clear,manager,pc,crop`.
 
-------
+В блоке **Crop** в настройках TV:
 
+| Опция | Назначение |
+| --- | --- |
+| `crop_ratio` | Пропорции рамки: `1/1`, `16/9`, `450/500` |
+| `crop_width` | Ширина результата в px |
+| `crop_height` | Высота результата в px |
+| `crop_suffix` | Суффикс имени файла. Пусто — перезапись. `time()` — новый файл с `_timestamp` |
+| `crop_options` | Доп. опции CropperJS: `zoomOnWheel: false, viewMode: 1` |
 
-###Системные настройки
+Пустой суффикс перезаписывает исходный файл. `time()` каждый раз создаёт новое имя. Если суффикс уже есть в имени, повторно не добавляется.
 
-**- mixedimage.random_lenght** - Длина строки для плейсхолдера {rand} 
+### Событие OnMixedImageCrop
+
+После сохранения обрезанного файла вызывается системное событие `OnMixedImageCrop`:
+
+- `image` — абсолютный путь к файлу на диске
+- `tvId` — ID TV
+
+Пример плагина с водяным знаком после crop:
+
+```php
+<?php
+switch ($modx->event->name) {
+    case 'OnMixedImageCrop':
+        if (!$image) {
+            return;
+        }
+
+        $watermark = $modx->runSnippet('phpthumbon', [
+            'input' => $image,
+            'options' => 'fltr=wmi|/assets/template/images/watermark.png|C|100',
+        ]);
+
+        rename(MODX_BASE_PATH . $watermark, $image);
+        break;
+}
+
+return;
+```
 
-**- mixedimage.translit** - Транслитерация файлов, позволяет заменять кириллицу на латиницу в названии файла во избежание возможных проблем на некоторых хостингах. Настройка работает только при установленном дополнении "translit"
+## Системные настройки
 
-**- mixedimage.check_resid** - Загружать только при редактировании. Пока ресурс не будет сохранен, файл не получится загрузить. Рекомендуется оставить включенным эту настройку. Иначе могут возникнуть проблемы при использовании плейсхолдеров {alias} и {palias} - у несохранных ресурсов они будут возвращать пустые значения.
+**mixedimage.random_lenght** — длина строки для `{rand}`.
 
+**mixedimage.translit** — транслит имён файлов. Нужен установленный пакет translit.
 
---------------------------------------
+**mixedimage.check_resid** — загрузка только при редактировании сохранённого ресурса. Рекомендуется оставить включённым: у несохранённых ресурсов `{alias}` и `{palias}` пустые.
 
-### Пример работы с MIGX 
+## MIGX
 
-* Создаnm TV (например migx_img) с типом **Смешанная загрузка файла**, не назначая никакому шаблону, настроить согласно текущему проекту (указать источник файлов или папку) 
-* Создать TV (например slider) с типом **migx** и в конфигурации (Вкладки формы) для поля с изображением прописать такие строки для каждой необходимой картинки
+1. Создайте TV `migx_img` с типом **Смешанная загрузка файла**. Не назначайте шаблону. Укажите источник или путь.
+2. Создайте TV `slider` с типом **migx**. В конфигурации формы для полей изображений:
 
 ```json
- {"field":"image","caption":"Изображение 1","inputTV":"migx_img"},
- {"field":"image2","caption":"Изображение 2","inputTV":"migx_img"}
+{"field":"image","caption":"Изображение 1","inputTV":"migx_img"},
+{"field":"image2","caption":"Изображение 2","inputTV":"migx_img"}
 ```
 
-И тогда при добавления новой строки в migx будут поля выбора файла согласно типу migx_img
+В новой строке MIGX появятся поля загрузки по настройкам `migx_img`.