Insertions (Вставки)

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

В нашем магазине продаются молотки по 180 р. за штуку!

Но в вашей бухгалтерии все цены ведутся в евро, причем цена в евро не изменяется, а цена в рублях должна всегда пересчитываться по курсу. Можно, конечно, каждый день лазить по всему сайту и править тексты, но такое решение вряд ли кого-то устроит. Как решить проблему? Обычно напрашивается решение - сделать специальную функцию для пересчитывания цены, и вместо непосредственных цифр вставлять в текст вызов этой функции. Например так:

class App_Prices
{
	public static function euro2rub($price)
	{
		// Получим каким-либо способом курс евро
		$euro = App::get_euro();
		// Пересчитаем и возвратим
		return $price*$euro;
	}
}

Вызывать будем так:

В нашем магазине продаются молотки по <?= App_Prices::euro2rub(4) ?> р. за штуку!

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

И тут нам на помощь приходит механизм вставок

В тексте мы будем писать следующее:

В нашем магазине продаются молотки по %euro2rub{4} р. за штуку!

Встретив такую конструкцию, движок сайта будет искать файл app/views/insertions/euro2rub.phtml и, если найдет, то вставит его результат в текст вместо %euro2rub{4}.

Для создания вставки достаточно создать в каталоге ../app/views/insertions/ шаблон с именем вставки (lowercase) и расширением .phtml.

Также можно переопределить стандартные вставки путем копирования шаблона из ../tao/views/insertions/. Но возможно придется очистить кэш для того, чтобы новая (или переопределенная) вставка заработала, т.к. движок не сканирует каждый раз каталоги, а сохраняет их в кеше.

Для библиотечных компонентов предоставляется возможность держать шаблоны вставок в каталоге views/insertions/ компонента.

Далее сделаем такой файл:

// Получим исходную цену из параметра
$price = $args_array[0];
// Получим каким-либо способом курс евро
$euro = App::get_euro();
// Пересчитаем и выведем
print $price*$euro;

После создания файла необходимо очистить кэш (ссылка из девелоперского меню в админке). И все готово - можно пользоваться. Вставки могут иметь как несколько параметров (через запятую), так и вовсе не иметь параметров. Однако в последнем случае синтаксис все равно требует наличия фигурных скобок:

• %aaa{arg1,arg2} - вставка с двумя параметрами
• %bbb{} - вставка без параметров

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

• $args_array - массив параметров
• $args - строка, содержащая все параметры в исходном виде.

Многострочный синтаксис

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

%mycoolinsertion{
	long-argument 1
	long-argument 2
	long-argument 3
}

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

Стандартные вставки

В TAO существует небольшой набор вставок, способный в некоторых случаях облегчить жизнь.

img

Предназначена для вывода изображения. Примеры использования:

• %img{/files/images/image.jpg} - вывод изображения "как есть"
• %img{/files/images/image.jpg,300x300} - предварительно уменьшаем с сохранением пропорций
• %img{/files/images/image.jpg,300x300,open:800x800} - то же самое, но по ссылке открывается более крупное изображение

imgl и imgr

То же самое, что и img, но изображение выводится с обтеканием текстом слева или справа.

maps

Отображение карты (Yandex или Google).

• %maps{53.145711,29.225188,10,640x480} - отобразить карту Yandex с указанными координатами размером 640x480. Здесь 10 - масштаб, а Yandex - по умолчанию.
• %maps{53.145711,29.225188,10,640x480,satellite,google} - то же самое, но с помощью Google, и вместо карты - спутниковый снимок.

youtube

Вставка видеоролика с Youtube. Вывод осуществляется во фрейме (iframe). Вторым параметром можно передать размеры окна (ширина, высота).

• %youtube{84XhArK-6q0,400x300}

calendar

Вставка осуществляет вывод календаря.

В самом простом варианте:

• %calendar{}

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

В качестве параметров можно указать:

• конкретные даты - год, месяц.

%calendar{2016}

%calendar{2016,11}

%calendar{06 2016}

• использование ключевых слов:

%calendar{year:2016}

%calendar{month=03}

%calendar{day:10}

• Можно включить кэширование.

%calendar{cache}

Кэширование будет производиться по ключу: tao:informer:calendar:{$year}-{$month}

Для модификации календаря есть возможность подписаться на события.

1. Для внесения какого-либо функционала перед отрисовкой календаря. Событий может быть произвольное количество, тогда в имя каждого необходимо добавить произвольный идентификатор ($component).

cms.insertions.calendar.setup($router,$orm,$cache)

cms.insertions.calendar.{$component}.setup($router,$orm,$cache)

Передаваемые аргументы:

• $router - роутер, который формирует ссылку на определенную дату.
• $orm - маппер, из которого надо получить значение, показывающее наличие события на данную дату.
• $cache - префикс для ключа, по которому производить кеширование.

2. Определение праздничных дней. Позволяет назначать выходными любые дни.

cms.calendar.is_holiday($d,$holiday)

Передаваемые аргументы:

• $d - дата
• $holiday - значение, определяющее, является ли данная дата выходным днем.

navigation

%NAVIGATION{}

Вывод навигационного блока. Эта вставка - с параметрами, которые могут быть указаны в фигурных скобках. Если параметры не указаны, то это эквивалентно вызову %NAVIGATION{0}.

Число указывает уровень навигации, который требуется выводить. Нумерация уровней начинается с нуля. Подробнее "Навигация".

route

%ROUTE{}

Вывод "хлебных крошек" на внутренних страницах. Подробнее "Навигация".

var

%VAR{var_name}

Выводит значение настройки var_name.

head

%HEAD{}

Заголовочная информация, которая будет состоять из:

• Тега TITLE
• Мета-тегов (description, keywords)
• Директив подключения JavaScript и CSS
• Прочей информации, обычно размещаемой в заголовочной части HTML-страницы

Подробнее в статье.