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

Файлы шаблонов вывода результатов макросов состоят из блоков, внутри которых может быть любая текстовая информация (в том числе и 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) Все остальные макросы и будут локальными макросами этого шаблона. Выпишем их вместе с блоками, в которых они встретились:

Если мы посмотрим в справочник макросов, например в описание блоков шаблона для макроса %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% (макрос вывода поля, который может быть вызван где угодно) тоже может зависеть от контекста.