Создание шкур
См. также:
Организация шкур, перечни файлов и краткий алгоритм создания (версия <1.7)Minimalistic skin example
скачатьAbstract
В данном документе рассматривается процесс создания шкур (скинов) для НПЖ и описываются некоторые важные для этого дела особенности системы, а именно: структура шкуры, программный контекст, движок шаблонов и синтаксис шаблонов, переменные, доступные из шаблонов, обнаруженные проблемы.
1. Введение
1.1. Что такое шкура
В соответствии с логикой MVC (Model-View-Controller), хранение и обработка данных в НПЖ отделены от представления, благодаря чему представление данных может быть (в идеале) произвольным. Шкура – часть программной системы на уровне представления (помимо шкур к этому уровню следует отнести движок шаблонов и некоторые классы системы, напр. UtilitySkin), отвечающая за формирование пользовательского интерфейса на основе шаблонов и полученных данных.
1.2. Структура шкуры в контексте программной системы
Шкура формируется в контексте всего приложения, однако существует возможность расширения функциональности системы уже на уровне представления для переопределения переменных шаблона или осуществления дополнительных программных действий с помощью т.н. «мэджиков». Однако их использование вместо имеющихся функций ухудшает программную логику и приводит к нерациональному использованию ресурсов системы (повторение операций, увеличение времени обработка запроса).
Ниже приводится базовая структура каталогов шкуры (в примерах используется шкура minimalistic):
/npj/themes/_common – общие для всех шкур элементы (в данной папке – унаследованные от Manifesto)
/npj/themes/absent – отсюда запрашиваются элементы, запрошенные, но не присутствующие в конкретных шкурах
/npj/themes/minimalistic – корневая папка шкуры
/npj/themes/minimalistic/css – оформительские CSS
/npj/themes/minimalistic/js – скрипты, специфичные для шкуры или оверрайд (в частности, override.js в всех «родных» шкурах)
/npj/themes/minimalistic/images – изображения для пользовательского интерфейса и дизайна страниц
/npj/themes/minimalistic/templates – шаблоны
/npj/themes/minimalistic/tpl_magic – «мэджики» – фрагменты PHP-кода, выполняемые в при парсинге шаблонов
1.3. Подключение
Достаточно указать название папки, в которой располагается новая шкура, в массиве $this->skins в файле настроек config_tunes.php, после чего ее можно будет включить через интерфейс.
2. Шаблоны
2.1. Описание
Движок шаблонов в НПЖ достаточно развит (авторы утверждают, что он так же крут, как Smarty), т.к., являясь частью движка Manifesto, использовался для построения большого числа сайтов. В дальнейшем движок Manifesto послужил основой для движка Rocket, составной частью которого стал движок шаблонов RocketTE, основанный на рассматриваемом д.ш., но значительно переработанный, также в части синтаксиса. Т.о. движок шаблонов в НПЖ представляет собой в известной степени legacy code и требует рефакторинга. В использовании, однако, никаких нареканий у меня не вызывает (в отличие от форм-процессора, до которого еще дойдем).
2.2 Основы синтаксиса
Синтаксис д.ш. где-то описан более подробно, возможно создателями. Здесь указываю только те конструкции, которые использую сам.
Этот кусок в html! Поправить форматтер
<style type="text/css">div { } p#templ1 {background:#dcdcdc; color: black; font-size:110%; margin:0; padding:0 0 5px 0;} p#templ2 {background:#a9a9a9; color: black; font-size:110%; margin:0; padding:0 0 5px 0;}</style>
<p id="templ1">Unknown action "@template.html" – включить файл template.html в тело шаблона. (Примечание! при наличии вложенных папок внутри папки templates, путь следует указывать от ее корня, даже если ссылающийся файл находится в одном каталоге с файлом, который включается)</p>
<p id="templ2">Unknown action "&js:myscript" – включить файл со скриптом из каталога js</p>
<p id="templ1">Unknown action "Variable" – при парсинге вместо этой конструкции подставляется значение переменной</p>
<p id="templ2">Unknown action "??Variable" ... Unknown action "??!Variable" ... Unknown action "??/Variable" – аналогично if (isset(Variable)) { ... } else { ... } – парсит только отдельные фрагменты шаблона в зависимости от наличия переменной.</p>
<p id="templ1">Unknown action "?Variable" ... Unknown action "?/" – сокращенная форма записи</p>
<p id="templ2">Unknown action "#Magic" – вызвать «мэджик» (если необходимо, чтобы мэджик вывел какое-то значение в шаблон, он должен сделать это явно с помощью echo/print, иначе мэджик ничего в шаблон не выводит. Еще один вариант, когда мэджик вызвает функцию парсинга некоторого подшаблона или другого шаблона, тогда распарсенный фрагмент будет доступен в контексте шаблонов и может быть включен в выводимую страницу)</p>
<p id="templ1">Unknown action "TEMPLATE:TemplateName" ... Unknown action "/TEMPLATE:TemplateName" – подшаблонка (допускаются вложенные конструкции)</p>
- Переменные становятся доступными из шаблона после вызова функции ($rh->)$tpl->Assign(«Variable», “value”); на уровне обработки данных (включая «мэджики»).
- Шаблоны парсятся при вызове функции ($rh->)$tpl->Parse(«tamplate.html:TemplateName"); где template.html соответствует файлу шаблона в папке templates, а выражение TemplateName – подшаблону, начало которого указано в файле шаблона с помощью конструкции Formatter «highlight/vti» not found
2.3. Порядок парсинга шаблонов
Первым парсится шаблон html.html. Помимо него в каталоге templates могут располагаться файлы record.html, record.comments.html и другие. Все они должны включаться в шаблон html.html напрямую или через вызов «мэджика» (например, таким образом: <? echo $tpl->Parse(«layout/sidebar.html:Guest"); ?>
3. Контекст
3.1. Переменные, доступные из шаблона
«Статы»
«Статы», как их называют создатели НПЖ в комментариях к коду, это переменные, доступные из шаблона страницы, в которых хранятся данные о загруженной странице. Задаются они в методе UtilitySkin::AssignRecordStats(). В родных шкурах этот метод вызывается в мэджике (tpl_magic) Path, что имхо очень неправильно, т.к. этот мэджик выводит пермалинк, а инициализация «статов» оказывается побочным эффектом (причем далеко не очевидным – поди найди, где это, если заранее не знаешь). «Статы» же могут использоваться и дальше – и используются. Поэтому в своих шкурах я выношу инициализацию статов в отдельный мэджик.
- Record.Stats.Address – адрес загруженной страницы
- Record.Stats.Security – доступ
- Record.Stats.Security.Icon
- Record.Stats.Security.IsPublic
- Record.Stats.Journal0 – пользователь
- Record.Stats.Journal1 – сообщество (?)
- Record.Stats.Journal2 – рабочая группа
- Record.Stats.ChangedByName – имя (точнее, user_name) редактировавшего последним
- Record.Stats.ChangedBy – очевидно, id
- Record.Stats.ChangedDT – timestamp последней редакции
- Link:Record.Stats.ChangedBy – ссылка на журнал последнего редактировавшего
- Record.Stats.Type – ?
- Record.Stats.TypeName
- Record.Stats.Ref
Другие важные переменные
- skin – каталог текущей шкуры
- theme – каталог текущей темы (т.к. в НПЖ она только одна, то это всегда npj/themes/absent)
- theme_images – npj/themes/absent/images
- Href:Principal – ссылка на корневую страницу авторизованного пользователя
- Href:Account – ссылка на корневую страницу пользователя, которому принадлежит просматриваемый документ
- JournalHead:Title
- / – корневой документ сайта (узла node)
3.2. Объекты и свойства, доступные из «мэджиков»
В целом, обычные. В частности:
- $rh – инстанс класса NpjRequestHandler (хранит просто все)
- $rh->tpl – инстанс класса TemplateEngine
- $rh->db – это DBAL::conn (т.е. обращаться к БД можно так: $rh->db->Execute($sql);)
- $rh->account->data – массив с данными о текущей странице и пользователе, которому она принадлежит
- $rh->principal->data – массив с данными о залогиненном пользователе или госте
4. Проблемы
1) Вызов UtitlitySkin::AssignRecordStats() в мэджике absent/tpl_magic/Path.php – затемняет логику, поэтому вынесен в отдельный мэджик (см. выше про Record.Stats)