Как работает Викирама?

По-умолчанию, в PmWiki реализована работа с изображениями через синтаксис Attach. Изображения в этом случае прикрепляются к страницам как любые другие файлы, без какой-либо обработки. Это не очень удобно, поскольку картинкам в большинстве случаев необходим ресайз. Поэтому, для автоматического создания превью существует популярный рецепт Mini от ведущего разработчика PmWiki. Он позволяет создавать превьюшки «на лету».

Викирама является надстройкой над Mini, расширяющей возможности этого рецепта. Викирама выполнена в идеологии Mini; фактически Викирама — это комбинация из настроек Mini, внешней jQuery-фотогалереи и Bootstrap-верстки.

Викирама:

  • с помощью готовых Пресетов, связывает серверную реалиацию Mini с Bootstrap-версткой, предлагая несколько удобных способов размещения превью на странице;
  • для просмотра полноразмерных изображений, связывает серверную реалиацию Mini с frontend-ом Fotorama через ее API.

Что такое Пресеты?

Пресеты — это комбинации параметров Mini. Рецепт предусматривает создание до 10 уникальных пресетов с разными параметрами, которые можно вызывать в контенте страниц командами вида Mini3:. По-умолчанию в рецепте определен только один пресет — дефолтный Mini:. Викирама предоставляет еще 7 дополнительных пересетов, заточенных специально под API Fotorama. Фактически, Викирама и есть набор правильным образом сконфигурированных пресетов.

Общая архитектура решения

«Пресеты с модальным окном» (Mini:, Mini2:, Mini3:, Mini4:, Mini5:, Mini6: ) используют надстройки над дефолтной fotorama.io, которые, работая через API, добавляют следующую логику:

  • PHP: перед каждым Mini: вызовом создается невидимый div class='fotorama …;
  • JS: при загрузке страницы: первый найденный в DOM div class=fotorama инициируется: перемещается в самый низ <body> и получает свой id=fotorama (почему так? Чтобы можно было делать «контентные модификации», см. ниже). Следующие параметры инициации Fotorama определены в файле fotorama-ph.js, но могут быть переопределены через «контентные модификации»: 
 allowfullscreen: 'native',  // чтобы можно было переключиться в полный экран
 nav: false,                 // отключить навигацию по превью
 hash: true,                 // чтобы работал вызов по хэшу в адресной строке
 fit: 'scaledown',           // чтобы большие фотографии сжимались, а мелкие — не растягивались
 maxheight: '100%',          // чтобы на горизонтальных мобильных фотографии ужимались
 keyboard: true              // включение навигации с помощью кнопок клавиатуры
Также применена концепция Lazy load , это сделано на уровне PHP посредством модификации HTML-кода;
  • CSS: id=fotorama представляет его в виде модального окна, которое фиксировано позиционировано и лежит «сверху» всей остальной верстки;
  • PHP: HTML-код всех фотографий, лежащих в совместимых вызовах Mini:, намеренно дублируется. Первая копия используется для отображения превью, вторая — для формирования галереи.
  • JS: при загрузке страницы: копии всех изображений страницы перемещается в id=fotorama. Таким образом формируется полный HTML-код фотогалереи. После этого Fotorama иницируется через API.
  • JS: при при клике на какую-либо фотографию:
    • делает фотогалерию видимой;
    • через API открывает в ней именно ту фотографию, в которую кликнули.
  • А также еще через JS:
    • по ESC, по клику по пустому пространству фотогалерея скрывается;
    • если в адресной строке обнаружен hash, открывает необходимое фото.

Пресет Mini1: использует оригинальную fotorama.io без каких-либо доработок логики. Она просто выводится в месте своего вызова в контенте страницы. Контентные кастомизации в Mini1: не предусмотрены, но их удобно делать с помощью Mini7:.

Контентные кастомизации

«Пресеты с модальным окном» допускают удобную модификацию вызова Fotorama посредством создания div с необходимыми data-параметрами перед первым вызовом Mini: на странице. Достаточно просто создать слой с классом ph-fotorama и data- атрибутами, который необходим для достижения желаемого изменения поведения Fotorama.

В коде страницы это выглядит, например, вот так: 

(:div class='ph-fotorama' data-nav='thumbs' :)
(:divend:)
Mini2:*

Такой код добавит в слайдер превью изображений.

Контентные модификации позволяют применять весь арсенал API Fotorama.io странице сайта.

Этот подход удобен, если вы собираетесь модифицировать вызов Викирамы на одной конкретной странице сайта. А что делать, если нужно внести изменения на весь сайт? Для этого предназначены более низкоуровневые PHP-кастомизации.

Файл phWikirama.php и PHP-кастомизации

Что хранится в PHP-файле рецепта?

В соответствии с принципами PmWiki вообще и Mini в частности, большая часть конфигурации системы и рецептов хранится в php-массивах. Массивы могут быть многократно (пере)определены, а их настройки применяются довольно поздно, в момент генерации страницы.

phWikirama.php написана в соответствии с духом PmWiki, поэтому не содержит никакого кода, кроме определения конфигурационных массивов для пресетов Mini.

Как делать PHP-модификации?

PHP-модификации дают site-wide эффект, то есть применяются ко всем фотогалереям сайта. По-умолчанию, в Викираме определены пресеты 0-6 (т.е. Mini:, Mini1-6:), а Mini7: зарезервирован. Поэтому, если вы собираетесь произвести PHP-модификаию, подумайте, стоит ли вам переопределять один из существующих пресетов, или лучше задействовать незанятые Mini8: или Mini9:.

PHP-модификация состоит в переопределении конфигурационного php-массива выбранного пресета, см. примеры. Переопределение массива должно быть произведено после подключения Викирамы (т.е. include_once("$FarmD/cookbook/phWikirama.php"); из farmconfig.php) и может быть осуществлено как в config.php, так и в skin.php или локальных php-конфигурациях Групп или Страниц. При переопределении массивов, можно пользоваться следующими переменными placeholder:

Шаблоны вывода картинки <IMG> вида $Mini['ImgFmt*']:
      %1$s | путь до превьюшки
      %2$s | title ( крыша Дома Мила, Барселона, 2013 год, автор фото - Арнольд Сталлоне|| best IMG 4667 cr )
      %3$s | путь до исходника
      %4$s | имя исходного файла без обработки
      %5$s | номер группы фотографий
Шаблоны вывода ссылки <A> вида $Mini['LinkFmt**']:
      %1$s | исполнение кода $Mini['ImgFmt']
      %2$s | абсолютынй путь до полноразмерного фото
      %3$s | rel='lightbox_mini_1' title="крыша Дома Мила, Барселона, 2013 год, автор фото - Арнольд Сталлоне"
      %4$s | путь до превьюшки
      %5$s | title аналогично ImgFmt:%2$s
      %6$s | значение для группы картинок (подразумевалось, что rel): lightbox_mini_1 
      %7$s | номер группы картинок (натуральное число)
Шаблоны вывода всего итога $Mini['MiniFmt*']:
      %s   | код вывода всех объектов вида <a> <img> </a>, <a>…
      %1$s = %s
      %2$s | порядковый номер вызова Mini

Как менять внешний вид модального окна?

Внешний вид модального окна определен в файле \pub\!phph\!phph-pack-collection\fotorama\fotorama-ph.css . Дополнительный CSS-код рекомендуется писать в этом же файле.