Логотип

Документация по макросам и шаблонам UMI.CMS

Макросы в TPL-шаблонизаторе

В предыдущем топике, при подключении TPL-шаблона нам встретились макросы, выполняющие различные подстановки. Рассмотрим подробнее классификацию макросов доступных в UMI.CMS при использовании TPL-шаблонизатора.

Макросы вывода поля или идентификатора

Ряд макросов просто выводит значение поля (например макросы %keywords%, %title%), или идентификатор (например %pid%).

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

Например, если мы хотим для группы страниц выводить комментарии к странице под текстом контента страницы — можно сделать шаблон дизайна, где после макроса %content% указать место вставки комментариев следующим образом:

%comments insert(%pid%)%

Макрос %pid% будет отработан раньше макроса %comments insert()% и в момент срабатывания последнего, в качестве параметра будет стоять число — идентификатор данной страницы.

Методы модулей

Эта группа макросов вызывается следующим образом: %имя_модуля имя_метода(список параметров)%.

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

Например, если мы подставим в шаблон дизайна вызов:

%news lastlist('/novosti_sajta/','sample',5,1)%

То для всех страниц, к которым будет применен этот шаблон, вместо макроса будет выводиться блок из 5 последних новостей из ленты по адресу http:/ваш_сайт/novosti_sajta/, оформленных по шаблону sample.tpl, и при этом будет игнорироваться постраничный вывод (см. описание макроса %news lastlist()%).

Важно! Не стоит размещать несколько макросов на одной строке, вложенные макросы могут не сработать в качестве аргумента у других макросов.

Шаблоны вывода результатов

Файлы шаблонов вывода результатов макросов состоят из блоков, внутри которых может быть любая текстовая информация (в том числе и html-код), а также могут быть различные макросы. У каждого блока есть уникальное имя (по сути это ключи ассоциативного массива в PHP) и две метки — начало и конец блока.

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

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

Локальные макросы

Рассмотрим действие этих макросов на примере трех первых блоков шаблона ~/tpls/news/default.tpl — шаблон, использующийся модулем "Новости":

<?php

$FORMS = Array();

$FORMS['lastlist_block'] = <<<END

<div>
 %items%
 %system numpages(%total%, %per_page%, 'standart')%
</div>

END;

$FORMS['lastlist_item'] = <<<END

<div class="item">

 <span class="date">
   %system convertDate(%publish_time%, d.m.Y)%
 </span> |

 <a href="%lent_link%">%lent_name%</a>
 <a href="%link%" class="title">%header%</a>

 %data getProperty(%id%, 'anons_pic', 'news.anons.home')%

 <div>
  %anons%
 </div>

 <div class="comments">
  <a href="%link%#comments" >Комментарии (%comments countComments(%id%)%)</a> | 
  <a href="%link%#add_comment">Добавить комментарий</a>
 </div>

</div>

END;

$FORMS['view'] = <<<END

 %data getProperty(%id%, 'publish_pic', 'news.view')%
 %content%
 %news related_links(%id%)%
 %comments insert(%id%)%

END;

?>

Разобьем встретившиеся макросы на группы:

1) Макросы, являющихся методами различных модулей:

2) Глобальные макросы %content% и %header%;

3) Все остальные макросы и будут локальными макросами этого шаблона. Выпишем их вместе с блоками, в которых они встретились:

  • lastlist_block: %items%, %total%, %per_page%

  • lastlist_item: %publish_time%, %lent_link%, %lent_name%, %id%, %link%, %anons%

  • view: %id%

Если мы посмотрим в справочник макросов, например в описание блоков шаблона для макроса %news lastlist()%, мы можем увидеть, что локальные макросы также могут выводить идентификаторы (%id%), значения полей (%anons%, %publish_time%), а также могут выводить содержимое других блоков этого шаблона (%items%).

Названия этих макросов в большинстве случаев интуитивно понятны. Однако может возникнуть ряд резонных вопросов: локальный макрос с именем %id% встречается в более чем одном блоке — возможно мы можем его использовать где-то еще? возможно мы можем использовать и другие макросы не только в одном блоке?

Для того, чтобы ответить на эти вопросы, необходимо познакомиться с еще одним понятием — контекст блоков шаблона.

Контекст блоков шаблона

Рассмотрим в качестве примера взаимодействие блоков lastlist_block и lastlist_item при вызове в шаблоне дизайна макроса %news lastlist()%.

Упростим задачу — оформим эти два блока следующим образом:

$FORMS['lastlist_block'] = <<<END

<div class="block">
 %items%
</div>

END;

$FORMS['lastlist_item'] = <<<END

<div class="item">
  %anons%
</div>

END;

Тогда html-код подставленный вместо макроса будет выглядеть следующим образом:

<div class="block">
  <div class="item">
    // анонс последней новости
  </div>
  <div class="item">
    // анонс предпоследней новости
  </div>
  <div class="item">
    // анонс третьей с конца новости
  </div>

   ... // и так далее; общее количество определяется настройками количества элементов на странице

</div>

Где вместо комментариев будут анонсы соответствующих новостей.

Теперь добавим в шаблон следующие макросы — локальный макрос %id% и макрос %header%:

$FORMS['lastlist_block'] = <<<END

<div class="block">
 <p>ID: %id%</p>
 <h1>%header%</h1>
 %items%
</div>

END;

$FORMS['lastlist_item'] = <<<END

<div class="item">
  <p>ID: %id%</p>
  <h2>%header%</h2>
  %anons%
</div>

END;

Теперь, если мы обновим страницу, html-код изменится на следующий:

<div class="block">

  <p>ID: 13</p>  // id страницы, где вызван макрос
  <h1> // заголовок страницы, где вызван макрос</h1>
  
  <div class="item">
    <p>ID: 18</p> // id последней новости
    <h2> // заголовок последней новости </h2>
      // анонс последней новости
  </div>

  <div class="item">
    <p>ID: 19</p> // id предпоследней новости
    <h2> // заголовок предпоследней новости</h2>
     // анонс предпоследней новости
  </div>

  <div class="item">
    <p>ID: 20</p> // id третьей с конца новости
    <h2> // заголовок третьей с конца новости</h2>
     // анонс третьей с конца новости
  </div>

    ...  // и так далее; общее количество определяется настройками количества элементов на странице

</div>

Мы можем видеть, что макросы %id% и %header% в разных блоках шаблона выводят разные значения, то есть результат зависит от места вызова, а если еще точнее — от обрабатываемого в этом блоке объекта. Список доступных в этом блоке объектов с их полями и их значениями и является контекстом блока шаблона.

Для макросов блока laslist_block контекстом является страница, где был вызван макрос %news lastlist()%. Поэтому макросы %id% и %header% возвращают нам соответствующий идентификатор и поле этой страницы.

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

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

Макросы-сокращения

Для некоторых макросов, являющихся методами модуля, используется сокращенная запись. На данный момент их всего 2:

При вызове этих макросов используются значения по умолчанию для всех параметров.

Была ли данная статья полезна?