Markus
Markus - набор task'ок и watcher'ов, для верстки с шаблонизатором SwigJS.
Этот проект больше не поддерживается.
Цель:
Основная цель Markus
- сделать максимально быструю интеграцию верстку с Symfony, минимизировав затраты на перенос и редактирование шаблонов, за счет частичного использования методологии Symfony, шаблонизатора SwigJS и великолепного сборщика Gulp.
Структура проекта:
В проекте три основных директории: web
, markup
и gulp
. Подробнее о каждой из папок ниже.
Web:
В папке web представлены все статичные файлы проекта:
components
- все вендоры bower;less
- ресурсы less;css
- скомпилированные файлы css;js
- скомпилированные файлы js (не реализовано. Сейчас используются простой JS);images|videos
- все изображения|видео;fonts
- все используемые шрифты;plugins
- все кастомные вендоры, которые не вошли в bower;*.html
- скомпилированные файлы проекта.
Замечание: Никто не запрещает менять структуру и добавлять новые папки и файлы. Но есть пара task, которые очень жестко завязаны на данной структуре. Ее можно посмотреть в файле конфигурации gulp - gulp/config.js
. Там, как раз и прописаны все пути к требуемым папкам и файлам. Изменение структуры, позволяет гибко настраивать иерархию папок и файлов с минимальными трудозатратами.
Markup:
В папке markup представлены файлы проекта по 3 категориям:
- models – хранятся все файлы сущностей, используемых в проекте,
- views - хранятся все файлы шаблонов страниц и блоков, используемых в проекте,
- controllers - хранит конфигурации всех путей и данных для моделей и представлений,
которые реализуют паттерна программирования - Model-View-Controller.
Models - содержит все файлы сущностей, используемых в проекте. Рекомендуется создавать на каждую новую сущность отдельный JS файл, в котором будет сначала описан класс сущности, а затем экспортированы соответствующие данные.
Например сущность персоны может принимать вот такой вид, который будет описывается следующей структурой:
function Person(id, name, isActive, image) {
this.id = id;
this.name = name;
this.isActive = isActive;
this.image = image;
}
module.exports.persons = [
new Person(1, 'Ivan', true, 'images/persons/person1.jpg'),
new Person(2, 'Max', false, 'images/persons/person2.jpg'),
new Person(3, 'Igor', true, 'images/persons/person3.jpg'),
new Person(4, 'Semen', false, 'images/persons/person4.jpg')
];
Views - содержит все шаблоны страниц (модулей/блоков/виджетов). По факту - это вся верстка проекта с парой особенностей.
В основу верстки ложится шаблонизатор SwigJS, который максимально приближен к шаблонизатору Twig, используемого в Symfony по умолчанию. С полной документацией можно ознакомится вот здесь - SwigJS/doc.
Для всех страниц (которые в последствии должны стать самостоятельными html файлами) мы создаем базовый шаблон, в котором есть обычно шапка и футер, и называем его - base.html.twig ( постфикс .html не обязателен, но он необходим для проектов, которые будут интегрироваться с Symfony). Базовый шаблон лежит в корневой директории всех шаблонов и является каркасом для всех последующих страниц.
Для всех общих блоков, которые присутствуют на разных страницах - мы создаем их в папке markup/views/common
. А подключаются эти блоки с помощью тега include
. Например, для подключения common/navbar.html.twig
это будет выглядеть следующим образом:
{% include 'common/navbar.html.twig' %}
Важно: пути к файлам определяются относительно корневой папки шаблонов - markup/views
. Т.е. для подключения блока common/test.html.twig
в файле шаблона news/my/custom/folder/page_news.html.twig
строчка подключения не изменится
{% include 'common/test.html.twig' %}
Это реализуется с помощью cutomного загрузчика файлов при компиляции шаблонов в SwigJS.
Все названия шаблонов в папке шаблонов разделяются с помощью нижнего подчеркивания.
Все папки шаблонов называются с маленькой буквы и единственном числе для сущности: person, author, user, build, event и т.д.
Все внешние файлы подключаются функцией asset, которая генерирует правильные пути к ресурсам. Например, для подключения библиотеки bootstrap из вендоров bower, необходимо написать следующее:
<link rel="stylesheet" href="{{ asset('components/bootstrap/dist/css/bootstrap.min.css') }}">
<script src="{{ asset('components/jquery/dist/jquery.min.js') }}"></script>
<script src="{{ asset('components/bootstrap/dist/js/bootstrap.min.js') }}"></script>
Controllers - содержит конфигурацию компилируемых файлов.
Механизм компиляции файлов из файлов контроллеров прост - просматриваем поочередно каждый файл и смотрим входящие в него экшены. Затем перебираем все экшены и компилируем страницы, в зависимости от конфигурации экшена.
Например, рассмотрим person контроллер:
exports.person = {
list: {
alias: 'persons',
template: 'person/list.html.twig',
models: ['person']
},
show: {
alias: 'person-show',
template: 'person/show.html.twig',
models: ['person']
}
};
Видно, что контроллер содержит два экшена - list
и show
.
Экшен list
имеет следующую конфигурацию:
alias
- название файла, которым будет сгенерировано при компиляцииtemplate
- шаблон, который будет использоваться для компиляцииmodels
- списки сущностей, которые будут загружены в models (это не реализовано. Сейчас подгружаются все сущности, которые есть вmarkup/models
)
В итоге после компиляции шаблона person
, в папке web
появиться два файла - persons.html
и person-show.html
Каждый экшен контроллера имеет свой уникальный роут, который имеет вид: controller_action
.
Для генерации путей можно использовать функцию path
с названием роута:
<a href="{{ path('person_show') }}" class="link">Link</a>
Выше приведенный пример применим для контроллера Person
и экшена show
.
Gulp:
Gulp - содержит все task'и и watcher'ы сборки. Все задачи разбиты по максимально атомарным действиям:
css
- все задачи связанные с компиляцией CSS;html
- все задачи связанные с компиляцией шаблонов HTML;generator
- все задачи связанные с генерацией кода/контента (не реализованы);images
- все задачи с обработкой изображений (не реализованы);js
- все задачи с компиляцией javascript (не реализованы);server
- все задачи связанные с запуском и перезапуском серверов.
Все выше перечисленные задачи подключаются в главном gulp файле - gulpfile.js
, который находится в корне проекта.
Генераторы:
Реализована таска gulp entity
, которая генерирует контролер, модель и представление для сущности.
gulp entity --e test,res,fd --a list,show,create,edit --m id,title,body
Аттрибуты:
--е - список сущностей, через зяаятую
--a - список экшенов (необязательный параметр, по умолчанию принимает: list,show )
--m - список свойств сущности (необязательный параметр, по умолчанию принимает: id,name )