«Attacher» 🗃️ плагин для Cotonti

Файлы: 🗃️ фото, изображения, документы и архивы zip, загрузить, прикрепить к статье, разместить для скачивания поможет плагин «Attacher» для Cotonti Siena. Плагин «Attacher» — это расширение под Cotonti, 🗃️ с помощью которого можно загружать файлы, прикреплять к страницам статей, сообщениям на форуме, выводить в виде списка для скачивания, галереи изображений, bb — кода, вставлять в визуальный редактор большую или маленькую миниатюру по клику.

«Attacher» — плагин для системы управления контентом сайта Cotonti Siena.
Особенности плагина attacher

Так как за основу плагина attacher был взят attach2 версии 2013 года, хотелось бы выразить благодарность тем кто изначально его создавал — Vladimir Sibirov (Trustmaser) & Cotonti Team.

Code=attacher
Name=Attacher
Category=files-media
Description=Attach files to posts and pages
Version=1.0.1
Date=2019-08-31
Author=Roffun
Copyright=Copyright (c) CmsCot.net, 2018 — TO THIS DAY & ABOVE. All rights reserved.

скачать плагин.

Посмотреть как работает плагин на демо-сайте

Для интерфейса загрузчика используется jQuery File Upload, поэтому библиотека jQuery должна присутствовать. Загрузки подсчитываются и происходят с оригинальным именем файла, а включение опции «по-частям (чанками)» позволяет обойти ограничение на загрузку файла через $_POST в 2 мб.
Мультизагрузка, несложная интеграция в шаблон через функции обратного вызова (callback). Можно включить конвертирование в jpeg при загрузке, настроить обрезку оригинала до определенных размеров.
Создание большой и маленькой миниатюры, с возможностью настройки, пересоздание налету, несколько форм на странице, автоматическое создание кнопок для вставки изображений в редактор, которые подхватывают настройки размера, указанного в админке. В визуальный редактор вставляется только изображение, без необходимости дополнительных контейнеров, ссылок, или классов для подключения галерей. Всё остальное делается налету.
Настраиваемое наложение водяного знака, при изменении watermark, достаточно удалить все копии через админку плагина, и они пересоздадутся с новым водяным знаком.
Преобразование налету изображения в ссылку на себя, или наоборот, вырезание ссылки, создание адаптивного picture из большой миниатюры и маленькой, создание контейнера с возможностью указания классов для стилизации. И это без изменения кода, можно менять в любой момент на уровне настроек.
Специальный bb код для вставки в редактор, независимо от парсера который выбран.

пример работы на codepen

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

Установленная Cotonti Siena актуального релиза (на момент публикации этой статьи — 0.9.19).
Рекомендуется PHP версии 7.1 и выше.
Плагин имеет отдельную базу данных, но при наличии работающих плагина attach2 или модуля file могут наблюдаться конфликты в работе, поэтому перед использованием плагина нужно приостановить работу вышеуказанных расширений.

Установка плагина attacher

Скачать архив, распаковать. Переименовать папку с плагином в attacher. Её нужно разместить в корневой каталог plugins, где все плагины находятся.
Перейти в «Управление сайтом / Расширения / Загрузка изображений и файлов» и установить с помощью интерфейса.
После установки путь к папке для загрузки файлов по умолчанию будет: datas/attacher, нужно создать ее на сервере и выставить права (CHMOD) на запись, 777 или 755. Если будет использоваться другой каталог, то соответственно с ним проделать то же самое.
Остальные настройки по желанию, о них дальше по тексту.

Конфигурация плагина attacher

Конфигурация плагина
Директория для файлов: путь к папке для загрузки файлов
Префикс имен файлов: приставка добавляемая к каждому файлу
Разрешенные типы файлов: типы файлов которые разрешено загружать
Макс. число вложений в каждом сообщении: сколько файлов можно прикрепить
Допустимые MIME-типы в окне выбора файлов: MIME-типы файлов, которые разрешены для загрузки
Загружать файлы чанками по (байт): Режим для обхода ограничения сервера на $_POST в 2 мб
Макс. размер файлов в байтах: ограничение на размер одного файла
Общее дисковое пространство на каждого пользователя: ограничение на совокупный размер файлов
Начинать закачку автоматически: если включено, то кнопки «начать» и «отменить» скрываются, закачка происходит автоматически
Последовательная загрузка вместо параллельной: выбор варианта загрузки файлов, поочередно или параллельно
Подключить CSS модуля/плагина: стили плагина для вывода в видимой части
Настройка загрузки изображений

Настройка загрузки изображений
Уменьшать загруженные изображения: Если включено, изображения будут уменьшены в соответствии с настройками ниже
Уменьшать ширину изображения до: Ширина до которой уменьшить
Уменьшать высоту изображения до: Высота до которой уменьшить
Конвертировать все изображения в JPG при закачке: Если включено, все загружаемые изображения будут преобразовываться в формат jpeg
Качество JPEG в %: Степень сжатия изображений формата jpeg
Настройка создания копий (миниатюр)

Настройка создания миниатюр
Показывать миниатюры изображений?: если включено, то показываются
Увеличивать изображения, которые меньше размеров миниатюры: если изображение меньше чем размер для миниатюр, то при включении опции, они будут увеличиваться до указанного минимума
Ширина миниатюры по умолчанию: ширина меньшей копии изображения
Высота миниатюры по умолчанию: высота меньшей копии изображения
Режим кадрирования миниатюры по умолчанию: как обрезать меньшую копию
Ширина большой миниатюры: ширина большой копии изображения
Высота большой миниатюры: высота большой копии изображения
Метод обрезки большой миниатюры: как обрезать большую копию
Настройка наложения водяного знака и фоновой текстуры

Настройка наложения водяного знака и фоновой текстуры
Водяной знак для миниатюр: путь к файлу водяного знака
Водяной знак. Мин. ширина: минимальная ширина, при которой водяной знак будет наложен
Водяной знак. Мин. высота: минимальная высота, при которой водяной знак будет наложен
Путь к файлу фоновой текстуры: путь к изображению (текстуре)
Размер отступа для заполнения текстурой: указанный размер будет отступом по бокам изображения, который заполнится изображением — текстурой
Настройка обработки «налету» в статьях

Настройка обработки изображений в статьях налету
Как выводить изображения в статьях: вариант обработки изображений
Создать title для ссылок из содержимого alt: если включено, и выбран режим ссылкой в настройках выше, то для ссылок создастся title из alt
Вырезать атрибут style у изображений: это удаляет атрибут style у изображений, полезно для выравнивания по центру всех картинок, которые раньше были влево или вправо
Преобразовать все изображения в адаптивный PICTURE: создается адаптивный контейнер <picture>, в котором на больших экранах показывается большая миниатюра, а на мобильных — маленькая
Создать контейнер (span): создает родительский контейнер
Имена классов для <span>: контейнеру можно указать имена классов через пробел
Интеграция плагина attacher в шаблон (тему) Cotonti

Для того чтобы иметь возможность загружать, прикреплять, выводить файлы с помощью аттачера, нужно добавить в шаблон функции обратного вызова — подключить интерфейс для взаимодействия. По умолчанию интерфейс можно подключить к страницам и сообщениям форума (модули page и forums). Также можно установить дополнительный плагин attacherfreelance, который подключает API аттачера для модулей фриланс биржи.

Есть несколько функций, которые для этого предназначены, о них и пойдет речь дальше, с примерами кода для вставки в шаблон.

Добавление элемента загрузки файла на форму создания/редактирования объекта

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

При добавлении страницы ее ID еще не существует, поэтому второй параметр указывается равным 0.
В шаблон 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:

<!-- 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 -->

или можно так:

<!-- 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.enum.tpl:

<!-- IF {РAGE_ROW_ID|att_count('page',$this,'','images')} > 0 -->
<div>
<a href="{PAGE_ROW_URL}" title="{PAGE_ROW_SHORTTITLE}">
    <img src="{PAGE_ROW_ID|att_get('page',$this,'')|att_thumb($this,200,160,'crop')}" alt="{PAGE_ROW_SHORTTITLE}">
<a>
</div>
<!-- ENDIF -->

или можно так:

<!-- IF {PAGE_ROW_ID|att_count('page',$this,'','images')} > 0 -->
<div>
<a href="{PAGE_ROW_URL}" title="{PAGE_ROW_SHORTTITLE}">
    {PAGE_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

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

 

В шаблон page.edit.tpl:

Это добавит iframe с загрузчиком файлов для существующего объекта:

<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
{PAGEEDIT_FORM_ID|att_widget('page', $this)}
</div>
<!-- ENDIF -->

А это добавит ссылку на всплывающий виджет в iframe:

<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
{PAGEADD_FORM_ID|att_widget('page', $this, '','attacher.link')}
</div>
<!-- ENDIF -->

В шаблон page.edit.tpl:

Это добавит iframe с загрузчиком файлов для существующего объекта:

<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
{PAGEEDIT_FORM_ID|att_widget('page', $this)}
</div>
<!-- ENDIF -->

А это добавит ссылку на всплывающий виджет в iframe:

<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<div>
{PAGEADD_FORM_ID|att_widget('page', $this, '','attacher.link')}
</div>
<!-- ENDIF -->

 

В шаблон page.tpl:

<!-- IF {PHP|cot_auth('plug', 'attacher', 'W')} -->
<li>{PAGE_ID|att_widget('page',$this,'','attacher.link')}</li>
<!-- 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 -->

Это добавит ссылку на всплывающий виджет в iframe на странице поста. А для вывода списка файлов нужно разместить нижеприведенный код в любом месте блока FORUMS_POSTS_ROW:

<!-- IF {FORUMS_POSTS_ROW_USERID} == {PHP.usr.id} -->
{FORUMS_POSTS_ROW_ID|att_display('forums',$this)}
<!-- ENDIF -->

BB-коды для встраивания в контент

Для того чтобы вывести изображение внутри текста, добавленного через визуальный редактор, например статья, используется единый бб код [att_image?] c параметрами, передаваемыми после вопросительного знака, например:

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

id — ID изображения
width — ширина
height — высота
frame — метод обрезки
alt — альтернативный текст
class — css класс

Обязательным является id, остальные на усмотрение. Их можно передавать все или частично, через знак &. Если в настройках указано преобразование в picture, то это правило сработает и на изображения добавленные через bb код.
Описание функций обратного вызова (callback)

Прикрепление файлов не ограничивается только модулем страниц и стандартными шаблонами. Можно самостоятельно настроить прикрепление файлов, соответствующие им шаблоны и к другим объектам системы, в том числе к пока не существующим. Для этого нужно сразу после сохранения объекта и до любого редиректа вызвать соответствующую функцию:

Функция регистрации нового объекта

function att_fixNewPath($area, $item);

$area — тип объекта или имя модуля. Например: page.
$item — id объекта. К примеру, это ID страницы, ID поста на форуме или ID комментария.

Эта функция по умолчанию работает для модулей forums, page. Для остальных расширений нужно самостоятельно добавить функцию. Вот как это реализовано для page в файле attacher.page.add.add.done.php:

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

Функция удаления всех прикрепленных файлов

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

$user_id — файлы определенного пользователя.
$area — тип объекта или имя модуля.
$item_id — id удаляемого объекта.

Эта функция удаляет все прикрепленные к объекту файлы, если указан $user_id, то удаляются файлы прикрепленные конкретным пользователем. Вот как это реализовано для page в файле attacher.page.delete.php:

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

Две вышеописанные функции предназначены для интеграции возможности взаимодействия API плагина attacher c другими расширениями, а дальше будут описаны функции применяемые в шаблоне.

Функция создания загрузчика

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

Выводит форму загрузки файлов, если это объект без id, то второй параметр нужно указывать как 0, в остальных случаях применяется $this, получающий значение из подключенного тега. Принимает следующие параметры:

$area — тип объекта или имя модуля. Например: page.
$item — id объекта. К примеру, это ID страницы, ID поста на форуме или ID комментария. CoTemplate «$this» позволяет передать в этот параметр значение тега.
$field — имя поля. Для создания нескольких форм можно использовать, по умолчанию является пустым.
$type — тип загружаемых файлов. ‘all’ — все файлы или ‘file’ или ‘image’.
$limit — Ограничение на количество загружаемых файлов. Если указан -1 — то будут использованы ограничения, действующие для группы, которой принадлежит пользователь. 0 — неограниченно.
$tpl — шаблон элемента загрузки файлов.

Функция вызова виджета загрузки в iframe

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

Эта функция используется для создания виждета прикрепления файлов, в зависимости от параметра $tpl выводит виджет загрузчика во всплывающем окне, или же ссылку на всплывающий по клику.

$area — определяет тип содержимого к которому прикрепляются файлы или код модуля / плагина, например ‘page’, ‘forums’, ‘comments’, и т.д.
$item — ID объекта, к которому прикрепляются файлы.
$field — имя поля. Можно оставить пустым. Позволяет к одному объекту прирепить несколько групп файлов.
$tpl — Код шаблона, содержащего html код виджета. «attacher.widget» вставляет диалог в iframe, а «attacher.link» (см.далее) добавляет ссылку на всплывающий диалог с загрузчиком.
$width — Ширина iframe.
$height — Высота iframe.

Функция вывода загруженных файлов

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

Эта функция используется для отображения изображений, уже прикрепленных к объекту. Может отображать их все вместе, или только определенный тип файлов.

$area — определяет из какого объекта выводить — код модуля / плагина.
$item — ID объекта, файлы которого выводятся.
$field — имя поля выводимого объекта (если для загрузчика указывали).
$tpl — код шаблона для отображения, «attacher.display», «attacher.display.thumb».
$type — тип выводимых файлов. ‘all’ — все файлы или ‘file’ или ‘image’.
$limit — количество выводимых объектов, 0 — все.
$order — сортировка, если не указан, то будет по умолчанию ASC.

Функция вывода галереи изображений

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

Эта функция используется для отображения файлов, уже прикрепленных к объекту.

$area — определяет из какого объекта выводить — код модуля / плагина.
$item — ID объекта, файлы которого выводятся.
$field — имя поля выводимого объекта (если для загрузчика указывали).
$tpl — код шаблона для отображения, «attacher.gallery».
$limit — количество выводимых объектов, 0 — все.
$order — сортировка, если не указан, то будет по умолчанию ASC.

Плагин attacher выдает сами файлы для галереи, ничего не зная о js скриптах, которые будут подключены. Такой подход делает возможным подключение разных библиотек, не привязываясь к директории аттачера или скриптам по умолчанию. Таким образом работает плагин highslide, который берет параметры изображений галереи, и выводит в своём tpl файле, подключая нужные скрипты.

Функция подсчета количества вложений

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

$area — определяет из какого объекта выводить — код модуля / плагина.
$item — ID объекта, файлы которого выводятся.
$field — имя поля выводимого объекта (если для загрузчика указывали).
$type — тип выводимых файлов. ‘all’ — все файлы или ‘file’ или ‘image’.

Параметр $field может принимать значение ‘_all_’. В этом случае функция вернет общее количество файлов, прикрепленных к объекту (ко всем «полям»).
Функция вывода списка файлов для скачивания

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

Выводит отдельным блоком файлы доступные для скачивания.

$area — определяет из какого объекта выводить — код модуля / плагина.
$item — ID объекта, файлы которого выводятся для скачивания.
$field — имя поля выводимого объекта (если для загрузчика указывали).
$tpl — код шаблона для отображения, «attacher.downloads».
$limit — количество выводимых объектов, 0 — все.
$order — сортировка, если не указан, то будет по умолчанию ASC.

Функция создания копии изображения

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

Эта функция генерирует копию изображения и возвращает её url.

$id — id файла.
$width — ширина генерируемого изображения.
$height — высота генерируемого изображения.
$frame — режим кадрирования. Может принимать следующие значения:
— ‘width’ заполняет миниатюру по ширине и сохраняет соотношение сторон.
— ‘height’ заполняет миниатюру по высоте и сохраняет соотношение сторон.
— ‘auto’ (по-умолчанию) сохраняет соотношение сторон уменьшая изображение таком образом, чтобы его размеры не превысили заданных.
— ‘crop’ уменьшает изображение сохраняя соотношение сторон и обрезает изображение так, чтобы оно полностью заполнило указанные размеры.
$watermark — наложение водяного знака.

Функция получения данных элемента

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

Это не все функции плагина, их намного больше, но для интеграции более чем достаточно. Если нужно удалить все копии изображений это можно сделать в панели управления аттачера (Администрирование), там же можно и по клику удалить не прикрепленные изображения, если такие найдутся плагином.

Если вам была полезна эта информация, будьте добры, поделитесь ею в социальных сетях. Это послужит дополнительным мотиватором, стимулом к дальнейшим публикациям на сайте автора — cmscot.net статей на интересующие вас темы.

Вопросы, заметки и свои замечания можно оставить в форме комментариев ниже.