Онлайн-руководство разработчика NetCat
Модуль «Поиск по сайту» 12.2.1Начало работы с модулем 12.2.2Язык запросов 12.2.3Способы хранения индекса 12.2.4Интерфейс модуля в панели управления сайтом 12.2.5Области индексирования 12.2.6Области HTML-страниц 12.2.7Области поиска на сайте 12.2.8Индексирование по расписанию, запуск индексирования в фоновом режиме 12.2.9Правила индексирования 12.2.10Постановка задачи переиндексирования в очередь 12.2.11Интеграция модуля в макеты дизайна сайта 12.2.12Простая форма поиска 12.2.13Расширенная форма поиска 12.2.14Вывод результатов поиска 12.2.15Стилизация списка подсказок 12.2.16Расширенные настройки 12.2.17Разработка расширений модуля 12.2.18Обзор архитектуры модуля 12.2.19Обработчики документов различных типов 12.2.20Текстовые фильтры 12.2.21Анализаторы текста 12.2.22Корректировщики запросов 12.2.23Подключение других поисковых систем 12.2.24Решение проблем с поиском 12.2.25Решение проблем с индексированием 12.2.26Справочник API

Автоматическая обработка изображений

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

Возможности:

  • изменение размера изображения;
  • обрезка изображения;
  • создание версий изображения для экранов с высокой плотностью пикселей (масштабирование изображения);
  • наложение водяного знака (watermark).
 

Данный функционал охватывает следующие типы полей:

  • поля «Файл» и «Множественная загрузка» компонентов;
  • поля «Файл» системных таблиц;
  • поля типа «Файл» пользовательских настроек инфоблоков и макетов дизайна.

Как это работает

Начиная с версии Netcat 5.9.0.18237 через переменную, которая содержит путь к картинке для определённого поля (например: $f_Image), можно задавать преобразования (примеры приведены ниже).

При выводе (при приведении к строке) переменной с преобразованиями будет сгенерирован путь к новому изображению, на основе оригинального изображения, сохранённого в соответствующем поле. При запросе по данному пути при первом запросе система создаст копию изображения и применит все указанные преобразования; полученное изображение будет сохранено по тому же сгенерированному пути, поэтому последующие запросы будут обрабатываться веб-сервером без участия скриптов.

Все сгенерированные на основе оригинала изображения хранятся в папке /netcat_files/generated/.

При изменении картинки, или при удалении поля, или объекта, или раздела и т. д., старые сгенерированные картинки для соответствующих полей будут удалены, тем самым всегда будут выводиться самые актуальные обработанные изображения, а старые сгенерированные изображения не будут лежать «мёртвым грузом». Также предусмотрена функция ручного удаления сгенерированных изображений.

Примеры использования для разных типов полей

Внимание! Перед использованием данного функционала необходима проверка на наличие данных в соответствующей переменной, иначе вызов метода приведёт к поломке сборки страницы. Актуально для всех полей, кроме «Множественная загрузка файлов».

Поле с названием “Image” типа “Файл” в компоненте
<? if ($f_Image) { ?>
    <img src="<?= $f_Image->resize(500, 500); ?>">
<? } ?>
Поле с названием “Images” типа “Множественная загрузка” в компоненте
<? foreach ($f_Images->to_array() as $image) { ?>
    <img src="<?= $image->resize(500, 500); ?>">
<? } ?>
Поле с названием “Image” типа “Файл” в пользовательских настройках инфоблока
<? if ($cc_settings['Image']) { ?>
    <img src="<?= $cc_settings['Image']->resize(500, 500); ?>">
<? } ?>
Поле с названием “Image” типа “Файл” в пользовательских настройках макета дизайна
<? if ($template_settings['Image']) { ?>
    <img src="<?= $template_settings['Image']->resize(500, 500); ?>">
<? } ?>
Поле с названием “Image” типа “Файл” в системной таблице “Сайт”
<? if ($current_catalogue['Image']) { ?>
    <img src="<?= $current_catalogue['Image']->resize(500, 500); ?>">
<? } ?>
Поле с названием “Image” типа “Файл” в системной таблице “Раздел”
<? if ($current_sub['Image']) { ?>
    <img src="<?= $current_sub['Image']->resize(500, 500); ?>">
<? } ?>
Поле с названием “Image” типа “Файл” в системной таблице “Пользователь”
<? if ($current_user['Image']) { ?>
    <img src="<?= $current_user['Image']->resize(500, 500); ?>">
<? } ?>

Описание доступных методов-модификаторов изображения

resize($width, $height, $type)

Изменение размера изображения.

Параметр Описание
$width Ширина конечного изображения.
$height Высота конечного изображения.
$type Способ изменения размеров изображения.
 

Доступные способы:
nc_ImageTransform::RESIZE_TO_BEST_FIT — пропорционально уменьшает изображение.
nc_ImageTransform::RESIZE_TO_BEST_FIT_WITH_CROP — вписывает в указанные размеры по наиболее подходящей стороне, обрезая края.
nc_ImageTransform::RESIZE_TO_WIDTH_WITH_CROP — вписывает в указанные размеры по ширине, обрезая края.
nc_ImageTransform::RESIZE_TO_HEIGHT_WITH_CROP — вписывает в указанные размеры по высоте, обрезая края.

Значение по умолчанию:
nc_ImageTransform::RESIZE_TO_BEST_FIT_WITH_CROP

crop($width, $height, $x, $y)

Обрезка изображения.

Параметр Описание
$width Ширина конечного изображения.
$height Высота конечного изображения.
$x Координата по оси X левого верхнего угла, от которого будет происходить обрезка.
$y Координата по оси Y левого верхнего угла, от которого будет происходить обрезка.
watermark($http_path, $mode)

Наложение водяного знака на изображение.

Параметр Описание
$http_path HTTP-путь (от корневой папки сайта) до файла водяного знака.

Пример:
watermark('netcat_files/watermark.png');
$mode

Режим наложения водяного знака.

Доступные режимы:
nc_ImageTransform::WATERMARK_POSITION_CENTER — наложение по центру.
nc_ImageTransform::WATERMARK_POSITION_TOP_LEFT — наложение в левый верхний угол.
nc_ImageTransform::WATERMARK_POSITION_TOP_RIGHT — наложение в правый верхний угол.
nc_ImageTransform::WATERMARK_POSITION_BOTTOM_LEFT — наложение в левый нижний угол.
nc_ImageTransform::WATERMARK_POSITION_BOTTOM_RIGHT — наложение в правый нижний угол.

Значение по умолчанию:
nc_ImageTransform::WATERMARK_POSITION_CENTER

scale($factor)

Получение пути к масштабированной копии изображения.

Параметр Описание
$factor

Фактор масштабирования исходного изображения.

Пример:
scale(1.5);

При использовании метода as_img() к тегу <img> автоматически добавляется атрибут srcset с путями к вариантам изображения с масштабами 1.5x, 2x, 3x и 4x. Это позволяет автоматически отображать на устройствах с дисплеем с высокой плотностью пикселей чёткую копию изображения.

Например, если картинка уменьшена до 100×100 точек, будут доступны варианты изображения с размерами 100×100 (например, для 21,5″ монитора с разрешением 1920×1080 и плотностью пикселей 102 ppi), 150×150 (например, для планшета Surface 3 с 204 ppi), 200×200 (например, для MacBook Pro 15 с 221 ppi), 300×300 (например, для Samsung Galaxy S5 с 432 ppi) и 400×400 (например, для Samsung Galaxy S6 с 576 ppi), из которых веб-браузером, в зависимости от возможностей устройства и соединения, будет выбрано наиболее подходящее.

Метод scale может понадобиться, если путь к масштабированному изображению нужен для каких-либо других целей — например, для формирования тега <picture> или CSS:

<?php
if ($f_Image) {
    $resized_image = $f_Image->resize(320, 240);

    $style = "
        width: 320px;
        height: 240px;
        background-repeat: no-repeat;
        background-image: url('{$resized_image}');
        background-image: -webkit-image-set(
            url('{$resized_image}') 1x,
            url('{$resized_image->scale(2)}') 2x
        );
    ";

    echo '<div style="' . $style . '"></div>
}

Дополнительные методы

as_img($attributes)

Выводит тег <img> для изображения.

Параметр Описание
$attributes

Массив с атрибутами тега <img>.
Параметр не обязателен.

 

Примеры использования методов

1. Простой вывод изображения из поля
<img src="<?= $f_Image; ?>">

2. Проверка на наличие данных
<? if ($f_Image) { ?>
   <img src="<?= $f_Image; ?>">
<? } ?>

3. Вывод сразу с тегом "img"
<? if ($f_Image) { ?>
   <?= $f_Image->as_img(); ?>
<? } ?>

4. Изменение размера изображения
<? if ($f_Image) { ?>
   <?= $f_Image->resize(100, 100)->as_img(); ?>
   <?= $f_Image->resize(100, 100, nc_ImageTransform::RESIZE_TO_HEIGHT_WITH_CROP)->as_img(); ?>
<? } ?>

5. Обрезка изображения
<? if ($f_Image) { ?>
   <?= $f_Image
           ->crop(50, 50, 20, 20)
           ->as_img(array(
               'title' => 'Обрезка квадрата 50×50 px с отступом от левого верхнего угла по 20 px'
           )); ?>
<? } ?>

6. Наложение водяного знака
<? if ($current_user['Avatar']) { ?>
   <?= $current_user['Avatar']->watermark('netcat_files/wm.png')->as_img(); ?>
<? } ?>

7. Копия изображения для экрана с высокой плотностью пикселей
<? if ($template_settings['HeaderImage']) { ?>
   <?= $template_settings['HeaderImage']->resize(100, 100)->scale(2); ?>
<? } ?>

8. Комбинирование параметров
<? if ($f_Image) { ?>
    <?= $f_Image->crop(300, 300)->resize(50, 50)->watermark('img.jpg')
                ->as_img(array('id' => 'some_id')); ?>
<? } ?>

Важно! Порядок выполнения обработки не зависит от порядка вызова методов, и заранее предопределён: сначала происходит изменение размера изображения, затем обрезка, затем наложение водяного знака. Если преобразование не задано методом — оно не выполняется.

Ручное удаление созданных изображений

Если есть необходимость ручного удаления сгенерированных изображений — можно воспользоваться методом

nc_image_generator::remove_generated_images($entity = null, $field = null, $object = null, $file = null)
Параметр Описание
$entity

Сущность, для которой необходимо удалить обработанные копии изображений.

Возможные значения:

  • Значение не указано (или null): Если значение не указано — происходит удаление всех сгенерированных изображений для всех типов сущностей (компоненты, системные таблицы, пользовательские настройки). Остальные параметры метода не используются.
  • Число (например: 150): Трактуется как ID компонента. Будут удалены все сгенерированные изображения для всех полей с файлами для указанного компонента.
  • 'catalogue': Будут удалены все сгенерированные изображения для всех полей с файлами для всех сайтов.
  • 'subdivision': Будут удалены все сгенерированные изображения для файловых полей всех разделов.
  • 'user': Будут удалены все сгенерированные изображения для всех полей с файлами для всех пользователей.
  • 'template': Будут удалены все сгенерированные изображения для всех полей с файлами для всех макетов дизайна.
  • 'class_settings': Будут удалены все сгенерированные изображения для всех полей с файлами для пользовательских настроек инфоблоков.
  • 'template_settings': Будут удалены все сгенерированные изображения для всех полей с файлами для пользовательских настроек макетов дизайна.
$field

Поле в указанной сущности (компонент, системная таблица, пользовательские настройки).
В случае компонентов или системных таблиц — необходимо указывать имя или ID поля (например: 'Image', 514).
Для остальных случаев — название поля (например: ‘Image’).
Если значение не указано — произойдёт удаление всех картинок для указанной сущности.

$object

ID объекта.
Например, ID объекта в компоненте, системной таблице, ID инфоблока, и т. д.
Если значение не указано — будет произведено удаление всех картинок из заданного поля для всех объектов указанной сущности.

$file

ID файла в поле «Множественная загрузка» (только для полей «Множественная загрузка» компонентов).
Если значение не указано — будет произведено удаление всех картинок заданного поля заданного объекта в заданной сущности.

 

Примеры использования

// Удаление всех изображений.
nc_image_generator::remove_generated_images();

// Удаление изображений компонента с ID 169.
nc_image_generator::remove_generated_images(169);

// Удаление всех изображений поля Image пользовательских настроек инфоблоков.
nc_image_generator::remove_generated_images('class_settings', 'Image');

// Удаление сгенерированных изображений из системной таблицы пользователя
// для пользователя с ID 3, из поля с ID 190.
nc_image_generator::remove_generated_images('user', 190, 3);

// Удаление сгенерированных изображений компонента с ID 344,
// из поля "Множественная загрузка" с ID 759,
// для объекта с ID 12, только для третьего изображения в поле.
nc_image_generator::remove_generated_images(344, 759, 12, 3);

Дополнительная информация

  • Теперь функция nc_image_edit_inline() не нужна, в режиме редактирования форма визуального изменения файлового поля в компоненте автоматически генерируется для авторизованных пользователей, имеющих нужные права.
  • Изменённые копии изображения генерируются при первом обращении к ним через веб-сервер. Если путь до изображения не будет вставлен в тег <img> (не будет использован метод as_img(), и результат выполнения не помещён в тег), то изображения не будут сгенерированы системой и помещены в папку для сгенерированных изображений.
  • Пути, при запросе к которым генерируются изображения, включают в себя хэш, который предотвращает создание несанкционированных копий изображения с произвольными параметрами (что позволяет защититься, например, от атаки злоумышленника, направленной на исчерпание свободного пространства на сервере, или попытки получения исходной копии изображения без водяного знака).
  • Все файлы, кроме изображений, а также файлы формата svg и bmp отдаются без изменений.
Описание проекта