Главная   /  Документация

CMS.Fields.Types.Gallery: подробнее о галерее

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

Сами изображения и дополнительная информация не сохраняется в БД, всё хранится в файлах.

Общая настройка

Для создания поля типа gallery достаточно указать в настройках соответствующий тип 

// app/components/Nodus/app/Datatype/Articles
...
	public function fields()
	{
        	return array(
			...
			'gallery' => array(
				'caption' => 'Gallery',
				'type' => 'gallery',
				'weight' => -10,
				'admin size' => '100x100',
				'tab' => 'gallery',
				'style' => 'max-height: 400px;overflow-y: auto;width: 90%;',
				'zip' => false,
				'multiple' => true
			),
			...
		);
}

Кроме стандартных настроек можно указать:

  • admin size - размер картинки в режиме администрирования.
  • zip - разрешать или нет закачку zip архива (по умолчанию true).
  • multiple - разрешать или нет выбирать несколько файлов

Большинство других опций будут рассмотрены далее.

Файлы галереи по умолчанию хранятся в docroot/files/{table-name}/0000/0001/{gallery-name}/. Где:

  • table-name - имя таблицы
  • 0001- внутренний id материала
  • gallery-name - имя галереи.

В этом каталоге лежат оригинальные изображения и файлы, хранящие дополнительную информацию:

  • data.serialize - сериализованный массив с подписями и другой информацией.
  • user_mods.json - предопределённые изображения в json формате.

В подкаталогах содержатся преобразованные изображения, по имени каталога можно понять какое преобразование было применено (например, «fit100x100»).

Documents, Attaches

Поле Gallery наследуется от поля Documents, которое, в свою очередь, наследуется от Attaches.

Attaches занимается загрузкой файлов (изображений), Documents добавляет возможность сохранять кроме самого файла дополнительную информацию о файле (описание, дата, ...), а также сортировку. Соответственно настройки для Attaches и Documents также действуют и на Gallery.

Presets

Для галереи, как и для поля image, можно задать набор именованных преобразований presets, а также набор преобразований, которые применяются к оригинальному изображению при закачке upload_mods. Для этого, при описании поля, необходимо добавить опцию presets и описать массив свойств.

Также у контейнера существует метод fullsize(), позволяющий указать преобразования для полноразмерных картинок.

Пример опций: 

'gallery' => array(
	...
	'upload_mods' => 'fit(500,600)',
	'presets' => array(
    		'on_top_page' => array('resize' => array(350, 400), 'grayscale' => array()),
	    	'full_size' => 'fit(200,300)',
	),
),

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

<?=$item->field('gallery')->preset('on_top_page')->fullsize('full_size')->render() ?>

Данная запись отобразит черно-белую галерею в размере 350 х 400 пикселей, при клике по которой показывается изображение размером 200 на 300.

Также при закачке будут сохранены не оригинальные изображения, а сжатые до размера 500 х 600. Это полезно в случае закачки больших фотографий, которые никогда не показываются в полном размере.

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

Usermods

Иногда требуется вместо автоматического преобразования картинок закачать какие-то свои.

Для этого можно применить опцию user_mods. 

'gallery' => array(
	...
	'user_mods' => array(
    		'fit100x100' => 'Картинка для админки',
    		'fit200x200' => 'Картинка для чего-то там'
	),
)

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

К сожалению, в данный момент в качестве ключа в массиве настроек нельзя использовать имя presets.

Контейнер

У поля также имеется контейнер (как и у поля image), содержащий методы для преобразования изображений, которые влияют на все изображения. Действия также кешируются, все измененные картинки сохраняются в отдельном каталоге.

Например, данное выражение выведет галерею с картинками размером 200 x 300 пикселей. 

<?= $item->field('gallery')->fit(200,300)->render() ?>

К подобным методам относятся:

  • fit
  • resize
  • crop
  • margins -
  • grayscale
  • watermark

Контейнер галереи является итератором, соответственно можно применить перебор элементов: 

// вывод списка имен файлов
foreach ($entity->field('gallery') as $item)
	print($item['name'] . '<br>');

Также с помощью метода get можно получить изображение по индексу. Например, вывод изображения с индексом 2 и примененным преобразованием «crop», и, если такое имеется, выведет его, заресайзив в 200 х 200 пикселей (никто не знает зачем кропить а потом ресайзить). 

$gallery_image = $item->field('gallery')->crop('10x10')->get(2);
if ($gallery_image) {
	print $gallery_image->resize('200x200')->render();
}

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

А также есть возможность обращаться к атрибутам:

  • name - имя файла.
  • url - ссылка на файл.
  • path - путь к файлу.
  • orig_path - путь к оригинальному файлу.
  • orig_url - ссылка на оригинальный файл.
  • caption - описание.

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

Кроме обычного итерирования, есть возможность фильтрации: 

print $item->field('gallery')->filter('11.jpg', 'name');
print $item->field('gallery')->filter('tag1,tag2')->filter_regexp('!^123!', 'caption', 'or')->preset('on_top_page')->fullsize('full_size')->render();

В первом случае отобразится картинка с именем 11.jpg, во втором случае - изображения с мнемокодами tag1 или tag2, а также те, у которых описание начинается с 123.

Метод filter имеет следующие параметры:

  • value значение для фильтрации, несколько значений могут быть разделены запятой.
  • field поле по которому происходит фильтрация, по умолчанию mnemocode.
  • combine имя логического оператора для применения нескольких фильтров ( 'or' 'and' ).
  • operation операция сравнения, по умолчанию 'eq' - на равенство, может быть также 'regexp' .
  • delim разделить нескольких значений, по умолчанию ',' .

Для удобства созданы методы filter_eq() и filter_regexp().

Чтобы у галереи появился атрибут mnemocode (который используется по умолчанию в фильтрации) достаточно в настройках указать: 

   ...
   'mnemocode' => true,
   ...

У контейнера есть методы:

  • dir() - директория к содержимому.
  • add() - добавление файла в галерею.
  • remove() - удаление файла из галереи.
  • files_data() - массив атрибутов картинок галереи.
  • filelist() - список файлов.
  • mods_filelist() - список модифицированных файлов.
  • mods_reset() - сбросить преобразования.
  • preset($name) - вызовет именованное произвольное преобразование по имени $name.
  • count() - вернет количество файлов.
  • fullsize($action) - применяет преобразование $action для полноразмерного изображения.

Примечание. Метод path() у галереи возвращает пустую строку. Поэтому пользоваться им не рекомендуется.

Шаблоны

Можно указать свой шаблон, передав в метод render() его имя. 

<?= $item->field('gallery')->render('path/to/render/template.phtml'); ?>

Или переопределить стандартный шаблон, указав в настройках: 

// app/components/Nodus/app/Datatype/Articles
...
	public function fields()
	{
        	return array(
   			...
			'template' => array('render/ul' => '../app/views/fields/gallery/ul.phtml'),
   			...
	}

В шаблон поступают следующие параметры:

  • files - список файлов, подвергшихся «изуверствам» аля fit.
  • original_dir - директория с оригинальными картинками.
  • original_files - список оригинальных картинок.
  • files_data - данные с подписями.
  • container - ссылка на экземпляр контейнера.

Стандартный шаблон выглядит примерно так: 

<?php
foreach ($container as $i => $data) {
	$sz = CMS_Images::size($data['path']);
		print $this->tags->content_tag('a',$this->tags->tag('img',
         		array_merge(array('src' => $data['url']), $sz[0] > 0 && $sz[1] > 0 ?  array('width' => $sz[0], 'height' => $sz[1]) : array() )),
         		array('href' => $data['orig_url'], 'target' => '_blank'));
}

Произвольные атрибуты

Список атрибутов у загружаемых картинок может быть произвольным (так же как у документов в Documents-типе). Для добавления атрибута достаточно в настройках поля указать: 

   ...
   'extend_doc_fields' => array('caption_en' => array('caption' => 'Назавание на анг')),
   ...

Настройки атрибутов можно посмотреть в документации https://github.com/daffl/jquery.dform.

Для указания типа, отличного от текстового, необходимо задать параметр type.

После этого, при редактировании и выводе изображений, будет доступен атрибут caption_en.

Список доступных настроек: 

container { "type" : "container" }
text { "type" : "text" }
password { "type" : "password" }
submit { "type" : "submit" }
reset { "type" : "reset" }
hidden { "type" : "hidden" }
file { "type" : "file" }
radio { "type" : "radio" }
checkbox { "type" : "checkbox" }
radiobuttons { "type" : "radiobuttons" }
checkboxes { "type" : "checkboxes" }
number { "type" : "number" }
url { "type" : "url" } // HTML 5
tel { "type" : "tel" } // HTML 5
email { "type" : "email" } // HTML 5
Метки: CMS, Контейнер, Обработка изображений
11.08.2014
Все статьи