Шаблоны — Документация Webasyst

В качестве шаблонизатора по умолчанию фреймворк использует Smarty 3. Об использовании других движков шаблонов см. ниже.

Разработчик приложения технически не ограничен в возможностях дизайна и верстки интерфейса. Обязательным для соблюдения условием является только расположение и название файла шаблона. Подробнее об именовании файлов шаблонов см. в разделе «Правила и рекомендации по именованию».

Использование Smarty

Для упрощения разработки фреймворк предоставляет ряд переменных и хелперов, доступных в шаблоне.

Переменные

{$wa_url}: путь к корню установки фреймворка от корня сайта.
{$wa_app_url}: относительный URL лицевой страницы приложения от корня сайта. В шаблонах фронтенда переменная возвращает путь к лицевой странице фронтенда приложения, в шаблонах бекенда — путь к лицевой странице бекенда приложения.
{$wa_app_static_url}: путь к каталогу приложения от корня сайта (применяется для построения ссылок на статические файлы приложения, например: {$wa_app_static_url}img/logo.png.
{$wa_app}: возвращает APP_ID приложения.
{$wa_backend_url}: относительный URL бекенда.

Хелпер `$wa`:

{$wa->header()} — возвращает HTML-код шапки бекенда со списком установленных приложений и именем текущего пользователя.
{$wa->app()} — APP_ID приложения.
{$wa->appName()} — название приложения.
{$wa->accountName()} — название аккаунта (экземпляра установки фреймворка).
{$wa->css()} — возвращает HTML-код подключения необходимых CSS-файлов.
{$wa->user()->getName()} — имя текущего пользователя.
{$wa->user()->getId()} — идентификатор текущего пользователя.
{$wa->version()} — номер версии приложения.
{$wa->url()} — путь к корню установки фреймворка от корня сайта.
{$wa->url(true)} — путь к корню бекенда от корня сайта.

Локализация

Для отображения строк, требующих перевода в зависимости от локали пользователя, следует использовать механизм gettext. В этом случае в код шаблона вставляется строка-ключ для перевода в обрамлении конструкции [` `], например: [`some gettext key`]. Подробнее о механизме локализации см. раздел «Локализация».

Пример

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>{$wa->appName()} &mdash; {$wa->accountName()}</title>
{$wa->css()}
<script src="{$wa_url}wa-content/js/jquery/jquery-1.4.2.min.js" type="text/javascript"></script>
</head>
<body>
<div id="wa">
    {$wa->header()}
    <div id="wa-app">
    <div class="block">
        {if !$records}
        <p>[`Guestbook is empty. Write a new post on the public guestbook page.`]</p>
        {else}
        <ul class="zebra">
        {foreach from=$records item=r}
        <li>
            {if $rights_delete}<a class="count" href="?action=delete&id={$r.id}"><i class="icon16 delete"></i></a>{/if}
            <span class="hint">
            <strong>{$r.name|escape}</strong>
            {$r.datetime|wa_datetime}
            </span>
            {$r.text|escape|nl2br}
        </li>
        {/foreach}
        </ul>
        {/if}
        <a href="{$url}" target="_blank">[`Guestbook on site`]</a>
        <i class="icon10 new-window"></i>
    </div>
    </div>
</div>
</body>
</html>

Использование альтернативных шаблонизаторов

Используемый по умолчанию шаблонизатор Smarty 3 можно заменить на любой альтернативный движок шаблонов.

Взаимодействие фреймворка с движком шаблонов происходит через специальный класс-адаптер. В частности, обращение системы к Smarty 3 происходит через системный класс waSmarty3View, содержащийся в файле wa-system/view/waSmarty3View.class.php.

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

Подключение шаблонов на чистом PHP

В состав фреймворка включен адаптер для использования в качестве шаблонов обычных PHP-файлов.

Внимание: в настоящий момент этот адаптер реализован в упрощенном виде в демонстрационных целях и не предназначен для использования в проектах с высокой нагрузкой.

Для того чтобы в вашем приложение вместо Smarty использовались шаблоны на чистом PHP, достаточно создать конфигурационный файл wa-apps/{APP_ID}/lib/config/factories.php следующего содержания:

<?php

return [
    'view' => 'waPHPView'
];

Если файл factories.php уже существует в приложении, в него необходимо добавить соответствующую строку.

К шаблонам в виде обычных PHP-файлов применяются те же правила расположения и именования файлов, что и для шаблонов Smarty (подробнее см. «Правила и рекомендации по именованию»). Единственным отличием является расширение имён файлов шаблонов: в отличие от шаблонов Smarty с расширением .html, шаблоны PHP имеют стандартное расширение .php.

В PHP-шаблонах доступны те же встроенные переменные и хелпер $wa, что и в шаблонах Smarty.

Создание адаптера для подключения альтернативного шаблонизатора

Любое разрабатываемое приложение можно настроить на использование привычного разработчику шаблонизатора. Для этого необходимо в конфигурационном файле приложения wa-apps/{APP_ID}/lib/config/factories.php указать класс адаптера подключения шаблонизатора:

<?php

return [
    'view' => '{НАЗВАНИЕ КЛАССА-АДАПТЕРА VIEW}'
];

По умолчанию в качестве значения параметра view используется waSmarty3View (адаптер для Smarty 3).

В качестве класса адаптера можно определить свой класс (его необходимо наследовать от системного класса waView), разместить его в файле с соответствующим именем (см. раздел «Правила и рекомендации по именованию») в любом месте внутри подкаталога lib/ приложения и реализовать в нём все необходимые функции.

Реализация адаптера для подключения шаблонизатора на примере класса waPHPView:

<?php

/**
* Любой адаптер View должен быть унаследован от системного класса waView
*/
class waPHPView extends waView
{
    // Здесь задаются расширения файлов шаблонов, по умолчанию используется .html,
    // для использования обычного PHP в качестве view, файлы шаблонов должны иметь имена вида *.php
    protected $postfix = '.php';

    // Переменная для хранения данных, переданных во view
    protected $vars = [];

    // Корневой каталог для шаблонов (задаётся в конструкторе)
    protected $template_dir = [];

    // Объект waSystem приложения
    protected $system;

    // Вспомогательная переменная для хранения текущего активного шаблона
    protected $current_template;

    public function __construct(waSystem $system, $options = [])
    {
        $this->system = $system;
    
        // Устанавливаем корневой каталог для шаблонов,
        // по умолчанию это каталог приложения wa-apps/{APP_ID}/
        $this->template_dir = isset($options['template_dir']) ? $options['template_dir'] : $this->system->getAppPath();
    }

    /**
    * Реализация функции assign - передача данных в шаблон из экшена/контроллера
    */
    public function assign($name, $value = null)
    {
        if (is_array($name)) {
            $this->vars += $name;
        } else {
            $this->vars[$name] = $value;
        }
    }

    /**
    * Удаление переменной
    */
    public function clearAssign($name)
    {
        if (isset($this->vars[$name])) {
            unset($this->vars[$name]);
        }
    }

    /**
    * Очистка всех переданных данных в шаблон
    */
    public function clearAllAssign()
    {
        $this->vars = [];
    }

    /**
    * Возвращает одну либо все переменные, переданные в шаблон
    */
    public function getVars($name = null)
    {
        if ($name === null) {
            return $this->vars;
        } else {
            return isset($this->vars[$name]) ? $this->vars[$name] : null;
        }
    }

    /**
    * Возвращает результат рендеринга шаблона в виде строки
    */
    public function fetch($template, $cache_id = null)
    {
        ob_start();
        $this->display($template, $cache_id);
        $result = ob_get_contents();
        ob_end_clean();
        return $result;
    }

    /**
    * Рендерит шаблон в браузер клиента
    */
    public function display($template, $cache_id = null)
    {
        if ($this->templateExists($template)) {
            $this->current_template = $template;
            extract($this->vars);
            include($this->template_dir.'/'.$this->current_template);
        } else {
            throw new waException("Template ".$template.' not found');
        }
    }

    /**
    * Проверяет, существует ли указанный шаблон
    */
    public function templateExists($template)
    {
        return file_exists($this->template_dir.'/'.$template);
    }
}