Интеграция с приложением «Сайт»

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

1. Темы оформления

Если у приложения есть фронтенд, то, чтобы пользователи приложения могли редактировать внешний вид фронтенда внутри приложения «Сайт», рекомендуется использовать темы оформления. Для этого нужно в файле описания wa-apps/APP_ID/lib/config/app.php добавить объявление свойства

'themes' => true

и создать тему оформления (либо несколько тем) по умолчанию в папке wa-apps/APP_ID/themes/.

Тема оформления — это объединенные в одной папке HTML/Smarty-шаблоны, файлы JavaScript, CSS, изображения и файл-манифест theme.xml.

Обязательные параметры файла-манифеста theme.xml:

1. id: совпадает с названием папки для темы
2. app: идентификатор приложения (APP_ID), для которого создана тема
3. name: название темы — обязательно указать хотя бы на одном языке
4. files: список файлов, доступных для редактирования в приложении «Сайт»

Ниже приведён пример описания темы default для приложения «Сайт» (тема располагается в папке wa-apps/site/themes/default/):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE theme PUBLIC "wa-app-theme" "http://www.webasyst.com/wa-content/xml/wa-app-theme.dtd" >
<theme id="default" system="1" vendor="webasyst" app="site" version="1.0.0">
  <name locale="en_US">Default theme</name>
  <name locale="ru_RU">Основная тема</name>
  <files>
    <file path="index.html">
      <description locale="en_US">Common layout</description>
      <description locale="ru_RU">Основной шаблон</description>
    </file>
    <file path="page.html">
      <description locale="en_US">Page content</description>
    </file>
    <file path="sidebar.html">
      <description locale="en_US">Page navigation</description>
    </file>
    <file path="error.html">
      <description locale="en_US">404 and other errors</description>
    </file>
    <file path="default.css">
      <description locale="en_US">CSS for common desktop and laptop computers</description>
    </file>
    <file path="mobile.css">
      <description locale="en_US">CSS for multi-touch mobile devices</description>
    </file>
  </files>
</theme>

Для того чтобы контроллерами/экшенами фронтенда приложения использовались шаблоны из темы оформления, а не из папки templates/, нужно в коде контроллера/экшена указать, какой файл темы следует использовать:

$this->setThemeTemplate('page.html');

Этот метод доступен в экземплярах классов, использующих шаблоны waViewAction, waViewController, waViewActions, waLayout.

В результате этих действий в приложении «Сайт» появится возможность редактировать шаблоны дизайна и другие файлы темы (например, CSS и JavaScript):

При установке нового приложения и новых тем оформления через «Инсталлер» либо вручную вручную темы устанавливаются в папку wa-apps/APP_ID/themes/.

Когда пользователь редактирует тему в приложении «Сайт», создаётся копия темы в папке wa-data/public/APP_ID/themes/, которая при дальнейших обновлениях приложения и оригинала темы остаётся без изменений, гарантируя сохранность изменений в шаблонах.

2. Шпаргалка

В шаблонах дизайна приложения допускается использовать полноценный инструментарий шаблонизатора Smarty, в частности, некоторые системные переменные и методы фреймворка Вебасист. Например, доступны переменная {$wa_theme_url}, которая указывает путь к папке темы оформления, и объект {$wa}, предоставляющий набор полезных методов.

Все основные методы, доступные в контексте шаблона (страницы), перечислены в шпаргалке приложения «Сайт». Шпаргалка — это интерфейсно-описательный инструмент приложения «Сайт», созданный для удобства пользователя. По желанию разработчик может добавить для своего приложения индивидуальные шаблоны из темы оформления для определенных шаблонов переменные и конструкции. Такое объявление не является обязательным, однако будет чрезвычайно удобно дизайнеру, работающему с шаблонами.

Основной список элементов шпаргалки может быть расширен в файле wa-apps/APP_ID/lib/config/site.php (создайте такой файл, если в вашем приложении его нет). Ниже приведено демонстрационное содержимое такого файла, добавляющее индивидуальные списки переменных для разных шаблонов.

<?php
return array(
  'vars' => array(
    'page.html' => array(
      '$page.name' => _w('Page name'),
      '$page.title' => _w('Page title (<title>)'),
      '$page.content' => _w('Page content'),
      '$page.update_datetime' => _w('Page last update datetime'),
    ),
    'index.html' => array(
      'title' => _w('Title'),
      'content' => _w('Content'),
      'meta_keywords' => _w('META Keywords'),
      'meta_description' => _w('META Description'),
    ),
    'error.html' => array(
      '$error_code' => _w('Error code (e.g. 404)'),
      '$error_message' => _w('Error message'),
    )
  )
);

Ключом массива является название файла шаблона, а значением — массив переменных. Если в приложении есть переменные, доступные во всех шаблонах, их можно описать в массиве с ключом "all" вместо названия файла.

3. Страницы

Документация процесса интеграция приложения с функционалом информационных страниц приложения «Сайт» находится в разработке.