Skip to main content

Thumb3x - Документация

Thumb3x: Современная обработка изображений для MODX 3

Этот компонент был написан, чтобы заполнить пробел в экосистеме MODX 3, где практически отсутствуют современные и надежные инструменты для работы с изображениями. Большинство существующих решений не обновлялись более 10 лет и не используют преимущества новой версии системы.

Ключевые возможности

  • Современные форматы: Конвертация в WebP и AVIF "на лету".

  • Продвинутый движок: В основе лежит высокопроизводительная библиотека Glide 3.0.1.

  • Интеграция с MODX 3: Полная поддержка "Источников файлов".

  • Гибкая обработка: Фильтры, эффекты, водяные знаки и точное позиционирование.

  • Поддержка Fenom: Удобный вызов сниппета с передачей параметров в виде массивов.

  • Управление кэшем: Ведение лога сгенерированных файлов в базе данных с удобной таблицей в админке.

Стандартный вызов MODX

HTML 

<img src="[[!Thumb3x? &input=`path/to/image.jpg` &options=`w=300&h=200`]]" alt="">

Вызов через Fenom

Фрагмент кода 

{'!Thumb3x' | snippet : [
    'input' => 'path/to/image.jpg',
    'options' => [
        'w' => 300,
        'h' => 200
    ]
]}

Основные параметры сниппета

Параметр Альтернатива Описание Пример
input i (Обязательный) Путь к исходному изображению. &input=image.jpg`
sourceId   ID "Источника файлов" для исходного изображения. По умолчанию используется значение из системных настроек. &sourceId=2`
quality q (Переопределяется &options) Качество по умолчанию. &quality=75`

warning Важно: Любые параметры (q, fm и т.д.), указанные внутри строки &options, всегда имеют наивысший приоритет.

Справочник по параметрам обработки (&options)

Официальная документация Glide

Компонент Thumb3x использует библиотеку Glide для всех операций с изображениями. Это означает, что вы можете использовать любые параметры, которые поддерживает сама библиотека.

Самую полную и актуальную информацию по всем возможным параметрам вы всегда можете найти на официальном сайте: https://glide.thephpleague.com/

Размеры и ориентация

Параметр Ключ Описание Пример
Ширина w Ширина итогового изображения в пикселях. w=300
Высота h Высота итогового изображения в пикселях. h=200
Вписывание fit Как вписать изображение. Основные значения: contain, max, stretch, crop. fit=crop
Обрезка crop Точное кадрирование: ширина,высота,x,y. crop=200,150,20,50
DPR dpr Множитель для Retina-дисплеев. dpr=2 вернет картинку вдвое большего размера. dpr=2
Ориентация or Поворачивает изображение. Значения: auto, 0, 90, 180, 270. or=90
Отражение flip Отражает изображение. Значения: v (вертикально), h (горизонтально), both. flip=h

Коррекция и эффекты

Параметр Ключ Описание Пример
Яркость bri Регулировка яркости (-100 до +100). bri=20
Контрастность con Регулировка контрастности (-100 до +100). con=-30
Гамма gam Гамма-коррекция (0.1 до 9.99). gam=2.2
Резкость sharp Усиление резкости (0 до 100). sharp=10
Размытие blur Размытие по Гауссу (0 до 100). blur=15
Пикселизация pixel Эффект пикселизации (0 до 1000). pixel=10
Фильтр filt Применяет фильтр: greyscale или sepia. filt=greyscale

Фон и рамка

Параметр Ключ Описание Пример
Фон bg Цвет фона. Формат: RRGGBB. bg=CCCCCC
Рамка border Добавляет рамку. Формат: ширина,цвет,тип. Тип: overlay или shrink. border=5,000000,overlay

Водяные знаки

Параметр Ключ Описание Пример
Путь mark (Обязательный) Имя файла водяного знака. mark=logo.png
Ширина markw Ширина водяного знака (в px или %). markw=15w
Высота markh Высота водяного знака (в px или %). markh=50
Отступ X markx Отступ по горизонтали (отрицательные значения - от правого края). markx=-20
Отступ Y marky Отступ по вертикали (отрицательные значения - от нижнего края). marky=-20
Отступы markpad Отступы со всех сторон. markpad=10
Позиция markpos Позиция: top-left, center, bottom-right и т.д. markpos=top-left
Прозрачность markalpha Прозрачность водяного знака (0-100). markalpha=50

Выходной формат

Параметр Ключ Описание Значения Пример
Формат fm Формат итогового изображения. jpg, png, gif, webp, avif fm=webp
Качество q Качество для jpg, webp, avif. 0 до 100 q=80

Развернутые примеры вызова

Пример 1: Наложение водяного знака (стандартный вызов MODX)

Задача: Наложить logo.png в правый нижний угол с отступом и полупрозрачностью.

HTML 

<img src="[[!Thumb3x?
    &input=`portfolio/image-01.jpg`
    &watermark=`assets/watermark/logo.png`
    &options=`w=1200&mark=logo.png&markpos=bottom-right&markpad=30&markalpha=50`
]]" alt="Портфолио с водяным знаком">

Пример 2: Вызов через Fenom

Задача: Сделать то же самое, используя более читаемый синтаксис Fenom с передачей параметров в виде массива.

Фрагмент кода 

{* Определяем параметры для Glide в виде массива *}
{var $params = [
    'w' => 1200,
    'h' => 800,
    'mark' => 'logo.png',
    'markpos' => 'bottom-right',
    'markpad' => 20,
    'markalpha' => 60
]}

{* Вызываем сниппет *}
<img src="{'!Thumb3x' | snippet : [
    'input' => 'portfolio/image-01.jpg',
    'watermark' => 'assets/images/logo.png',
    'options' => $params
]}" alt="Изображение с водяным знаком">

Пояснение: Главное преимущество Fenom здесь — возможность собрать все параметры обработки в аккуратный массив $params, что делает код шаблона намного чище и удобнее для чтения и редактирования.

Back to top