Введение

Шаблоны - это обычные файлы HTML со специальными метками, на месте которых будет размещаться контент.

Метки записываются в строгом формате: <php:ИмяМетки/>. Name marker (identifier) should consist of English letters and numbers.

В одном шаблоне может быть неограниченное число меток, но как правило достаточно двух-трех.

Содержание

Простой пример

В следующем примере показана страница-шаблон, в которой определено две метки: <php:Head/> и <php:MainContent/>.

<!DOCTYPE html>
<html>
  <head>
    <title></title>
    <meta name="viewport" content="width=device-width" />
    <link rel="stylesheet" href="/Content/css/bootstrap.min.css" />
    <script src="/Scripts/jquery-1.11.1.min.js" type="text/javascript"></script>
    <script src="/Scripts/bootstrap.min.js" type="text/javascript"></script>
    <php:Head/>
  </head>
  <body>
    <div class="container">
      <php:MainContent/>
    </div>
  </body>
</html>

Страницы контента могут содержать блоки контента для указанных в шаблоне меток. Для этого используется специальный системный тег: php:Content, который имеет следующий формат записи:

<php:Content ID="имяМетки">
  Содержимое блока.
  Допустимо использование любых тэгов, 
  серверного кода и 
  элементов управления.
</php:Content>

Если для какой-то из меток не будет определено содержимое на странице контента, то такая метка будет удалена из итогового HTML кода.

В следующем примере показан HTML-код страницы контента, в которой для метки MainContent устанавливается содержимое <h2>Привет, мир!</h2>.

<php:Content ID="MainContent">
  <h2>Привет, мир!</h2>
</php:Content>

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

<!DOCTYPE html>
<html>
  <head>
    <title>Заголовок по умолчанию</title>
    <meta name="viewport" content="width=device-width" />
    <link rel="stylesheet" href="/Content/css/bootstrap.min.css" />
    <script src="/Scripts/jquery-1.11.1.min.js" type="text/javascript"></script>
    <script src="/Scripts/bootstrap.min.js" type="text/javascript"></script>
  </head>
  <body>
    <div class="container">
      <h2>Привет, мир!</h2>
    </div>
  </body>
</html>

Директивы

В шаблонах допустимо использование директив <?#Register ?> для регистрации пользовательских элементов управления.

Другие директивы не поддерживаются и не будут никаким образом обработаны (останутся в итоговом HTML, как есть).

В следующем примере показано использование директив в шаблоне. Директива <?#Page ?> будет проигнорирована и останется в результате обработки запроса в исходном виде. Директивы <?#Register ?> будут успешно обработаны.

<?#Page Title="Test"?>
<?#Register Src="~/Controls/Header.php" TagPrefix="php" TagName="Header"?>
<?#Register Src="~/Controls/Footer.php" TagPrefix="php" TagName="Footer"?>
<?#Register Src="~/Controls/Message.php" TagPrefix="php" TagName="Message"?>

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <php:Header ID="Header1" />

    <div class="container">
      <php:Message Type="Info" Content="Это простой пример" />
      <hr />
      <php:MainContent/>
    </div>

    <php:Footer ID="Footer1" />
  </body>
</html>
<php:Content ID="MainContent">
  Привет, мир!
</php:Content>
<!--Директива Page не поддерживается в шаблонах-->
<?#Page Title="Test"?>

<!DOCTYPE html>
<html>
  <head>
    <title>Заголовок по умолчанию</title>
  </head>
  <body>
    <!--Начало вывода элемента Header-->
    <h1>Test site</h1>
    <!--Конец вывода элемента Header-->

    <div class="container">
      <!--Начало вывода элемента Message-->
      <div class="alert alert-info">Это простой пример</div>
      <!--Конец вывода элемента Message-->
      <hr />
      <!--Начало вывода блока контента MainContent-->
      Привет, мир!
      <!--Конец вывода блока контента MainContent-->
    </div>

    <!--Начало вывода элемента Footer-->
    <footer>
      Copyright © Example, 2015. All rights reserved. 
    </footer>
    <!--Конец вывода элементаа Footer-->
  </body>
</html>

Локализация шаблонов

Для локализации шаблонов можно использовать глобальные ресурсы (global.json).

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

Подробнее о механизмах локализации.

Серверный код

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

Если вы захотите реализовать поддержку серверного кода в шаблонах, то сделать это можно в классе \Nemiro\UI\Page. Например, в методе: Render, где-нибудь перед обработкой пользовательских элементов управления.

# ...
# add head
$pattern = '|<head>(.*)</head>|is';
$result = preg_replace($pattern, '<head>'.$h.'</head>', $result);

# обработка блоков серверного кода в шаблоне
$result = $this->Execute($result);

# controls
$result = $this->RanderControl('Template', $result);

# content blocks
if ($this->Content != NULL && count($this->Content) > 0)
# ...

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

Имена меток блоков контента

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

Во избежание конфликтов, имена меток не должны пересекаться с существующими именами пользовательских элементов управления, имеющими префикс php:.

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

В следующем примере показан шаблон с двумя метками <php:MainContent/> и результат выполнения запроса.

<!DOCTYPE html>
<html>
  <head>
    <title></title>
  </head>
  <body>
    <div class="container">
      <php:MainContent/>
      <br />
      <php:MainContent/>
    </div>
  </body>
</html>
<php:Content ID="MainContent">
  Привет!
</php:Content>
<!DOCTYPE html>
<html>
  <head>
    <title>Заголовок по умолчанию</title>
  </head>
  <body>
    <div class="container">
      Привет!
      <br />
      Привет!
    </div>
  </body>
</html>