Плагин Attacher for CMF Cotonti Siena 0.9.26+, PHP 8.4+

Attacher — мощное и универсальное расширение для Cotonti CMF (версия 0.9.26+, PHP 8.4+), разработанное для управления загрузкой, обработкой и отображением файлов и изображений. Плагин позволяет прикреплять файлы к различным объектам системы, таким как статьи, посты форума, карточки товаров или пользовательские модули, и предоставляет гибкие инструменты для работы с медиафайлами. Поддерживает асинхронную загрузку, обработку изображений, интеграцию с визуальными редакторами и отображение в виде галерей или списков для скачивания.

Help & Support

Основные возможности

1. Гибкая загрузка файлов:
   • Множественные способы загрузки: Поддержка загрузки через выбор файлов, drag-and-drop или по URL. Возможность загружать изображения напрямую с других сайтов, указав их URL, что особенно удобно при создании или редактировании статей, карточек товаров, постов форума и других объектов.
   • Мультизагрузка: Одновременная загрузка нескольких файлов с настраиваемыми ограничениями по количеству.
   • Чанки: Загрузка файлов частями (чанками) для обхода серверных ограничений $_POST (по умолчанию 2 МБ).
   • Проверка файлов: Фильтрация по расширениям (например, jpg, png, gif, webp, pdf) и MIME-типам.
   • Поддерживаемые форматы: Изображения, аудио, видео, архивы, документы.
2. Управление вложениями:
   • Привязка к объектам: Возможность прикреплять файлы к любым объектам Cotonti (страницы, посты, товары, комментарии) с указанием модуля, объекта и поля.
   • Редактирование заголовков: Пользователи могут задавать заголовки для каждого файла через интерфейс.
   • Замена файлов: Поддержка замены существующих файлов новыми без удаления привязки.
   • Сортировка: Переупорядочивание вложений с помощью drag-and-drop.
   • Статистика: Подсчёт количества загрузок и сохранение оригинальных имён файлов.
3. Обработка изображений:
   • Миниатюры: Автоматическое создание маленьких и больших миниатюр с настраиваемыми размерами и режимами кадрирования (crop, width, height, auto).
   • Конвертация в JPEG: Опциональное преобразование всех загружаемых изображений в JPEG с настройкой качества сжатия.
   • Водяные знаки и текстуры: Наложение водяных знаков и фоновых текстур с возможностью пересоздания копий при изменении настроек.
   • Адаптивный вывод: Преобразование изображений в тег <picture> для адаптивного отображения (большая миниатюра для десктопов, маленькая для мобильных).
   • Обработка "налету": Удаление атрибута style, преобразование изображений в ссылки или создание контейнеров <span> с настраиваемыми классами.
   • BB-код: Поддержка [att_image?...]err для встраивания изображений в текст с параметрами размера, кадрирования и классов.
4. Интеграция с формами и редакторами:
   • Виджет загрузки: Интерактивный виджет (att_filebox) для форм создания/редактирования объектов, таких как статьи, карточки товаров, посты форума.
   • Загрузка по URL: Прямая загрузка изображений с внешних сайтов через поле ввода URL, упрощающая добавление медиа без скачивания на устройство.
   • Предпросмотр: Отображение предварительного просмотра изображений перед загрузкой.
   • Вставка в редактор: Автоматическое создание кнопок для вставки изображений в визуальный редактор с учётом настроек размера.
   • Галереи и списки: Вывод файлов в виде галерей (att_gallery), списков для скачивания (att_downloads) или общего списка (att_display).
5. Безопасность и ограничения:
   • Проверка прав: Ограничение доступа к загрузке, редактированию и удалению файлов на основе прав пользователя.
   • Лимиты: Настраиваемые ограничения на размер одного файла, общее дисковое пространство и количество вложений.
   • Очистка: Автоматическое удаление временных файлов (garbage collection) для несохранённых форм.
   • Токен безопасности: Использование токена x для защиты операций загрузки и удаления.
6. Гибкость и кастомизация:
   • Шаблоны: Настраиваемые шаблоны для интерфейса загрузки и отображения файлов.
   • Конфигурация: Подробные настройки через админ-панель для управления типами файлов, размерами, качеством и стилями.
   • Локализация: Поддержка многоязычности через языковые файлы (attacher.<lang>.lang.php).
   • Совместимость с галереями: Интеграция с внешними библиотеками галерей (например, Highslide) через настраиваемые шаблоны.

Системные требования

• Cotonti: Siena 0.9.26+ (рекомендуется последняя версия).
• PHP: 8.4+
• Библиотеки:
  • jQuery и jQuery UI для интерфейса.
  • jQuery File Upload для асинхронной загрузки файлов.
  • JavaScript Load Image для обработки изображений и загрузки по URL.
  • JavaScript Templates для динамического рендеринга шаблонов.
  • Canvas-to-Blob для преобразования изображений.
  • TableDnD для сортировки вложений через drag-and-drop.
• Браузеры: Современные браузеры (Chrome, Firefox, Safari, Edge). Ограниченная поддержка IE8+ через iframe-транспорт.
• Конфликты: Плагин несовместим с attach2 и модулем file — их необходимо отключить.
• База данных: Плагин использует отдельную таблицу для хранения информации о файлах.
•  

Установка

1. Скачайте (бесплатно) архив плагина репозитория на GitHub и распакуйте его.
2. Переименуйте папку в attacher и поместите её в директорию plugins вашего сайта.
3. Перейдите в админ-панель Cotonti: Управление сайтом → Расширения → Загрузка изображений и файлов и установите плагин.
4. Создайте папку для загрузки файлов (по умолчанию datas/attacher) и установите права CHMOD 755 или 777. Если используется другой каталог, настройте его в конфигурации.
5. Настройте параметры плагина в админ-панели: Управление сайтом → Конфигурация → Плагины → Attacher.
6.  

Конфигурация

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

• Директория для файлов: Путь к папке загрузки (по умолчанию datas/attacher).
• Префикс имён файлов: Приставка для имён файлов (например, att_).
• Разрешённые типы файлов: Список расширений (например, jpg,png,gif,pdf,zip,mp3,mp4).
• Макс. число вложений: Ограничение на количество файлов в одном объекте (например, 5, 10 или неограниченно).
• Допустимые MIME-типы: MIME-типы для фильтрации в окне выбора файлов (например, image/*,application/pdf).
• Загрузка чанками: Размер чанка в байтах (например, 1 МБ) для обхода ограничений $_POST.
• Макс. размер файла: Ограничение на размер одного файла в байтах (например, 10485760 для 10 МБ).
• Общее дисковое пространство: Лимит хранилища для пользователя в байтах (например, 104857600 для 100 МБ).
• Автоматическая загрузка: Включение/выключение автоматической загрузки после выбора файлов (скрывает кнопки "Начать" и "Отменить").
• Последовательная загрузка: Выбор между последовательной и параллельной загрузкой файлов.
• Подключение CSS: Включение стилей плагина (fileupload.css и jQuery UI).

Настройка изображений

• Уменьшение изображений: Включение масштабирования загружаемых изображений.
• Ширина/высота уменьшения: Максимальные размеры изображения (например, 1920x1080).
• Конвертация в JPEG: Автоматическое преобразование всех изображений в JPEG.
• Качество JPEG: Степень сжатия в процентах (например, 80%).

Настройка миниатюр

• Показывать миниатюры: Включение/выключение отображения миниатюр в интерфейсе.
• Увеличение маленьких изображений: Увеличение изображений, меньших заданных размеров миниатюр.
• Ширина/высота миниатюр: Размеры маленькой (например, 200x160) и большой (например, 800x600) миниатюр.
• Режим кадрирования: crop (обрезка), width (по ширине), height (по высоте), auto (сохранение пропорций).

Водяные знаки и текстуры

• Водяной знак: Путь к файлу водяного знака (например, datas/attacher/watermark.png).
• Мин. ширина/высота: Минимальные размеры изображения для наложения водяного знака (например, 300x200).
• Фоновая текстура: Путь к файлу текстуры (например, datas/attacher/texture.jpg).
• Отступ для текстуры: Размер отступа вокруг изображения для заполнения текстурой (например, 10 пикселей).

Обработка изображений в статьях

• Режим вывода: Варианты отображения изображений (как ссылка, <picture>, чистое изображение).
• Title из alt: Создание атрибута title из alt для ссылок.
• Удаление style: Удаление атрибута style для выравнивания изображений.
• Адаптивный <picture>: Использование большой и маленькой миниатюр для разных устройств.
• Контейнер <span>: Создание родительского контейнера с настраиваемыми CSS-классами.

Шаблоны плагина

Плагин использует три основных шаблона для интерфейса и отображения файлов:

1. attacher.filebox.tpl:
   • Назначение: Форма загрузки файлов, интегрируемая в страницы создания/редактирования (например, статьи, карточки товаров).
   • Содержимое:
     • Поле выбора файлов и область drag-and-drop.
     • Поле ввода URL для загрузки изображений с других сайтов (например, https://example.com/image.jpg) с кнопкой "Загрузить по URL".
     • Кнопки управления: "Добавить файл", "Начать загрузку", "Отменить", "Удалить", "Выделить все".
     • Прогресс-бар для отображения процесса загрузки.
     • Таблица для предпросмотра загружаемых файлов с миниатюрами.
   • Конфигурация: Подключает объект attConfig с параметрами загрузки (расширения, MIME-типы, лимиты).
   • Библиотеки: Интегрирует jQuery File Upload, JavaScript Load Image и TableDnD.
2. attacher.files.tpl:
   • Назначение: Полноценная страница управления загрузками, используемая в iframe или отдельном интерфейсе.
   • Содержимое:
     • Форма загрузки с аналогичным интерфейсом: выбор файлов, drag-and-drop, поле URL.
     • Список загруженных файлов с возможностью редактирования заголовков, замены и удаления.
     • Поддержка мультизагрузки и отображения файлов в таблице.
   • Стили и скрипты: Подключает fileupload.css, jQuery UI, jQuery, JavaScript Templates, Canvas-to-Blob и другие библиотеки.
3. attacher.templates.tpl:
   • Назначение: Шаблоны для динамического рендеринга файлов в процессе загрузки/скачивания.
   • Содержимое:
     • Шаблон template-upload: Отображает файлы в процессе загрузки с прогресс-баром, именем файла и кнопками отмены.
     • Шаблон template-download: Показывает загруженные файлы с миниатюрами, заголовками, кнопками удаления/замены и вставки в редактор.
     • Поддержка предварительного просмотра изображений и интеграции с визуальными редакторами.
   • Формат: Использует text/x-tmpl для рендеринга через JavaScript Templates.

Все шаблоны настраиваемы и поддерживают локализацию через языковые переменные ({PHP.L.<key>}).

Интеграция в шаблоны

Добавление загрузчика

Функция att_filebox добавляет форму загрузки в страницы создания/редактирования (например, статьи, карточки товаров):

<!-- В page.add.tpl (для новых страниц) -->
<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
 {PHP|att_filebox('page', 0)}
</div>
<!-- ENDIF -->
<!-- В page.edit.tpl (для существующих страниц) -->
<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
 {PAGEEDIT_FORM_ID|att_filebox('page', $this)}
</div>
<!-- ENDIF -->

Вывод изображений в списках

Для списков страниц (page.list.tpl или page.enum.tpl):

<!-- Простой вывод изображения -->
<!-- IF {LIST_ROW_ID|att_count('page', $this, '', 'images')} > 0 -->
<div>
 <a href="{LIST_ROW_URL}" title="{LIST_ROW_SHORTTITLE}">
 <img src="{LIST_ROW_ID|att_get('page', $this, '')|att_thumb($this, 200, 160, 'crop', false)}" alt="{LIST_ROW_SHORTTITLE}">
 </a>
</div>
<!-- ENDIF -->
<!-- Через att_display -->
<!-- IF {LIST_ROW_ID|att_count('page', $this, '', 'images')} > 0 -->
<div>
 <a href="{LIST_ROW_URL}" title="{LIST_ROW_SHORTTITLE}">
 {LIST_ROW_ID|att_display('page', $this, '', 'attacher.display.thumb', 'images', 1)}
 </a>
</div>
<!-- ENDIF -->

Вывод на странице (page.tpl)

• Все файлы:

  <!-- IF {PAGE_ID|att_count('page', $this)} > 0 -->
  <div data-att-display="all">
   <h3>{PHP.L.att_attachments}</h3>
   {PAGE_ID|att_display('page', $this, '', 'attacher.display', 'all')}
  </div>
  <!-- ENDIF -->

   

Галерея изображений:

<!-- IF {PAGE_ID|att_count('page', $this, '', 'images')} > 0 -->
<div data-att-gallery="yourgallery">
 <h3>{PHP.L.att_gallery}</h3>
 {PAGE_ID|att_gallery('page', $this, '', 'attacher.gallery')}
</div>
<!-- ENDIF -->
<!-- С Highslide (отдельный плагин) -->
<!-- IF {PAGE_ID|att_count('page', $this, '', 'images')} > 0 -->
<div data-att-gallery="highslide" data-att-group="mygroup">
 <h3>{PHP.L.att_gallery}</h3>
 {PAGE_ID|att_gallery('page', $this, '', 'highslide.attacher.gallery')}
</div>
<!-- ENDIF -->

Список файлов для скачивания:

<!-- IF {PAGE_ID|att_count('page', $this, '', 'files')} > 0 -->
<div data-att-downloads="download">
 <h3>{PHP.L.att_downloads}</h3>
 {PAGE_ID|att_downloads('page', $this)}
</div>
<!-- ENDIF -->

Виджет в iframe

Функция att_widget для загрузки через iframe:

<!-- В page.edit.tpl -->
<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
 {PAGEEDIT_FORM_ID|att_widget('page', $this)}
</div>
<!-- ENDIF -->
<!-- Ссылка на всплывающий виджет -->
<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
 {PAGEADD_FORM_ID|att_widget('page', $this, '', 'attacher.link')}
</div>
<!-- ENDIF -->

Прикрепление к постам форума (forums.posts.tpl)

<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} AND {FORUMS_POSTS_ROW_USERID} == {PHP.usr.id} -->
{FORUMS_POSTS_ROW_ID|att_widget('forums', $this, '', 'attacher.link')}
<!-- ENDIF -->
<!-- Вывод файлов -->
<!-- IF {FORUMS_POSTS_ROW_USERID} == {PHP.usr.id} -->
{FORUMS_POSTS_ROW_ID|att_display('forums', $this)}
<!-- ENDIF -->

BB-код для изображений

Используйте BB-код [att_image?...]err для встраивания изображений в текст (например, в статьях или карточках товаров):

[att_image?id=15]err2
[att_image?id=11&width=350]err2
[att_image?id=2&width=350&height=350]err2
[att_image?id=7&width=320&height=240&alt=Image alt]err2
[att_image?id=88&width=320&height=240&alt=Image alt&class=myclass]err2

Параметры:

• id: ID изображения (обязательный).
• width, height: Размеры изображения.
• frame: Режим кадрирования (crop, width, height, auto).
• alt: Альтернативный текст.
• class: CSS-класс для изображения.

Функции API

• Регистрация нового объекта:

  att_fixNewPath($area, $item);

   

Используется для привязки файлов к новому объекту после его создания. Пример для модуля page:

if (cot_auth('plug', 'attacher', 'W')) {
 if ($id) {
 att_fixNewPath('page', $id);
 }
}

Удаление всех вложений:

att_remove_all($user_id = null, $area = null, $item_id = null);

Удаляет все файлы, связанные с объектом или пользователем. Пример для модуля page:

if (cot_auth('plug', 'attacher', 'W')) {
 att_remove_all(null, 'page', $id);
}

Создание загрузчика:

att_filebox($area, $item, $field = '', $type = 'all', $limit = -1, $tpl = 'attacher.filebox');

• Параметры:
  • $area: Модуль/плагин (например, page, forums).
  • $item: ID объекта (или 0 для новых объектов).
  • $field: Имя поля для группировки файлов.
  • $type: Тип файлов (all, image, file).
  • $limit: Ограничение на количество файлов (-1 для групповых настроек, 0 для неограниченного).
  • $tpl: Шаблон (attacher.filebox по умолчанию).

• Вывод виджета в iframe:

  att_widget($area, $item, $field = '', $tpl = 'attacher.widget', $width = '100%', $height = '200');

   

• Создаёт iframe или ссылку на всплывающий загрузчик.

• Вывод файлов:

  att_display($area, $item, $field = '', $tpl = 'attacher.display', $type = 'all', $limit = 0, $order = '');

   

• Выводит все файлы или определённый тип (например, только изображения).

• Вывод галереи:

  att_gallery($area, $item, $field = '', $tpl = 'attacher.gallery', $limit = 0, $order = '');

   

• Создаёт галерею изображений с поддержкой сторонних библиотек (например, Highslide).

• Подсчёт вложений:

  att_count($area, $item, $field = '', $type = 'all');

   

• Возвращает количество файлов, привязанных к объекту. $field = '_all_' возвращает общее количество.

• Вывод списка загрузок:

  att_downloads($area, $item, $field = '', $tpl = 'attacher.downloads', $limit = 0, $order = '');

   

• Формирует список файлов для скачивания.

• Создание миниатюры:

  att_thumb($id, $width = 0, $height = 0, $frame = '', $watermark = true);

   

• Генерирует URL миниатюры с заданными параметрами.

• Получение данных элемента:

  att_get($area, $item, $field = '', $column = '', $number = 'first');

   

• Возвращает данные файла (например, путь, имя, размер).

• Генерация HTML для изображения:

  att_customizable_thumb($m);

   

• Преобразует тег <img> в настраиваемый HTML-сниппет (<span><a><picture><source><img></picture></a></span>).

• Генерация HTML из BB-кода:

  att_customizable_thumb_bbcode($m);

   

  1. Преобразует BB-код [att_image?...]err в HTML с поддержкой адаптивного <picture>.

Управление через админ-панель

• Удаление копий: Удаление всех миниатюр для пересоздания с новыми настройками (например, новым водяным знаком).
• Очистка: Удаление неприкреплённых файлов (garbage collection) через админ-панель.
• Управление файлами: Просмотр, редактирование и удаление загруженных файлов.

Примечания

• Конфликты: Плагин несовместим с attach2 и модулем file. Отключите их перед использованием.
• Галереи: Поддержка сторонних библиотек (например, Highslide) через настраиваемые шаблоны.
• Загрузка по URL: Реализована через JavaScript Load Image, позволяет загружать изображения с внешних сайтов без скачивания на устройство.
• Локализация: Поддерживается через языковые файлы (attacher.<lang>.lang.php).