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 )

Fafnur / markus