Minimalistic skin example скачать

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

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 Основы синтаксиса

Синтаксис д.ш. где-то описан более подробно, возможно создателями. Здесь указываю только те конструкции, которые использую сам.

{{@template.html}} – включить файл template.html в тело шаблона. (Примечание! при наличии вложенных папок внутри папки templates, путь следует указывать от ее корня, даже если ссылающийся файл находится в одном каталоге с файлом, который включается)

{{&js:myscript}} – включить файл со скриптом из каталога js

{{Variable}} – при парсинге вместо этой конструкции подставляется значение переменной

{{??Variable}} ... {{??!Variable}} ... {{??/Variable}} – аналогично if (isset(Variable)) { ... } else { ... } – парсит только отдельные фрагменты шаблона в зависимости от наличия переменной.

{{?Variable}} ... {{?/}} – сокращенная форма записи

{{#Magic}} – вызвать «мэджик» (если необходимо, чтобы мэджик вывел какое-то значение в шаблон, он должен сделать это явно с помощью echo/print, иначе мэджик ничего в шаблон не выводит. Еще один вариант, когда мэджик вызвает функцию парсинга некоторого подшаблона или другого шаблона, тогда распарсенный фрагмент будет доступен в контексте шаблонов и может быть включен в выводимую страницу)

{{TEMPLATE:TemplateName}} ... {{/TEMPLATE:TemplateName}} – подшаблонка (допускаются вложенные конструкции)

• Переменные становятся доступными из шаблона после вызова функции ($rh->)$tpl->Assign(«Variable», “value”); на уровне обработки данных (включая «мэджики»).
• Шаблоны парсятся при вызове функции ($rh->)$tpl->Parse(«tamplate.html:TemplateName»); где template.html соответствует файлу шаблона в папке templates, а выражение TemplateName – подшаблону, начало которого указано в файле шаблона с помощью конструкции {{TEMPLATE:TemplateName}}

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)